Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded

Qtopia Theming

Introduction

The Qtopia Phone Edition has a powerful theming engine, allowing much of the user interface to be customized and personalized.

Qtopia - Theming the Phone Edition

The following can be themed:

The color scheme, fonts and background image can be selected by the user in the Appearance settings. It also allows a theme to be selected. The themes presented in the Appearance settings modify one or more of the title, home screen, context bar, widget style and icons. The Media player theme can be selected independantly in the media player settings.

In order to create a well integrated theme it will usually be necessary to implement the Title area, Home screen, Context bar and Window decorations. Widget style and icons can help to finish the effect, however since these are far more time consuming to produce it is common to use those provided by an existing theme.

A theme is defined by a desktop file in $QPEDIR/etc/themes/. The theme desktop file contains:

[Theme]
Name = <name of theme (translatable)>
Style = <name of the Style plugin that handles widget drawing>
WidgetsConfig = <path for the configuration file (for the themed widget style)>
TitleConfig = <path to the title configuration file>
HomeConfig = <path to the home screen configuration file>
ContextConfig = <path to the context bar configuration file>
DecorationConfig = <path to the window decoration configuration file>
IconPath = <list of semi-colon separated paths to substitute icons>

For example, the Portal theme is defined by: $QPEDIR/etc/themes/portal.desktop:

[Theme]
Name = Portal
Style = Qtopia
TitleConfig = portal/title.xml
HomeConfig = portal/home.xml
ContextConfig = portal/context.xml
DecorationConfig = portal/decorationrc

The title, home screen and context bar share the same theming format. The window decoration and widget themes have their own formats.

Themed Views

Themed views are used by the title, home screen and context bar. The Qtopia system interacts with the themed views to display status information, text, animations, etc. The themed views are defined by XML files which describe a heirachical group of visual and formatting elements.

Common Attributes

There are a number of attributes common to many of the elements. These affect the placement of elements and their visual appearance.

Naming Elements

Qtopia Phone interacts with elements using their name. All elements can be named, however only one element of each type should have the same name. For a list of the elements that Qtopia can interact with see the Known Elements section.

This attribute is available in all elements.

Positioning Elements

Elements are placed according to rect attributes. The rects are relative to their parent's geometry. The rect attributes can have one of two forms:

If any of the top or left coordinates are negative, they are relative to the right/bottom of the parent element. If bottom or right coordinates are less than or equal to zero, they are relative to the right/bottom of the parent element.

This allows the theme to scale. For example, to place a rect element that scales as the view gets wider:

<rect rect="20,10,-20,50" color="Highlight" brush="Highlight"/>

This places a rectangle, using the Highlight color, at 20,10 with height of 40 pixels and the y2 coordinate 20 pixels from the parent element's right side.

This attribute is available in all elements.

Showing/hiding elements

The Qtopia system may show or hide elements as appropriate depending upon the state of the system. These elements can be specified by setting the transient attribute to "yes". The active attribute determines whether the element will initially be visible. The default is to show the element. To hide the element set active to "no". The elements which can be transient are listed in the Known Elements section.

This attribute is available in all elements.

Specifying Colors

Colors can be specifed by either their hex color code of the form #RRGGBB, by their Qt QColorGroup color roles:

There are some color roles used mostly for 3D bevel and shadow effects: All of these are normally derived from Background, and used in ways that depend on that relationship. For example, buttons depend on it to make the bevels look good.

Selected (marked) items have two roles:

Finally, there is a special role for text that needs to be drawn where Text or Foreground would provide bad contrast, such as on pressed push buttons:

Alignment

Some elements can be aligned by specifying:

To specify both horizontal and vertical alignment separate the alignment flags by a comma.

Stretching Images

Images and masks can be stretched to support themes that scale to different screen sizes. Stretching specifies a portion of the image that can be duplicated to fill the area between the start and end of the stretched image. The stretching can only be performed in one direction.

This illustration shows that the area bewteen point S1 and S2 is duplicated as necessary when the image is drawn. The stretch points are separated by a comma, e.g. stretch="16,48".

Themed View Elements

page

The top-level element. Specifies the size and shape of the view.

Attribute Description
name The name of the view. Qtopia expects one of title, home or contextbar
base The base directory where the image data can be found relative to $QPEDIR/pics
rect The size of the view. The x and y coordinates are ignored.
mask The mask used to set the widget shape. This is useful for the title and context bar.
stretch The stretch points for the mask.

rect

Draws a rectangle which may be filled.

Attribute Description
active "yes" if this is a transient element.
color The color of the line.
brush The color to fill the interior with.

line

Attribute Description
color The color of the line.

text

Attribute Description
size The font size in points.
color The color of the font.
shadow Paints 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.
align The text alignment.
short When set to "yes" Qtopia will supply a short version of the text, for example instead of "3 new messages", just "3" will be set.

image

Attribute Description
src The image to be drawn.
color A color to blend with the image. This allows images to be colored to match the selected color scheme.
alpha Add an alpha channel with value in the range 0-255
stretch The stretch points for the image.
orientation The direction to stretch the image.

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.

Attribute Description
src The image containing the frames.
count The number of frame in the image.
width The width of the frames.
loop The frame to loop back to when the last frame is reached.
revloop The frame to loop back to, in reverse order, when the last frame is reached.
delay The delay between frames.

status

Displays an on/off status icon.

Attribute Description
imageon The filename of the image representing the on state.
imageoff The filename of the image representing the off state.
coloron A color to blend with the image in the on state.
coloroff A color to blend with the image in the off state.
alphaon The alpha level of the image in the on state (0-255).
alphaoff The alpha level of the image in the off state (0-255).

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.

Attribute Description
src The filename of the image containing the frames for the levels.
count The number of levels.
width The width of the frames.

plugin

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

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 vertical. If any of the child elements are shown/hidden then the remaining children will be layed out again.

Attribute Description
orientation The direction to layout the elements (vertical or
align Set the alignment of the elements. horizontal).

exclusive

This element will display only one of its children. The children must be transient. This is useful for sharing an area in different states.

Known Elements

Qtopia interacts with the view using the element's names an the element type. The names Qtopia supports are:

Name Types Description
time text The current time.
date text The current date.
location text The cell location.
caption text The caption set by application, e.g. the application name.
roaming status Set to on when roaming.
messages text, status New unread messages.
call_active status Call(s) are active.
signal level Signal strength.
battery level Battery charge.
inputmethod rect Placeholder for input method indicator.
calls text, status Missed calls.
alarm status An alarm has been set.
lock status Key lock is active.
calldivert status A call diversion is active.
profile text The current ring profile.
infobox text, image Displays various information to the user, e.g. "Searching for Network" Home screen only.
button0 text, image Context button 0
button1 text, image Context button 1
button2 text, image Context button 2

Window Decorations

It is important that the window decoraton metrics match the title theme. The title is positioned over the window title of maximised windows. If the window title size doesn't match the system title size, some of the applciation window will be obscured, or there will be an empty area at the top of the application.


Copyright © 2001-2005 Trolltech Trademarks
Qtopia version 2.1.1