Chapter 5. Event Structures

Table of Contents
Key events
Pointer movement events
Pointer button events
Commands and information
Valuators
Expose events

All of the event structures are included by ggi/events.h.

Events are of type gii_event. It is a union of all of the LibGII event structures:

typedef union gii_event {

        uint8                   size;           /* size of this event   */

        gii_any_event           any;            /* access COMMON_DATA   */
        gii_cmd_event           cmd;            /* command/information  */
        gii_expose_event        expose;         /* exposure event       */
        gii_val_event           val;            /* valuator change      */
        gii_key_event           key;            /* key press/release    */
        gii_pmove_event         pmove;          /* pointer move         */
        gii_pbutton_event       pbutton;        /* pointer buttons      */

} gii_event;

All of the event structures begin with COMMON_DATA, which contains housekeeping information:

#define COMMON_DATA  \
        uint8   size;           /* size of event in bytes       */\
        uint8   type;           /* type of this event           */\
        sint16  error;          /* error (for replies)          */\
        uint32  origin;         /* origin device (etc)          */\
        uint32  target;         /* target device (etc)          */\
        struct timeval time     /* timestamp                    */

size

specifies the size of the given event (in bytes). Note that size is also accessable as the first member of gii_event as well.

type

is an enumeration of the possible types of LibGII events:

typedef enum gii_event_type {

        evNothing = 0,  /* event is not valid. (must be zero)   */

        evCommand,      /* report command/do action             */
        evInformation,  /* notification of new information      */

        evExpose,       /* exposure event                       */
        /* empty slot */

        evKeyPress=5,   /* key has been pressed                 */
        evKeyRelease,   /* key has been released                */
        evKeyRepeat,    /* automatically repeated keypress      */

        evPtrRelative,  /* pointer movements reported relative  */
        evPtrAbsolute,  /* pointer movements reported absolute  */
        evPtrButtonPress,       /* pointer button pressed       */
        evPtrButtonRelease,     /* pointer button released      */

        evValRelative,  /* valuator change (reported relative)  */
        evValAbsolute,  /* valuator change (reported absolute)  */

        evLast          /* must be less than 33                 */

}  gii_event_type;

Thus, by analyzing the contents of any.type, you can determine what the given event is, and select the appropriate member of the gii_event union to access to get at the event data.

error

is mainly there to round things up to a 32 bit boundary, but could be used to signal an error in a send-reply sequence.

origin

is a device handle; it distinguishes one input device from another, other than that there's no real meaning to the number.

target

is also a device handle, but for distinguishes input devices when sending events to an input device (e.g. via giiEventSend).

time

indicates when the event in question has been generated.

Key events

The gii_key_event structure represents key/button events from keyboards and other devices.

Event types:

evKeyPress
evKeyRepeatevKeyRelease

/*      key events should be used to report events obtained from keys and
**      other switches.
*/
typedef struct gii_key_event {

        COMMON_DATA;

        uint32  modifiers;      /* current modifiers in effect  */
        uint32  sym;            /* meaning of key       */
        uint32  label;          /* label on key         */
        uint32  button;         /* button number        */

} gii_key_event;

effect

specifies the modifiers currently in effect, for example, the shift keys on a keyboard.

sym

is the 'symbol' of the key, describing the resultant character produced by the key. This is roughly the 'label' on the key (described below) combined with the effect.

label

is the actual label which is present on the key in question, and the main 'symbol' on the key. label can be used as a generalized, portable keycode or scancode of the key.

button

is the button number distinguishing between the different buttons on the device. For example, on a keyboard it is a number from 0 to 127 (i.e. a 'scancode'), on a joystick it might be 1 to 4, and on a spaceorb it will be 1 to 8.

In GGI, key values and characters are specified in accordance to ggi/keyboard.h. They are organized in a similar way to Linux keysyms (but without the braindamage) and Unicode. However, in the GGI system, no key is guaranteed to exist; the key values are for identification only. Particularly, applications should not rely on their presence. Also, because not all keyboards are configured in the same way, GGI application are encouraged to allow user configuration of the keys used and not hardcode them.

GGI keysym system

A list of GGI keysyms and some macros for manipulating them are found in gii/keyboard.h.

To be done.