Logical IDs

Graphics

A logical ID is a way to unambiguously refer to a particular piece of graphics from the theme. Each and every asset from the theme, be it an icon, a background image, or a piece of a widget graphics, has such an ID.

The ID abstracts the actual format of the graphic from the application developer, and allows MeeGo Touch to automatically switch the graphics when the theme changes to match the new look.

Using logical IDs

Logical IDs are typically used in the following ways:

• In MeeGo Touch widget methods that take an ID
• Requesting a piece of graphic directly from the theme system
• In the CSS files of applications and libraries

Examples of methods that accept an logical ID include:

• MImageWidget::setImage(const QString &id, const QSize &size)
• MAction::setIconID(const QString &id)
• MComboBox::setIconID(const QString &id)
• MContentItem::setImageID(const QString &id, const QSize &size)

Note:

If a size is not provided when requesting a graphic by logical ID, whatever size the graphics was created with in the theme itself is used which can produce unexpected results. You should therefore always provide a size, the only exception being MAction and MComboBox type of APIs where the component itself already knows the exact size of the graphics.

By providing a logical ID instead of a QPixmap or QImage to a widget, you can be sure that the widget will be updated when the theme changes.

In case you are implementing a widget yourself, or you require a direct handle to the graphics for some other reason, it is possible to request a QPixmap containing a particular themed graphics using MTheme::pixmap(const QString &id, const QSize &size).

In MeeGo Touch CSS files, a logical ID can be provided for style attributes that are of MScalaleImage or QPixmap types:

MButtonSwitchStyle {
    background-image: "meegotouch-button-switch-background";
    thumb-image: "meegotouch-button-switch-thumb";
    ...
}

Mapping graphics to Logical IDs

A themed graphical asset may be either a static image on the filesystem, or a single element or group inside a SVG document. The rules for mapping a logical ID to a piece of graphics is as follows:

• The Theme Structure is searched for graphical assets (SVG's, PNG, JPEGs, etc.)
• If a static image's filename without the suffix (PNG, JPEG, etc.) matches the logical ID, it is selected.
• If a single element's or a group's Object ID in an SVG document matches the logical ID, it is selected.
  • The filename of the actual SVG is not relevant to the selection
  • A single SVG file can contain any number of themed graphical elements
• Files in the icons directory of the theme structure are always selected based on the filename without the suffix, even if they are in SVG format.

The following figure illustrates how a single SVG document contains all of the necessary graphical assets to draw the MButton::switchType widget: