On-Key Events

On-Key events are fired when the user presses a button or releases a pressed button.

UJML provides On-Key events to capture button presses and releases. See Handling Events, onKeyDown Event, onKeyUp Event. On-Key events are defined using an event element inside of a visual element. See event, Visual Elements.

Note: If more than one visual element contains an On-Key event, the visual element with the highest z-order receives the event. See Z-Order.

Discovering which key was pressed or released

On-Key events are general and fire when any button is pressed or released. You can discover which button fired the event by calling the _getStringEventData() function with the &_EVENT_STRING_ONKEY; predefined entity. See _getStringEventData() function, Event Entities. The result is returned as a UJML key code. See Key Codes.

Figure 1. UJML On-Key events displayed by the events.ujml sample.

Example

The following example shows a state transition containing two invisible boxes; one capturing the onKeyDown event and one capturing the onKeyUp event. It is part of the events.ujml sample.

Copy Code

<state var="sKeyEvents">
    <transition value="true">
        <display>
            <box>
                <event name="onKeyDown">
                    <variables>
                        <var name="key" type="string"/>
                    </variables>
                    <script>
                        key = _getStringEventData(&_EVENT_STRING_ONKEY;);
                        showMessage(_strcat("onKeyDown: ", key));
                    </script>
                </event>
            </box>
            <box>
                <event name="onKeyUp">
                    <variables>
                        <var name="key" type="string"/>
                    </variables>
                    <script>
                        key = _getStringEventData(&_EVENT_STRING_ONKEY;);
                        showMessage(_strcat("onKeyUp: ", key));
                    </script>
                </event>
            </box>
        </display>
    </transition>
</state>