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

unsigned longkey_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 longkey_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 longkey_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 longkey_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 shortkey_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_tpos

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

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