Component Events

Components can fire events for external code to handle, similar to built-in UJML events.

Components can fire events declared in Interfaces implemented by the component, which external code can handle in a way similar to UJML events. See Components, Interfaces. Component events may pass arguments to the event handler as parameters if the parameters are defined in the interface.

Declaring events

Events are declared with an event element inside of an events element contained by an interface element. See interfaces element, interface element, events element.

A simple interface definition with one function (foo) and one UJML event (bar) would look like this:

Copy Code

<ujml>
   <interfaces>
      <interface name="IExample">
         <functions>
            <function name="foo" type="int">
               <parameters>
                  <var name="x" type="int">
                  <var name="y" type="int">
                  <var name="name" type="string">
               </parameters>
            </function>
         </functions>
         <events>
            <event name="bar">
               <parameters>
                  <var name="count" type="int">
                  <var name="name" type="string">
               </event>
            </function>
         </events>
      </interface>
   </interfaces>
</ujml>

Firing events

Component events are fired from UJML script using the interface name and the event name in 'dot notation'. Firing the event is similar to calling a function, including passing parameters, except that events do not have a return value.

For example:

Copy Code

InterfaceName.eventName(arg1, arg2, arg3);

Declaring an event handler for a component event

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 receive. See instance, parameters. The events element may contain multiple component event handlers, like this:

Copy Code

<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>

Remarks

An event handler is connected to the component instance when the state transition containing the event handler is activated. This means that changing the component variable in the instance tag for the event to a different component instance after the state transition becomes active does not change which component instance will fire the event.

Example

The following example shows an interface event declaration. It is part of the itimer.ujmi sample.

Copy Code

<events>
    <!--
        Fired after all listeners have been serviced for
        a single tickID.
    -->
    <event name="onTick">
        <parameters>
            <var name="timerID" type="int"/>
        </parameters>
    </event>
</events>

The following example shows how to fire the event declared above. It is part of the timer.ujml sample.

Copy Code

// Fire event
ITimerSource.onTick(mTimerID[idx]);

The following example shows how to handle the event declared above. It is part of the lifegrid.ujml sample.

Copy Code

<events>
    <!--
        Timer component event handler. onTick is Fired after
        all listeners have been serviced for a single tickID.
    -->
    <event name="ITimerSource.onTick">
        <instance><eval>mTimers</eval></instance>
        <parameters>
            <var name="timerID" type="int"/>
        </parameters>
        <script>
            // Update header?
            if (timerID == &UPDATE;)
            {
                mGeneration++;
                _clear_state(sGridHeader);
                sGridHeader = sGridHeader;
            }
        </script>
    </event>
</events>