Home · All Classes · Main Classes · Deprecated

Theme directory structure

Theme directory structure

Theme directory

The system can have multiple themes and they are all located in /usr/share/themes/. Each theme has one root directory, which contains all necessary files for the theme. So if you are developing a theme, you should start by creating a new directory under /usr/share/themes.

Theme description file (index.theme)

Every theme should have a description file. The file contains the name, version, and other information about the theme. The following example illustrates an index.theme file:

[Desktop Entry]
Type=X-MeeGoTouch-Metatheme
Name=Very cool ThEMe
Encoding=UTF-8

[X-MeeGoTouch-Metatheme]
X-Inherits=base
X-Icon = icon-theme-logo
X-Visible=true

Where value for X-Inherits must be an existing theme (for example, base in common case). TODO: explain all key-value pairs

Theme constants file (constants.ini)

This file contains constant definitions for this theme. The constant set is predefined and can be found from /usr/share/themes/base/constants.ini. Constants are used in application code (MPalette, MDefaultFonts), and in style sheets.

When creating a new theme, start with the constants file.

To create the file:

1. Create an empty constants.ini. 2. Add a few lines from base:constants.ini with modified values.

Now your theme contains index.theme, and constants.ini, and it is ready for testing. No other steps are necessary, since MeeGo Touch themes can inherit other themes. Instead of copying and modifying an existing theme, it is recommended to inherit a theme and change the parts you want. The following example illustrates one of the style sheets from the base theme:

MButtonStyle {
    font: $FONT_DEFAULT;

    background-image: "meegotouch-button-background" 10px 10px 10px 10px;
    background-color: $COLOR_BACKGROUND;
    text-color: $COLOR_FOREGROUND;

The base theme contains style definitions that are made with constants. When you declare your own values for the constants, you change the style attribute values defined with constants such as $COLOR_BACKGROUND.

The following example illustrates constants.ini that changes the default colours for the theme:

[Palette]
COLOR_FOREGROUND            = #fafafa ;text color
COLOR_SECONDARY_FOREGROUND  = #7a7a7a ;secondary text
COLOR_BACKGROUND            = #ff0000 ;background

;reversed elements
COLOR_INVERTED_FOREGROUND           = #090909 ;text color
COLOR_INVERTED_SECONDARY_FOREGROUND = #595959 ;secondary text
COLOR_INVERTED_BACKGROUND           = #00ffff ;background

The rest of the values for constants.ini comes from the theme from which you inherited your own theme.

Theme graphics directories

There are three directories under each theme; images, svg and icons. The directories contain all the common graphics for the theme. Thus, if you are not pleased with your theme after just changing constants.ini you can always replace graphics.

ImageId is a unique name for a graphic object. This imageId can be used from application code and from style sheets. The imageID enables you to modify your theme by adding graphics to any of the three directories. The following example illustrates one of the style sheets from the base theme:

MButtonStyle {
    font: $FONT_DEFAULT;

    background-image: "meegotouch-button-background" 10px 10px 10px 10px;
    background-color: $COLOR_BACKGROUND;
    text-color: $COLOR_FOREGROUND;

The "background-image" attribute for the button has a value "meegotouch-button-background". This "meegotouch-button-background" is the imageId. To override the background-image graphics in MButton, you just need to place the replacement, for example, in the svg/ directory. The funky part is the imageId. The imageIds for the three directories are defined as follows:

To create a replacement for the meegotouch-button-background image, create an SVG called meegotouch-button.svg (for example) and place it under svg/. Then add an element called meegotouch-button-background and create your graphics there.

Library directory

Every library that provides new components(widgets) also has to provide default styling attributes for them. Developers of the library place the default attribute values into /usr/share/themes/base/meegotouch/<libraryname>/style/. Additionally, if the library providing these components has made it possible to change the view part of the component, the developer of the library has placed the initial view configuration into /usr/share/themes/base/meegotouch/<libraryname>/<libraryname>.conf.

There is one directory for each library to be themed. Normally it is not necessary to create these library theming folders for your theme. In case you need to change attributes in style sheets or you need to change the view part of a component anyway, you must create a directory which has the same name as the library providing the component (for example libnicewidgets-extras/).

Library style sheet directory

This directory can contain any number of style sheet files. It is recommended that every component(widget) in the library which can be styled should have its own CSS file. This directory must contain one CSS file which is the entry point. For more information on style sheets, see Styling with style sheets.

Library main style sheet file

This file is located in the style directory, and its name must follow the name of the library (for example, libnicewidgets-extras.css). The system reads this file when reading style attributes for a class coming from this library. All other files in style should be Import from this file to ensure that they are also read.

Library view configuration file

This file contains a component(widget) - view pairs. Normally you do not need to have this file in your theme, since the default values come from the theme you are inheriting from. However, you can use this file if, for example, you want to create a button with a better look and you cannot do this by changing only the CSS file and graphics.

TODO: view libraries + link to view-config explanation

Application directory

All applications can provide additional styling for themselves, and the application directory must have the same name as the application to be styled (for example, widgetsgallery/).

This directory can contain graphics, style sheets and view configuration for the application.

Application graphics directories

When creating a theme, you do not usually have to override the base theme definitions for applications. Most of the applications probably do not even have any special styling. However, if you want a specific application to look different than specified in the theme, you can create application-specific styling. Applications can override theme default graphics by inserting files into the images/, svg/ or icons/ directories. Graphics are overridden in the same way as themes are inherited. For more information, see Theme graphics.

Application style sheet directory

To override the default style sheet attribute values of a theme in an application, you can create an application style sheet entry point. Applications can override any attributes from any component. Anything that is not overridden still comes from the theme, so it is recommended that applications override as few attributes as possible.

Application main style sheet file

This file is located in the style directory, and the name of the file has to be equal to the application name.

Application view configuration file

TODO: explain more.

Feedbacks

The feedbacks are stored in the subdirectory "feedbacks" (next to "style", "svg" , and so on) at the same directory level in the themes. For each feedback, the feedbacks directory has a subdirectory corresponding to the feedback name. For example, feedback sample files for a common feedback named "press" of the theme "base" should be located in the "/usr/share/themes/base/meegotouch/feedback/press" directory. The directory names are case-sensitive and follow the icon name conventions of the FreeDesktop project (http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html). Therefore, "all names may only contain lower-case letters, numbers, underscore, dash, or period characters. Spaces, colons, slashes, and backslashes are not allowed". If a directory name does not follow these rules, it is ignored. These subdirectories contain the feedback sample files which can be played by the backends.

The common feedback directory of the base theme contains all the common feedbacks for MeeGo Touch common components and external libraries. The base theme contains all of the common feedbacks. This means that new themes that derive from the base theme can only override existing feedbacks that are already present in the base theme. Any new feedbacks that the derived themes introduce are ignored.

Application-specific feedbacks are placed in the application-specific feedback directory in the theme directory structure. Applications can override any existing common feedback in the base theme and add new feedbacks as well. Any new feedbacks should be placed in the application-specific feedback directory of the base theme. The feedbacks can be overridden by derived themes. However, derived themes cannot introduce any new feedbacks that are not present in the base theme.

Pulseaudio backend: This backend plays audio samples from the device speakers. It is recommended to provide feedback files for this backend in the native format of the audio sink. Files that are not in the native format are converted to native format each time the feedback is loaded. This assures the lowest possible latency when playing the audio effects. The pulseaudio backend supports only WAV files and the name of the audio file must be "audio.wav".

Vibra backend: This backend uses the Immersion TouchSense player to play vibra effects. A vibration effect file ("vibra.ivt") must be placed in the feedback directory.

When an event, such as pressing a button, takes place, all feedback devices play a sample at the same time (play an audio and vibra effect in parallel). If a feedback directory does not contain an effect file for a backend (such as "vibra.ivt"), there is a fallback mechanism to find a sample for the backend going back on the theme inheritance tree. One example of theme inheritance for a feedback could be: "base/feedbacks", "inherited1/feedbacks", "inherited2/feedbacks", "base/application/feedbacks", "inherited1/application/feedbacks", "inherited2/application/feedbacks". Here "base/feedbacks" means common feedback directory of the "base" theme, and so on. The last directory in the list is the first place to look for the feedback. If a zero-sized sample file (either "audio.wav" or "vibra.ivt") is placed somewhere in the inheritance tree, that means that the feedback is not played for the backend that the sample file belongs to. If it is not possible to load some samples for a specific event (for example, "press-loud") then it tries to fallback to a generic event name (for example, "press-loud" -> "press") and load the missing sample(s). Note that the fallback mechanism only works for the text before the first dash ('-'). For example, fallback for feedbacks "press-really-loud" and "press-loud" is "press".

The feedbacks can be played on three different global volume levels. This is a global setting of the feedback daemon, but the feedbacks should be prepared for it. The Pulseaudio backend sets the appropriate playback volume for the audio, nothing should be done here. The vibra backend checks the "vibra.ivt" file for three specific timeline effects, named "low", "medium" and "high", which refer to low, medium and high levels. If these timeline effects are not available in the effect file, the fallback logic uses the first effect from the file (in this case, its type does not matter).

Locales directory

This directory contains directories for different locales. All locales that need some special icons or constant definitions can have their own directory. For example, ar/ (for Arabic) may have a different icon set than the normal theme (as Arabic has right-to-left layouts). Another example could be zh_CN/ (for Simplified Chinese) that has bigger fonts.

Locale-specific directory

This directory is located at /usr/share/themes/<theme>/meegotouch/locale/<locale>/ where the <locale> is fi, en, and so on. Definitions in this directory are applied for <theme> when the <locale> matches the system locale.

Locale-specific constants

This file contains fonts and colour definitions for the locale.

Locale-specific icons directory

This directory contains any number of icons which override the theme icons when the locale matches the system locale setting. The icons in this folder must exist in the theme icons directory.


Copyright © 2010 Nokia Corporation
MeeGo Touch