PhKeyEvent_t

Data structure describing a key event

Synopsis:

See below.

Description:

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

unsigned long 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_mods is a combination of the following bits:

• Pk_KM_Shift
• Pk_KM_Ctrl
• Pk_KM_Alt
• Pk_KM_AltGr
• Pk_KM_Shl3
• Pk_KM_Mod6
• Pk_KM_Mod7
• Pk_KM_Mod8
• Pk_KM_Shift_Lock
• Pk_KM_Ctrl_Lock
• Pk_KM_Alt_Lock
• Pk_KM_AltGr_Lock
• Pk_KM_Shl3_Lock
• Pk_KM_Mod6_Lock
• Pk_KM_Mod7_Lock
• Pk_KM_Mod8_Lock
• 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.

unsigned long 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; this bit is set only on a key press, not a release.
• Pk_KF_Cap_Valid — the key_cap member is valid.
• Pk_KF_Compose — a compose sequence is in progress.

unsigned long 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.

unsigned long 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.

unsigned short 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.

PhPoint_t pos

A PhPoint_t structure that specifies the current mouse-pointer position.

unsigned short 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.

If you're looking for printable characters (i.e. textual input as opposed to “raw” key presses and releases), look at key_sym (after throwing away any events that don't have the Pk_KF_Sym_Valid flag) and ignore the modifiers. Also, ignore symbols in the 0xF0xx range; those are nonprintable control characters, such as Home, PageUp, and function keys.

If you're looking for cursor keys or function keys and don't care about the difference between the two PageDown keys or about interpreting the NumLock flag yourself, also look at key_sym (again, after ignoring events that don't have a valid symbol). Look at the modifiers if you want to recognize combinations such as Shift-Home or Ctrl-PageUp.

In the rare cases where you need to distinguish between the two PageDown keys (Pk_Pg_Down and Pk_KP_3), look at key_cap (discarding any events that don't have the Pk_KF_Cap_Valid flag). But beware: if an event contains the symbol 3, it's probably wiser to assume that the person meant the number 3 rather than PageDown. Since key releases normally contain a valid cap, you'll also need to look at the Pk_KF_Key_Down flag to distinguish between presses and releases (and possibly the Pk_KF_Key_Repeat flag if you want to distinguish between presses and repeats).

If you need to detect keystrokes such as Ctrl-A or Alt-B, you have no choice; those normally don't carry a symbol, and you need to look at the key_cap and the other flags. Actually, if an Alt-B keystroke does carry a symbol, it's probably safer to assume that it wasn't meant to be also recognized as an Alt-B — there might be keyboard mappings that map Alt-B to some special symbol that has nothing to do with Alt-B.

Classification:

Photon

See also:

PhEvent_t, PhPoint_t, PhPointerEvent_t

Events chapter of the Photon Programmer's Guide