UJML allows you to create event handlers with scripting code to execute when the event is fired. UJML supplies a rich set of built-in events and fires these events to the appropriate event handlers while the application is executing to provide user interaction and track resource availability. Without event handlers, your UJML application can do very little.

A typical UJML program does some setup processing and then waits for events to occur. Each time an event occurs, the code attached to that event is executed, including any code branches caused by function calls and event transitions. Afterwards, UJML waits for another event to occur, and then processes it when one happens. See Execution Order. In this way, a UJML application is event-driven, processing one event at a time until it is unloaded. 

For this reason, you should structure your UJML application as a co-operating set of event handlers, turning them on or off as needed by enclosing them inside of state transitions. See State Transitions. For non-trivial examples of this in operation see the events.ujml sample, the lunarlander.ujml and the Visual Elements sample.

A element may contain an accelerators element to indicate what device buttons can fire the event, a variables element, and a script element containing scripting code to execute when the event is fired. See variables, script, Scripting. Only the script element is required for built-in events. For component events you must also provide an instance element to indicate which component instance you are handling events for and (if arguments are defined for the event in the interface) a parameters element. See instance, parameters. 

Note: The accelerators element is not appropriate for anything except selection events. 

Note: The instance and parameters elements are not appropriate for anything except component events.

Components can fire events declared in interfaces implemented by the component. See Components, Interfaces, Component Events. Component events may pass arguments to the event handler as parameters if the parameters are defined in the interface. Component events are fired using the interface name and the event name in 'dot notation' like this:

InterfaceName.eventName(arg1, arg2, arg3);

You define a component event handler in UJML using an event element containing scripting code to execute when the event fires contained by an events element inside of a transition element. See event, events, transition, Scripting. The event handler indicates the fully qualified name (the interface name and the event name in 'dot notation') of the component event to handle. An instance element to indicate which component instance you are handling events for and (if arguments are defined for the event in the interface) a parameters element specifies what arguments the event can recieve. See instance, parameters. The events element may contain multiple component event handlers, like this:

<events>
    <event name="InterfaceName.eventName">
        <instance><eval>componentReference</eval></instance>
        <parameters>
            <var name="arg1" type="int"/>
            <var name="arg2" type="boolean"/>
            <var name="arg3" type="string"/>
        </parameters>
        <script>
            doSomething(arg1, arg2, arg3);
        </script>
    </event>
    <event name="InterfaceName.otherEventName">
        <instance><eval>componentReference</eval></instance>
        <script>
            doSomethingElse();
        </script>
    </event>
</events>

UJML provides a rich set of built-in events that are fired for user interaction and resource availability. User interaction is provided with selection events, function key events and on-key events. See Capturing User Input. Resource management events track network activity and availability of resources. See Resource Management Events.

You define a built-in event handler in UJML using an event element containing scripting code to execute when the event fires. See event, Scripting. The event handler indicates the name of the built-in UJML event to handle. See Events. Event handlers for built-in events may be contained by most visual elements and by the resources element.

UJML provides the built-in onSelect event, which fires when the user selects a visual element on the device screen. See Visual Elements, onSelect. For devices that support a stylus or other pointing device this means that the onSelect event fires when the user taps the containing visual element on the screen. 

The event is tied to the visual element by the visual element containing the event handler. For example a small red box with an event handler looks like this:

<box>
    <x>10</x><y>10</y><width>60</width><height>40</height>
    <fg>&_COLOR_RED;</fg><bg>&_COLOR_RED;</bg>
    <event name="onSelect">
        <script>foo("Bar");</script>
    </event>
</box>

You can associate a device button with an onSelect event by using an accelerators element inside the event element. See accelerators, key. The onSelect event fires when the key is pressed and released. For example, you can extend the small red box example above to also respond to clicking the FIRE button like this:

<box>
    <x>10</x><y>10</y><width>60</width><height>40</height>
    <fg>&_COLOR_RED;</fg><bg>&_COLOR_RED;</bg>
    <event name="onSelect">
        <accelerators>
            <key>FIRE</key>
        </accelerators>
        <script>foo("Bar");</script>
    </event>
</box>

A common scenario is an event handler without a visual representation. This is easily created in UJML by containing the event handler in an 'invisible' visual element; usually a box element with default position and size. For example this box will not display on the screen, but the FIRE button still fires the event:

<box>
    <event name="onSelect">
        <accelerators>
            <key>FIRE</key>
        </accelerators>
        <script>foo("Bar");</script>
    </event>
</box>

A special case of visual elements and the selection event is function key event handlers. See Function Keys. This ties a selection event handler to a special device key and may have a representation on the device screen that is not part of the usual visual elements in a UJML application. For example, you can display the text 'Back' in a special area on the device screen and exit your application when the F1 button is pressed like this:

<fn>
    <text>Back</text>
    <event name="onSelect">
        <accelerators>
            <key>F1</key>
        </accelerators>
        <script>_unload();</script>
    </event>
</fn>

Most event handlers for built-in events must be contained by a visual element of some kind. Because only one event element is allowed per visual element, the common scenario is to contain each non-selection event in an 'invisible' box as described above, but without the accelerator key. For example:

<box>
    <event name="onRequestStarted">
        <script>downloadStarted(_getStringEventData(&_EVENT_STRING_ONREQUEST_URL;));</script>
    </event>
</box>
<box>
    <event name="onRequestSucceeded">
        <script>downloadComplete(_getStringEventData(&_EVENT_STRING_ONREQUEST_URL;));</script>
    </event>
</box>

There are exceptions to the one built-in event handler per visual element rule. These are the resource availability events, which are contained by a resource element. For example:

<resource>
    <url><eval>mSoundURL</eval></url>
    <event name="onResourceAvailable">
        <script>playSound(mSoundURL);</script>
    </event>
    <event name="onResourceError">
        <script>showError(mSoundURL);</script>
    </event>
</resource>

When more than one event handler exists for the same event name, only the handler inside the visual element with the highest z-order will receive the event. See Z-Order.

The scripting code in an event handler may change variables and state variables in the same module scope as the event handler. See Data Scoping and Sharing. This means that an event handler may have side effects because the module is in a different state after the event was fired.

Scripting, Data Scoping and Sharing, State Transitions, Visual Elements, Z-Order, Function Keys, Events, Components, Interfaces, Component Events, Resource Management Events, <event>, <events>, <transition>, <variables>, <script>, <instance>, <parameters>