Selection Events

Selection events are fired when the user selects a visual element with a pointing device or clicks a related accelerator button.

Description

UJML provides selection events to the user interacting with a visual element and/or clicking a button on the device. See Handling Events, Visual Elements, onSelect Event. Selection events are defined using an event element inside of a visual element. See event.

Selecting visual elements

To make a visual element selectable, all you need to do is include an event element inside the visual element definition. This makes the visual element 'live' so that the event is fired when the visual element is clicked using a pointing device.

Note: If the visual element is completely hidden behind another visual element the user cannot click it. See Z-Order.

Accelerators

To associate a button click with an onSelect event, you use an accelerators element containing key elements for each device button to associate. See accelerators, key. The key value must be a valid UJML key code. See Key Codes.

Note: If more than one visual element contains an event with the same accelerator key code, the visual element with the highest z-order receives the event. See Z-Order.

Using invisible boxes for accelerator-only events

In some cases you will want to capture button clicks only, without showing a visual element on the screen. This is easily done using a box element with no position or size elements. In this case the only child of the box element is an event element.

Example

The following example shows a state transition containing a visual element (a box containing a triangle) and a related onSelect event. The accelerator is the 'UP' button. It is part of the events.ujml sample.

Copy Code

<state var="sButton" index="&BUTTON_UP;">
    <transition value="true">
        <display>
            <box>
                <x><eval>mArrowUpPos[&POS_X;]</eval></x>
                <y><eval>mArrowUpPos[&POS_Y;]</eval></y>
                <width>&BUTTON_WIDTH;</width>
                <height>&BUTTON_HEIGHT;</height>
                <fg>&_COLOR_SILVER;</fg>
                <bg><eval>mButtonBackColor</eval></bg>
                <event name="onSelect">
                    <accelerators>
                        <key>UP</key>
                    </accelerators>
                    <script>
                        showMessage("onSelect: UP");
                        flashButton(&BUTTON_UP;);
                    </script>
                </event>
                <polygon>
                    <x>&OFFSET;</x>
                    <y><eval>&BUTTON_HEIGHT; - &OFFSET; - 1</eval></y>
                    <x><eval>&BUTTON_WIDTH; - &OFFSET; - 1 </eval></x>
                    <y><eval>&BUTTON_HEIGHT; - &OFFSET; - 1 </eval></y>
                    <x><eval>&BUTTON_WIDTH; / 2</eval></x>
                    <y>&OFFSET;</y>
                    <fg><eval>mButtonForeColor</eval></fg>
                    <x-bg><eval>mButtonForeColor</eval></x-bg>
                </polygon>
            </box>
        </display>
    </transition>
</state>

The following example shows four different invisible boxes, each with an event for a directional button. It is part of the helloworld4.ujml sample.

Copy Code

<box>
    <event name="onSelect">
        <accelerators>
            <key>LEFT</key>
        </accelerators>
        <script>
            mPosX = mPosX - &MOVEMENT;;
            if (mPosX &_LT; 0)
            {
                mPosX = 0;
            }
            _clear_state(sHelloBox);
            sHelloBox = true;
        </script>
    </event>
</box>
<box>
    <event name="onSelect">
        <accelerators>
            <key>RIGHT</key>
        </accelerators>
        <script>
            mPosX = mPosX + &MOVEMENT;;
            if (mPosX &_GT;
                (_getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;) - mWidth))
            {
                mPosX = _getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;) - mWidth;
            }
            _clear_state(sHelloBox);
            sHelloBox = true;
        </script>
    </event>
</box>
<box>
    <event name="onSelect">
        <accelerators>
            <key>UP</key>
        </accelerators>
        <script>
            mPosY = mPosY - &MOVEMENT;;
            if (mPosY &_LT; 0)
            {
                mPosY = 0;
            }
            _clear_state(sHelloBox);
            sHelloBox = true;
        </script>
    </event>
</box>
<box>
    <event name="onSelect">
        <accelerators>
            <key>DOWN</key>
        </accelerators>
        <script>
            mPosY = mPosY + &MOVEMENT;;
            if (mPosY &_GT;
                (_getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;) - mHeight))
            {
                mPosY = _getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;) - mHeight;
            }
            _clear_state(sHelloBox);
            sHelloBox = true;
        </script>
    </event>
</box>