[Previous] [Contents] [Index] [Next]


Data structure describing a key event


typedef struct Ph_ev_key_data {
    unsigned long  key_mods;
    unsigned long  key_flags;
    unsigned long  key_cap;
    unsigned long  key_sym;
    unsigned char  key_scan;
    unsigned char  key_zero1;
    unsigned short key_zero2;
    PhPoint_t      pos;
    unsigned short button_state;
} PhKeyEvent_t;


This structure describes a key event. It includes at least:

Some keys (e.g. Shift or Num Lock) modify other keys. When a modifier key is pressed or released, it's evaluated through a table and the key_mods field is updated accordingly. This evaluation is done before the key event is sent.

The key_mod is a combination of the following bits:

If the Shift key is pressed, the Shift modifier is on; if it's released, the Shift modifier is off. Because some keys occur twice on the keyboard, a key release doesn't guarantee that the corresponding modifier is off - the matching key may still be pressed.

Flags that indicate the status of the key:
The unique scan code produced by the key, without any modifiers. This member is valid only if Pk_KF_Cap_Valid is set in the key_flags.
The value of the key with modifiers applied to it. This member is valid only if Pk_KF_Sym_Valid is set in the key_flags.

This field holds the value that's used for text entry; it can also be used in a switch statement to determine a key's function.

The hardware-dependent scan code for the key. This member is valid only if Pk_KF_Scan_Valid is set in the key_flags.
The current mouse-pointer position.
The current state of the pointing-device buttons (i.e. which buttons are currently pressed):

All flags and key symbols are defined in <photon/PkKeyDef.h>.

Before using the key_cap, key_scan, or key_sym members, check the key_flags to make sure they're valid. The key_cap identifies the key that caused the event, while key_sym defines the character (or function key code) that the event carries, if any.

The keyboard is divided into groups, as dictated by ISO 9995. When a key in the text group is pressed and the Ctrl or Alt modifier is on, the keyboard driver doesn't generate a key_sym. If the key is in any other key group, the driver generates a key_sym.

For any key press event, there's a corresponding release event. For example, if you press the A key, key_cap is set to a in both the press and release (and any repeats), but only the press and repeats have a valid key_sym. Its value may be a, A, or perhaps an accented character or some symbol, depending on whether or not this keystroke completed a compose sequence.



See also:


Events chapter of the Photon Programmer's Guide

[Previous] [Contents] [Index] [Next]