PhKeyEvent_t

Data structure describing a key event

Synopsis:

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;

Description:

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

key_mods

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:

• Pk_KM_Shift
• Pk_KM_Ctrl
• Pk_KM_Alt
• Pk_KM_AltGr
• Pk_KM_Shl3 - not used.
• Pk_KM_Mod6 - not used.
• Pk_KM_Mod7 - not used.
• Pk_KM_Mod8 - not used.
• Pk_KM_Shift_Lock
• Pk_KM_Ctrl_Lock
• Pk_KM_Alt_Lock
• Pk_KM_AltGr_Lock
• Pk_KM_Shl3_Lock - not used.
• Pk_KM_Mod6_Lock - not used.
• Pk_KM_Mod7_Lock - not used.
• Pk_KM_Mod8_Lock - not used.
• Pk_KM_Caps_Lock
• Pk_KM_Num_Lock
• Pk_KM_Scroll_Lock

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.

key_flags

Flags that indicate the status of the key:

• Pk_KF_Key_Down - the key has been pressed.
• Pk_KF_Key_Repeat - the key is repeating.
• Pk_KF_Scan_Valid - the key_scan member is valid.
• Pk_KF_Sym_Valid - the key_sym member is valid.
• Pk_KF_Cap_Valid - the key_cap member is valid.
• Pk_KF_Compose - a compose sequence is in progress.

key_cap

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.

key_sym

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.

key_scan

The hardware-dependent scan code for the key. This member is valid only if Pk_KF_Scan_Valid is set in the key_flags.

pos

The current mouse-pointer position.

button_state

The current state of the pointing-device buttons (i.e. which buttons are currently pressed):

• Ph_BUTTON_SELECT
• Ph_BUTTON_MENU
• Ph_BUTTON_ADJUST

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.

Classification:

Photon

See also:

PhEvent_t

Events chapter of the Photon Programmer's Guide