Nesting

Visual elements may contain other visual elements.

Most visual elements may contain child visual elements, nesting one inside the other. Child visual elements may also contain child visual elements to any depth. The position and size properties of a child element are relative to the parent element. See Position and Size.

Nesting limitations

Only visual elements that use a bounding rectangle for position and size may contain child visual elements. See Position and Size. However, any visual element may be contained by a parent element. There is no limit to visual element nesting other than device memory.

Clipping

Nested visual elements are not clipped to (drawn only inside) their parent element. It is possible for all or part of a nested visual element to positioned and drawn outside of the parent visual element.

Clipping is supported only in the following scenario: If the parent element supports the x-clip property element, and if the device supports clipping, and if x-clip is specified with a value of true, then any part of a child element which falls outside of the bounding rectangle of the parent element will not be drawn on the device screen. See x-clip.

Z-order

Child visual elements have a z-order higher than their parent, but only in relation to the parent. When there are multiple child elements, their z-order in relation to the parent element is determined by the order they occur in the source code. See Z-Order.

Figure 1. Several nested visual elements with different z-orders displayed by the visualelements.ujml sample.

Example

The following example shows how to display a round-box containing a label. The _text_width() and _text_height() functions are used to determine the size of the parent element in order to make certain that the child element does not draw outside the parent's borders. It is part of the helloworld2.ujml sample.

Copy Code

<round-box>
    <x>20</x>
    <y>20</y>
    <width>
        <eval>
            (&SPACING; * 2) +
                _text_width("&SALUTATION;", &_FONT_SIZE_LARGE;, &_FONT_STYLE_ITALIC;,
                &_FONT_FACE_SYSTEM;)
        </eval>
    </width>
    <height>
        <eval>
            (&SPACING; * 2) +
                _text_height(&_FONT_SIZE_LARGE;, &_FONT_STYLE_ITALIC;, &_FONT_FACE_SYSTEM;)
        </eval>
    </height>
    <fg>&_COLOR_SILVER;</fg>
    <bg>&_COLOR_RED;</bg>
    <x-arc-width>8</x-arc-width>
    <label>
        <text>&SALUTATION;</text>
        <x>&SPACING;</x>
        <y>&SPACING;</y>
        <fg>&_COLOR_WHITE;</fg>
        <size>&_FONT_SIZE_LARGE;</size>
        <style>&_FONT_STYLE_ITALIC;</style>
        <face>&_FONT_FACE_SYSTEM;</face>
    </label>
</round-box>

The following example shows how to display multiple-nested visual elements. It is part of the visualelements.ujml sample.

Copy Code

<display>
    <box>
        <x><eval>mRectX</eval></x>
        <y><eval>mRectY</eval></y>
        <width><eval>mRectWidth</eval></width>
        <height><eval>mRectHeight</eval></height>
        <fg><eval>makeColor(mBackColor, 255)</eval></fg>
        <bg><eval>makeColor(mBackColor, mOpacity)</eval></bg>
        <box>
            <x>10</x>
            <y>20</y>
            <width><eval>mRectWidth - 20</eval></width>
            <height><eval>mRectHeight - 30</eval></height>
            <fg><eval>mForeColor</eval></fg>
            <bg><eval>mForeColor</eval></bg>
            <label>
                <text><eval>mSingleLineText</eval></text>
                <x>10</x>
                <y>10</y>
            </label>
        </box>
        <label>
            <text><eval>mSingleLineText</eval></text>
            <x>5</x>
            <y>5</y>
            <fg><eval>mForeColor</eval></fg>
            <size><eval>mFontSize</eval></size>
            <style><eval>mFontStyle</eval></style>
            <face><eval>mFontFace</eval></face>
        </label>
        <image>
            <url>&IMAGE_URL;</url>
            <x>30</x>
            <y>30</y>
            <width>&IMAGE_WIDTH;</width>
            <height>&IMAGE_HEIGHT;</height>
        </image>
        <line>
            <x1><eval>mRectWidth</eval></x1>
            <y1>0</y1>
            <x2>0</x2>
            <y2><eval>mRectHeight</eval></y2>
            <fg><eval>makeColor(mBackColor, 255)</eval></fg>
        </line>
        <line>
            <x1>0</x1>
            <y1>0</y1>
            <x2><eval>mRectWidth</eval></x2>
            <y2><eval>mRectHeight</eval></y2>
            <fg><eval>makeColor(mBackColor, 255)</eval></fg>
        </line>
    </box>
</display>