Visual elements are pictures, shapes and text displayed on a device screen. These are defined with a rich set of UJML tags representing primitive graphics objects such as boxes, labels, and images which may be combined, colored, and positioned as needed. 

All visual element tags must be contained within a display element or nested within another visual element. See display, Nesting. When a transition element containing a display element activates, the visual and non-visual sub-elements of the display element are evaluated in the order they occur in the UJML source code. See State Transitions, transition. This means any code that changes variable values (for example in a function call) has side-effects on other sub-elements referencing those variables with a later execution order. 

Figure 1. A self-overlapping polygon displayed by the visualelements.ujml sample.

All visual elements support some form of user interaction using selection events. Edit Boxes support text entry on a device-specific basis. See Capturing User Input, Selection Events, Edit Boxes.

All visual elements have property sub-elements which describe the position and size of the visual element on the screen. See Position and Size. Visual elements that display text also allow you to specify the string to display and the font attributes to use. See Text and Fonts. Labels and shapes allow you to specify the color of the visual element. See UJML Colors. Other properties are specific to a particular visual element.

Visual elements differ in how their position and size properties work; either they use a bounding rectangle or are line-oriented. See Position and Size. In general, visual elements fall into the following five categories:

• Shape: A two-dimensional graphic primitive like a rectangle or a line.
• Image: A bit-mapped picture.
• Text: A text display primitive like a label.
• Edit: A text editing control.
• Special Purpose: Serves some special purpose and works differently than all other visual elements.

The order (top to bottom) of visual elements on a device screen is determined by z-order and element nesting. See Z-Order, Nesting. Visual elements are either active, meaning that they are visible on the device screen, or inactive, meaning that they are not visible. Visual elements contained by a display element in the body of a UJML application are always active. Visual elements contained by a display element within a transition element are only active when the transition occurs and become inactive again when the state transitions out. See State Transitions. 

Each visual element is declared separately and you cannot add new visual elements at run time. For the simple scenario of a box element inside of a state transition, that box is only displayed in one place on the screen when the transition is active and goes away when the state transitions out. In this case there is no way to repeat the box without declaring a separate box.

UJML provides two ways of repeating visual elements which are only declared once. 

The first method uses a state variable array with a 'default' state. To do this, you replace the element reference in the index attribute of the state element with asterisks ('*') for each dimension. For example, '<state var="sFoo" index="*,*">'. In this case, the visual elements (and other transition elements) contained in that state element apply to all elements of the state variable array. See State Transitions. 

The second method uses the template element to define a set of visual elements that may be repeated at will wherever you insert an expand element. See Visual Element Templates. Templates have other benefits as well, including smaller executable code sizes.

UJML does not automatically fill the device screen background. This means that a visual element displayed by a state transition which then becomes inactive may continue to show on the screen unless the UJML application is painting something else at that location. For this reason, it is always a good idea to use a colored backdrop which fills the screen in your applications. See State Transitions. 

Note: The background.ujms sample is an example of a reusable component which fills the screen background. 

Support for visual elements may vary from device to device. Some visual elements, such as x-oval, may not be supported at all. Other elements, such as round-box or polygon, may display differently. UJML provides you with functions to determine device support and adjust your application to the device capabilities at run time. See Device Independence, Determining Device Context. Devices also provide a wide variety of screen sizes, dimensions, and color capability. UJML also provides functions to determine these factors at run time, and adjust your application accordingly. 

Note:The visualelements.ujml sample shows every possible type of visual element, you can experiment with it to see how these display on different devices.

State Transitions, Capturing User Input, Selection Events, Edit Boxes, Device Independence, Determining Device Context, Components, visualelements.ujml, background.ujms