NAME
gii_key_event - LibGII key events
SYNOPSIS
#include <ggi/events.h>
typedef struct gii_key_event {
COMMON_DATA;
uint32_t modifiers;
uint32_t sym;
uint32_t label;
uint32_t button;
} gii_key_event;
DESCRIPTION
The gii_key_event structure represents key/button events from keyboards
and other devices.
GENERATED EVENTS
evKeyPress
The key specified in the structure is pressed. Not repeatedly
produced while holding down the key.
evKeyRelease
A key specified in the structure is released.
evKeyRepeat
Makes sense when dealing with character input. A key is being
held down and the character should be processed at intervals
when the key is held down.
The key repeat rate and the delay before repeat is unspecified
and depends on the user’s environment.
STRUCTURE MEMBERS
modifiers
Result of bitwise-or of the following flags, indicating certain
shift states:
· GII_MOD_SHIFT
· GII_MOD_CTRL
· GII_MOD_ALT
· GII_MOD_META
· GII_MOD_SUPER
· GII_MOD_HYPER
· GII_MOD_ALTGR
· GII_MOD_CAPS
· GII_MOD_NUM
· GII_MOD_SCROLL
sym The symbol of the key, which is the resultant character produced
by the key. This is roughly a transformation of the label with
the current modifiers. It also depends on the user’s key
configuration.
label The actual label visible on the key in question. This is either
the symbol produced when there are no modifiers or it is the
most prominent symbol on that key. For example:
· The numeric keys on top of the letter keys on a standard PC
keyboard have label values which are the digit characters in
ASCII.
· The English letter keys on a keyboard are represented by A
through Z in label. Although in their unshifted state these
keys produce lowercase letters, the keycaps are printed with
uppercase by convention, so this is what LibGII returns.
label can be used as a generalized, portable keycode or scancode
of the key (That is, if the documentation for an applications
says that something is is mapped to key y, it is, even for
German keyboard, where y and z are swapped)
button 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.
If an application is interested in what physical keys are pressed and
released (most games for example), read the label field. Usually the
modifiers in effect are irrelevant for these applications (however, for
non-alphanumeric symbols like + and -, it is wise to check the sym
field instead of label as they are accessed using shifts on some
keyboard configurations).
If an application wants a stream of characters (for text input), it
should read the sym field.
GGI KEYSYM SYSTEM
In GGI, key values are defined in ggi/keyboard.h. They are basically
Unicode characters with some extensions:
Keys which are not represented by codepoints in the Unicode standard
(such as the numeric keypad keys) are assigned codepoints in the
private range. Applications should use the GIIK_ #defines for
representing these keys. These codepoints are used in label, but they
can also occur in sym when the symbol is not any character (e.g. arrow
keys, function keys).
The GIIUC_ #defines represent normal Unicode characters. The #defines
are interchangeable with their corresponding codepoint scalars and
their use is optional. However, it is recommended to use them for the
symbols GIIUC_BackSpace, GIIUC_Return, GIIUC_Escape and GIIUC_Delete.
Important: In the LibGII 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, applications
are encouraged to allow user configuration of the keys used and
not hard-code their values.
SEE ALSO
gii_event(3)