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

# Qtopia Theming

- Introduction
- Qtopia - Theming the Phone Edition
- Themed Views
  - Common Attributes
    - Naming Elements
    - Positioning Elements
    - Showing/hiding elements
    - Specifying Colors
    - Alignment
    - Stretching Images
  - Themed View Elements
    - page
    - rect
    - line
    - text
    - image
    - anim
    - status
    - level
    - plugin
    - layout
    - exclusive
  - Known Elements
- Window Decorations

## 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:

- Color scheme
- Font
- Title area
- Home screen
- Context bar
- Window decorations
- Widget style
- Icons
- Media player

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:

- `x,y,wxh` - specifies the top, left corner and the width and height.
- `x1,y1,x2,y2` - specifies the top, left and bottom, right corners.

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:

- `None` - do not paint/blend with any color.
- `Background` - general background color.
- `Foreground` - general foreground color.
- `Base` - used as background color for e.g. text entry widgets, usually white or another light color.
- `Text` - the foreground color used with `Base`. Usually this is the same as the `Foreground`, in what case it must provide good contrast both with `Background` and `Base`.
- `Button` - general button background color, where buttons need a background different from `Background`.
- `ButtonText` - a foreground color used with the `Button` color.

There are some color roles used mostly for 3D bevel and shadow effects:

- `Light` - lighter than `Button` color.
- `Midlight` - between `Button` and `Light`.
- `Dark` - darker than `Button`.
- `Mid` - between `Button` and `Dark`.
- `Shadow` - a very dark color.

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:

- `Highlight` - a color to indicate a selected or highlighted item.
- `HighlightedText` - a text color that contrasts to `Highlight`.

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:

- `BrightText` - a text color that is very different from `Foreground` and contrasts well with e.g. `Dark`.

#### Alignment

Some elements can be aligned by specifying:

- left
- hcenter
- right
- top
- vcenter
- bottom

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.