class KeyboardEventHandler

Defined in: C4Engine.h

The KeyboardEventHandler class encapsulates a keyboard event handler function.

Definition

class KeyboardEventHandler : public ListElement<KeyboardEventHandler>

Constructor

KeyboardEventHandler(HandlerProc *proc, void *cookie = nullptr);

Parameters

`proc`	The procedure to invoke when a keyboard event occurs.
`cookie`	The cookie that is passed to the event handler as its last parameter.

Description

The KeyboardEventHandler class encapsulates a procedure 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 procedures corresponding to all installed keyboard event handlers are invoked. The HandlerProc type is defined as follows.

typedef bool HandlerProc(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 values.

`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 the Unicode value corresponding to the key that was involved in the event. 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 value.

kModifierKeyShift The shift key was held down.

The cookie parameter is the value passed to the KeyboardEventHandler constructor.

The value returned by the handler specifies whether the keyboard event was successfully handled. If the handler returns true, then the keybaord event is considered handled, and no further keyboard event handlers will be called for the same event. If the handler 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.