Visual Components

UJML Components can display visual elements.

A UJML component with visual elements is displayed in a state transition using a display-instance element contained by a display element. See Visual Elements, Components, display-instance element, display element. The visual component elements will only be visible on the device screen while the transition is active, even if the elements are in an active transition inside the component. See State Transitions.

The state transition containing the display element can be contained by another component instance, but that instance must also be displayed using display-instance before anything will actually appear on a device screen. This nesting may be as deep as you like, but the top level display-instance element must be located in an active state transition which is itself located in an application or partition module or nothing will be visible.

Updating visual elements inside of components

You update the visual elements inside of a component instance by changing or resetting state transitions in the same way you would for visual elements in application or partition modules. However, unless the component instance is referenced in an active state transition (as described above), nothing will display on the device screen. If the component instance is visible then updating its visual elements will update the device screen even if the state transition that contains the display-instance element referencing the component instance does not change.

However, you cannot access a state variable inside of a component instance from outside code so the component must either change its state in response to some event or must expose interface functions that change the state variable appropriately. See Interfaces.

Component positions are based on the containing element

The position of the visual elements in a component instance are offsets from the position of the visual element containing the display-instance element referencing the component instance. If the parent of the display-instance element is a display element, the offset starts at the top, left of the device screen. If the parent visual element of the display-instance element is a box element, or some other bounding rectangle visual element, the offset starts at the top and left positions of the containing element. See Position and Size.

Component instances can not be displayed multiple times

If the same component instance is referenced by display-instance elements in more than one active state transition, only the state transition with the highest Z-Order will show the component instance. See Z-Order.

If you need to show the same visual elements multiple times you must either support that from the component instance, or create multiple instances of the component.

Example

The following example shows a display block containing two component instances. It is part of the life.ujml sample.

Copy Code

<display>
    <!-- Draw Grid. -->
    <display-instance>
        <instance><eval>mGrid</eval></instance>
    </display-instance>
    <!-- Draw Menu (when not hidden). -->
    <display-instance>
        <instance><eval>mMenu</eval></instance>
    </display-instance>
</display>

The following example shows a state transition inside of a component referenced in the example above that is displaying a nested component instance, and also handling events from that component instance. It is part of the lifegrid.ujml sample.

Copy Code

<state var="sGridBlocks" index="*, *">
    <transition value="true">
        <display>
            <!-- Show a block. -->
            <display-instance>
                <instance>
                    <eval>
                        mBlocks[_state_index(0)][_state_index(1)]
                    </eval>
                </instance>
            </display-instance>
        </display>
        <events>
            <!--
                Fired when a block is clicked.
            -->
            <event name="ILifeBlock.onClick">
                <instance>
                    <eval>
                        mBlocks[_state_index(0)][_state_index(1)]
                    </eval>
                </instance>
                <script>
                    // Are we in edit mode?
                    if (!sRunning)
                    {
                        // Select the block.
                        ILifeGrid.selectBlock(_state_index(0), _state_index(1));
                        // Toggle the block.
                        ILifeGrid.toggleBlock(_state_index(0), _state_index(1));
                    }
                </script>
            </event>
        </events>
    </transition>
</state>

The following example shows a state transition inside of a component instance that is actually displaying the visual elements for the examples above. It is part of the lifeblock.ujml sample.

Copy Code

<state var="sShow">
    <transition value="&MODE_NORMAL;">
        <display>
            <!--
                Normal displays with one pixel of space around
                the left and top of the block to allow the background
                to show for a grid line. No border is displayed.
            -->
            <box>
                <x><eval>mX + 1</eval></x>
                <y><eval>mY + 1</eval></y>
                <width><eval>mWidth - 1</eval></width>
                <height><eval>mHeight - 1</eval></height>
                <fg><eval>mCurrBlockColor</eval></fg>
                <bg><eval>mCurrBlockColor</eval></bg>
                <event name="onSelect">
                    <script>
                        fireOnClick();
                    </script>
                </event>
            </box>
        </display>
    </transition>
    <transition value="&MODE_SELECTED;">
        <display>
            <!--
                Selected displays with a colored border that
                extends one pixel to the right and bottom.
            -->
            <box>
                <x><eval>mX</eval></x>
                <y><eval>mY</eval></y>
                <width><eval>mWidth + 1</eval></width>
                <height><eval>mHeight + 1</eval></height>
                <fg>&COLOR_BLOCK_SELECTED_FG;</fg>
                <bg><eval>mCurrBlockColor</eval></bg>
                <event name="onSelect">
                    <accelerators>
                        <key>FIRE</key>
                    </accelerators>
                    <script>
                        fireOnClick();
                    </script>
                </event>
            </box>
        </display>
    </transition>
 </state>

The following example shows how to update the state transition in the example above from a component's interface. It is part of the lifeblock.ujml sample.

Copy Code

<!--
    Causes the block to show as 'selected'.
-->
<function name="ILifeBlock.select" type="void">
    <script>
        _clear_state(sShow);
        sShow = &MODE_SELECTED;;
    </script>
</function>
<!--
    Causes the block to show normally.
-->
<function name="ILifeBlock.deselect" type="void">
    <script>
        _clear_state(sShow);
        sShow = &MODE_NORMAL;;
    </script>
</function>