Reference for the Mosaic class Core::KeyPressHandler

Core::KeyPressHandler
CharCode
Code
Continue
Down
Enabled
Filter
OnHold
OnPress
OnRelease
Repetition
RepetitionCount
Time

SEE ALSO

Using the Key Handler to process keyboard and button input events.

The class Core::KeyPressHandler provides a universal keyboard event handler able to process key press and release events. It compares the received key codes with the value of the property Filter and if the codes do match the filter condition, sends signals to the slot methods stored in the OnPress, OnHold and OnRelease properties.

Keyboard handlers can be created at the design time only. You can simply drag-and-drop them from the Embedded Wizard Gallery into the Composer window where you are editing the GUI component. If necessary several keyboard handlers can be added to the component. For example, one handler can react to the 'Enter' key and the other to the 'Exit' key. The order in which the handlers will process the events corresponds to their Z-order. You can verify and modify this Z-order in the Embedded Wizard Inspector. Please note, keyboard handlers created at the runtime with the Chora 'new' operator will not work!

The handler provides several variables with details of the received keyboard event, like the key code (Code or CharCode), whether the user has pressed or released the key (Down), etc. These variables can be evaluated in the implementation of the slot method.

The property Enabled can be used to activate/deactivate the keyboard handler. Disabled handler will not react to the events.

var char CharCode;

The variable 'CharCode' stores the UNICODE character code of the pressed or released character. For key codes the variable is initialized with '\x0000' and the key code is stored in the variable Code.

var Core::KeyCode Code;

The variable 'Code' stores the code of the pressed or released key. For UNICODE characters the character code is stored in the CharCode variable and the variable Code is initialized with the value Core::KeyCode.NoKey.

var bool Continue;

The variable 'Continue' determines whether the just processed event should be passed to the next handler or whether it should be signed as handled. Per default, all processed events will be signed as handled. However, if a slot method invoked by this handler decides to not handle the event, it can assign 'true' to this variable. In this manner, the event dispatching can continue as if the handler had not been activated.

var bool Down;

The variable 'Down' determines whether the user has pressed or released the key. If this variable == 'true' the key has been pressed.

property bool Enabled = true;

The property 'Enabled' determines whether the handler is able to react to user inputs. Disabled handlers will ignore any user interactions and will not send any signals to the assigned slot methods.

property Core::KeyCode Filter = Core::KeyCode.AnyKey;

The property 'Filter' stores the key code or the category of key codes to process by this handler. Keyboard events with key codes not matching this filter will be ignored.

property slot OnHold = null;

The property 'OnHold' can refer to a slot method, which should be invoked by the handler when the user continues pressing a key with a code matching the filter condition Filter.

Within the slot method the current state of the handler variables like Code, CharCode, Down, Repetition. etc. can be evaluated.

Please note, the frequency with it the repetition events are delivered does depend on the target system and its particular keyboard drivers. If the keyboard driver doesn't support the repetition events, the handler will receive only the OnPress and OnRelease events without any OnHold.

property slot OnPress = null;

The property 'OnPress' can refer to a slot method, which should be invoked by the handler when the user has pressed a key with a code matching the filter condition Filter.

Within the slot method the current state of the handler variables like Code, CharCode, Down, Repetition, etc. can be evaluated.

If the slot method decides to ignore the event, it can assign 'true' to the variable Continue. This causes the framework to pass the event to the next following handler or GUI component. With it, however, the handler will not receive any corresponding OnHold nor OnRelease events.

property slot OnRelease = null;

The property 'OnRelease' can refer to a slot method, which should be invoked by the handler when the user has released the previously pressed key with the code matching the filter condition Filter.

Within the slot method the current state of the handler variables like Code, CharCode, Down, Repetition, etc. can be evaluated.

var bool Repetition;

The variable 'Repetition' determines whether the user continues pressing the key.

var int32 RepetitionCount = 0;

The variable 'RepetitionCount' stores the number of key down repetition events received by this handler after the user has pressed a key.

Just after pressing a key the variable RepetitionCount is 0. Later every repetition event causes the variable to be incremented. In this manner the implementation of the OnHold or OnRelease slot method can determine how long the user presses the key.

Please note, the frequency with it the repetition events are delivered does depend on the target system and its particular keyboard drivers. If the keyboard driver doesn't support the repetition events, the handler will receive only the OnPress and OnRelease events without any OnHold.

var uint32 Time;

The variable 'Time' stores the time in milliseconds when the user has triggered the event.