C4 Engine
C4 Engine API Documentation

class KeyboardEventHandler

Defined in:  C4Engine.h
The KeyboardEventHandler class encapsulates a keyboard event handler callback function.
Definition

class KeyboardEventHandler : public ListElement<KeyboardEventHandler>

Constructor

KeyboardEventHandler(HandlerCallback *callback, void *cookie = nullptr);

Parameters
callback The callback function to invoke when a keyboard event occurs.
cookie The cookie that is passed to the event callback function as its last parameter.
Description
The KeyboardEventHandler class encapsulates a callback function that is invoked when a keyboard event occurs. Once an instance of the KeyboardEventHandler class has been constructed, it can be installed by calling the Engine::InstallKeyboardEventHandler function.

When a keyboard event occurs, the callback functions corresponding to all installed keyboard event handlers are invoked. The HandlerCallback type is defined as follows.

typedef bool HandlerCallback(const KeyboardEventData *eventData, void *cookie);

The eventType field of the KeyboardEventData structure specifies what type of keyboard event occurred and can be one of the following constants.
kEventKeyDown A key was pressed. If a key is held down long enough to trigger auto-repeat, then this event is received each time a character is generated.
kEventKeyUp A key was released.
kEventKeyCommand A command key combination was pressed. This means the user held in the control key (under Windows) or the command key (under Mac OS) while pressing another key.
The keyCode field of the KeyboardEventData structure specifies either the Unicode value corresponding to the character that was involved in the event or one of the following values for special keys.
kKeyCodeEnter The enter key (return key on the Mac).
kKeyCodeEscape The escape key.
kKeyCodeTab The tab key.
kKeyCodeLeftArrow The left arrow key.
kKeyCodeRightArrow The right arrow key.
kKeyCodeUpArrow The up arrow key.
kKeyCodeDownArrow The down arrow key.
kKeyCodePageUp The page up key.
kKeyCodePageDown The page down key.
kKeyCodeHome The home key.
kKeyCodeEnd The end key.
kKeyCodeDelete The delete key.
kKeyCodeBackspace The backspace key.
kKeyCodeF1 The F1 key.
kKeyCodeF2 The F2 key.
kKeyCodeF3 The F3 key.
kKeyCodeF4 The F4 key.
kKeyCodeF5 The F5 key.
kKeyCodeF6 The F6 key.
kKeyCodeF7 The F7 key.
kKeyCodeF8 The F8 key.
kKeyCodeF9 The F9 key.
kKeyCodeF10 The F10 key.
kKeyCodeF11 The F11 key.
kKeyCodeF12 The F12 key.
Special keys always have codes in the ranges [0x01, 0x1F] or [0x80, 0x9F], and keyboard event handlers should not attempt to handle codes in these ranges as ordinary characters.

The modifierKeys field specifies which modifier keys were held down when the event occurred. It can be zero or a combination (through logical OR) of the following values.
kModifierKeyShift The Shift key was held down.
kModifierKeyControl The Control key (Command key on the Mac) was held down.
kModifierKeyAlternate The Alternate key (Option key on the Mac) was held down.
The cookie parameter is the value passed to the KeyboardEventHandler constructor.

The value returned by the callback function specifies whether the keyboard event was successfully handled. If the callback function returns true, then the keybaord event is considered handled, and no further keyboard event handlers will be called for the same event. If the callback function returns false, then the event is passed to the next keyboard event handler.

A keyboard event handler is uninstalled by destroying its associated class instance.
Base Classes
ListElement<KeyboardEventHandler> Used internally to store all instances of KeyboardEventHandler in a list.