Home · All Classes · Grouped Classes · Annotated · 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.

AttributeDescription
activeThe active state of the element. The value of this may be an expression. See Showing/Hiding Elements.
expandingWhether this element may expand to fill any available space. Only applies when element is within a layout element. See the documentation of layout for details.
interactiveSee Interactive Elements.
messageSends a specified message to a specified channel or service. Currently only supported for interactive elements through the onlick attribute. See Interactive Elements.
nameThe name of the element.
rectThe size and position of the element. See Positioning Elements.
transientIf set to "yes" the item can change. See Showing/Hiding Elements.
vspathThe valuespace path for which expressions appearing in this element are relative to. See Expressions and Valuespace.
onclickChanges the value of attributes when the item is clicked. See Interactive Elements.
onfocusChanges the value of attributes when the item has the focus. See Interactive Elements.

page

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

Attributes

AttributeDescription
backgroundThe image used as the background.
baseThe base directory where the image data can be found relative to $QPEDIR/pics.
keypadIf true, the item is active in keypad mode.
maskThe mask used to set the widget shape. This is useful for the title and context bar.
orientationThe page direction ("vertical" or "horizontal").
rectThe size of the view. The x and y coordinates are ignored.
colorSee Specifying Colors.
stretchThe stretch points for the mask. See Stretching Images.
transparentSet to "yes" if the page is transparent.

rect

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

Attributes

AttributeDescription
alphaAdd an alpha channel with value in the range 0-255
brushThe color to fill the interior with. See Specifying Colors.
colorThe color of the line. See Specifying Colors.
keypadIf true, the item is active in keypad mode.
transparentSet to "yes" if the item is transparent.

line

The line element is implemented by the ThemeLineItem class.

Attributes

AttributeDescription
colorThe color of the line. See Specifying Colors.

text

Displays a string of text to the user.

The text element is implemented by the ThemeTextItem class.

Attributes

AttributeDescription
alignThe text alignment. See Alignment.
boldWhen set to "yes" the text will be bold.
colorThe color of the text. See Specifying Colors.
elidedSpecifies where the ellipsis should appear when displaying a text that doesn't fit. The value can be "left", "middle" or "right".
fontThe font used to display the text.
formatWhen set to "RichText" the text will be rendered as richtext (Qt HTML subset). When set to "PlainText" the text will be rendered as plain text. If unspecified, the format will be detected automatically based on the presence of html tags.
outlineThe color to draw the outline around the text. See Specifying Colors.
shadowPaints a shadow under the text to make it more visible when the background is textured. The value is a number in the range 0 - 255.
shortWhen set to "yes" Qtopia will supply a short version of the text, for example instead of "3 new messages", only "3" will be set.
sizeThe font size in points.

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

AttributeDescription
alphaAdd an alpha channel with value in the range 0-255.
colorA color to blend with the image. This allows images to be colored to match the selected color scheme. See Specifying Colors.
keypadIf true, the item is active in keypad mode.
orientationThe direction to stretch the image ("vertical" or "horizontal").
scaleIf set to "yes", scale the image to fit the rect. It is possible to scale in one direction only with "vertical" or "horizontal".
srcThe image to be drawn. This may be a literal reference to a file or an expression returning a string which is a reference to a file.
stretchThe stretch points for the image. See Stretching Images.
tileIf set to "yes", tiles the entire rect with the image. This attribute is ignored if scale is set.
transparentSet to "yes" if the image is transparent.

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

AttributeDescription
alphaAdd an alpha channel with value in the range 0-255.
colorA color to blend with the animation. This allows images to be colored to match the selected color scheme. See Specifying Colors.
countThe number of frame in the image.
delayThe delay between frames.
loopThe frame to loop back to when the last frame is reached.
looprevThe frame to loop back to, in reverse order, when the last frame is reached.
playWhether the animation should play. The default is "no", but if a literal "yes" is specified the animation starts playing immediately. If an expression is specified, the animation will play whenever the return value of the expression is true.
scaleIf set to "yes", scale the animation to fit the rect. It is possible to scale in one direction only with "vertical" or "horizontal".
srcThe image containing the frames.
widthThe width of a frame.

status

Displays an on/off status icon.

The status element is implemented by the ThemeStatusItem class.

Attributes

AttributeDescription
alphaonThe alpha level of the image in the on state (0-255).
alphaoffThe alpha level of the image in the off state (0-255).
coloronA color to blend with the image in the on state. See Specifying Colors.
coloroffA color to blend with the image in the off state. See Specifying Colors.
imageonThe filename of the image representing the on state.
imageoffThe filename of the image representing the off state.
onWhether the item is on or off. The default is "on", but if a literal "off" is specified the status item is off by default. If an expression is specified, the status item is on when the result of the expression is true and off when the result is false.
scaleIf set to "yes", scale the status to fit the rect. It is possible to scale in one direction only with "vertical" or "horizontal".

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

AttributeDescription
alphaAdd an alpha channel with value in the range 0-255.
colorA color to blend with the level. This allows images to be colored to match the selected color scheme. See Specifying Colors.
countThe number of frames.
delayThe delay between frames.
loopThe frame to loop back to when the last frame is reached.
looprevThe frame to loop back to, in reverse order, when the last frame is reached.
playWhether the animation should play. The default is "no", but if a literal "yes" is specified the animation starts playing immediately. If an expression is specified, the animation will play whenever the return value of the expression is true.
maxThe maximum value of the level.
minThe minimum value of the level.
scaleIf set to "yes", scale the animation to fit the rect. It is possible to scale in one direction only with "vertical" or "horizontal".
srcThe image containing the frames for the levels.
widthThe width of a frame.

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

AttributeDescription
alignSet the alignment of the elements. See Alignment.
keypadIf true, the item is active in keypad mode.
orientationThe direction to layout the elements ("vertical" or "horizontal").
spacingThe space left between elements.
stretchWhen set to "yes", stretch the elements to use all available space.

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.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3