Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Themed View Elements

Themed View elements define the layout and structure of components. For example, the page element is a top-level element that specifies the size and shape of the view of a component such as Title Bar.

The following tables define each of the Themed View elements together with attributes that may be applied to those elements.

Common attributes

Some attributes are common to all theme elements. Functionality for these attributes are implemented by the ThemeItem class. These attributes are listed below.

page

The top-level element. Specifies the size and shape of the view. The page element is implemented by the ThemePageItem class.

Attributes

rect

Draws a rectangle which may be filled. The rect element is implemented by the ThemeRectItem class.

Attributes

line

The line element is implemented by the ThemeLineItem class.

Attributes

text

Displays a string of text to the user.

The text element is implemented by the ThemeTextItem class.

Attributes

Content

The text element's content may be a literal string or an expression that returns a string which is used as the text for the element.

    <text name="literal">Hello, World!</text> <-- displays Hello, World!
    <text name="expression">@/My/Valuespace/Path/Text</text> <-- displays the text returned by the valuespace key /My/Valuespace/Path/Text

image

The image element is implemented by the ThemeImageItem class.

Attributes

anim

Shows an animation. Animations are costly in CPU and therefore power, so they must be used sparingly and only for transient elements with short active periods. The animation is defined by an image with frames layed out horizontally next to each other.

The anim element is implemented by the ThemeAnimationItem class.

Attributes

status

Displays an on/off status icon.

The status element is implemented by the ThemeStatusItem class.

Attributes

level

Displays a level such as battery charge. The different levels are represented by an image with frames layed out horizontally next to each other. As the level element is an extension of the anim element, all of anim's attributes also apply.

The level element is implemented by the ThemeLevelItem class.

Attributes

Content

Either a literal value or an expression can be specified for the content of the level attribute. If an expression is specified, the return value of the expression is used as the level's current value.

plugin

This is a special element which loads a plug-in to do the drawing. This is currently only used to display custom backgrounds in the home screen.

The plugin element is implemented by the ThemePluginItem class.

layout

This element does not do any drawing itself. Its role is to layout its child elements in a horizontal or vertical orientation. The default orientation is horizontal. If any of the child elements are shown/hidden then the remaining children will be laid out again.

The layout element is implemented by the ThemeLayoutItem class.

Attributes

exclusive

This element will display only one of its children. The children must be transient. The last child that is active will be displayed. All other children will be hidden. This is useful for sharing an area in different states. The exclusive element is implemented by the ThemeExclusiveItem class.

group

This element groups its children into a logical group. It primary role is to propagate mouse button (or stylus) clicks to all children.

The group element is implemented by the ThemeGroupItem class.

widget

This is a special purpose element. It is a place-holder for a custom widget in the user interface, such as a text input field.

The widget element is implemented by the ThemeWidgetItem class.

list

This is a special purpose element from the widget element. It contains functionality that extends the widget element to specifically support lists in themeing. template items can be defined under the list element to represent the appearance of the list's items.

The list element is implemented by the ThemeListItem class.

template

This is a special purpose element. It allows a hiearchy of theme items representing a visual look to be declared without actually creating an instance of them. Then, an actual instance of that hierarchy can be created dynamically and used to draw the visual look to some user interface component eg. a custom widget.

    <page>
        <text>This is my standard theme</text>
        <image src="hello"/>
        <template name="button">
            <image rect="0,0,0,0" src="buttonbg"/>
            <text rect="0,0,0,0" align="hcenter,vcenter">Click me.</text>
        </template>
    </page>

In the above example a template "button" is defined that declares a visual look consisting of an image and some text. The button template is not drawn as part of the theme, it just exists in its hierarchy as a convenient way to access it. You could create an instance of the "button" template using ThemeTemplateItem::createInstance() and then draw it to a custom widget using ThemedView::paint().

For more information also see the Themed Views: Templates documentation.