Data structure describing a key event
This structure describes a key event. It includes at least these members:
The key_mods 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.
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.
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.
PhEvent_t, PhPoint_t, PhPointerEvent_t
Events chapter of the Photon Programmer's Guide