Test build
Test build

Theme directory structure

Theme directory structure

Theme Directory

The system can have multiple themes and they are all located in /usr/share/themes/-path. Each theme has one root direcory, which will contain 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)

The description file is something every theme has to have. The file contains information about the theme: name, version, etc. For example the index.theme file could look like this: 

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

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

Where value for X-Inherits must be an existing theme (e.g. 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 (DuiPalette, DuiDefaultFonts), and in stylesheets.

When creating a new theme, this file is the one to start with. Just create an empty constants.ini and add a few lines from base:constants.ini with modified values. Now your theme contains index.theme, and constants.ini; and is already a functional theme to be tried out! This is enough because DirectUI themes can inherit other themes. There is no need to copy some existing theme and start modifying it, instead it's recommended to inherit some theme and just change the parts you want. Here's a peek to one of the stylesheets in base-theme. 

DuiButtonStyle {
    font: $FONT_DEFAULT;

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

And as we see the base theme contains style definitions that are made by using constants. So when declaring your own values for the constants, you are changing the style attribute values which are defined by using constants like $COLOR_BACKGROUND.

Below is an example of constants.ini which changes the default colors for this 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

Rest of the values for constants.ini will come from the theme from which you inherited your own.

Theme Graphics Directories

There are three directories under each theme; images, svg and icons. These directories contains all common graphics for the theme. So if you're not pleased with your theme by just changing constants.ini you can always start doing some replacement graphics.

ImageId is a unique name for a piece of graphic. This imageId can be used from application code and from stylesheets and is also a reason, why just by adding graphics to any of these three directories, you can modify your theme. Here's the same peek to one of the stylesheets in base-theme 

DuiButtonStyle {
    font: $FONT_DEFAULT;

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

We can see that "background-image" attribute for the button has a value "duibutton-background". This "duibutton-background" is the imageId. To override the background-image graphics in DuiButton, you just need to place the replacement in for example svg/ directory. The funky part is the imageId. Here's explanation that defines the imageIds for the three directories.

So to create replacement for duibutton-background image, just create an svg called e.g. duibutton.svg and place it under svg/. Then add an element called duibutton-background and create your graphics there.

Library Directory

Every library which provides some new components(widgets) has to also provide default styling attributes for those. Developers of the library will place the default attribute values to /usr/share/themes/base/dui/<libraryname>/style/. Also if the library providing these components has made it possible to change the view part of the component, the developers of the library has placed the initial view configuration to /usr/share/themes/base/dui/<libraryname>/<libraryname>.conf.

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

Library Stylesheet Directory

This directory can contain any number of stylesheet files. The recomendation is that every component(widget) in the library which can be styled would have it's own css-file. This directory must contain one css file which is the entry point. More of the stylesheets can be found from Stylesheets.

Library Main Stylesheet File

This file is located to style directory, and it's name must follow the name of the library (for example libnicewidgets-extras.css). This file will be the one which the system will read when reading style attributes for a class coming from this library. All other files in style should be Import from this file so they will also get read.

Library View Configuration File

This file contains a component(widget) - view pairs. Normally you don't need to have this file in your theme, the default values are coming from the theme you're inheriting from. Anyway if you want to create for example a button with a better looks than is possible to do by changing just css and graphics, this is the place to do that. TODO: view libraries + link to view-config explanation

Application Directory

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

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

Application Graphics Directories

Usually when creating a theme you don't have to override the base-theme definitions for applications (most of the applications probably doesn't even have any special styling). Anyway if you want some specific application to look different than the theme specifies, you can do it by creating application-specific styling. Applications can override themes default graphics by inserting files to images/, svg/ or icons/ directories. The graphics overriding works the same way as it works with theme inheritance, so see Theme Graphics for more info.

Application Stylesheet Directory

Applications can override themes default stylesheet attribute values by creating a application stylesheet entry point. Applications can override any attributes from any component. Everything that is not overridden will still come from theme, so the recommendation is that applications override as few attributes as possible.

Application Main Stylesheet File

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

Application View Configuration File

TODO: explain more.

Feedbacks

The feedbacks are stored in the subdirectory "feedbacks" next to "style", "svg" etc. on the same directory level in the themes. A directory is associated to each feedback under the subdirectory "feedbacks" whose name is the feedback name. For example feedback sample files for a common feedback named "press" of theme "base" should be located at directory "/usr/share/themes/base/meegotouch/feedback/press". 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 lowercase letters, numbers, underscore, dash, or period characters. Spaces, colons, slashes, and backslashes are not allowed". If a directory name does not follow these rules then it is ignored. These subdirectories contain the feedback sample files which can be played by the backends.

The common feedback directory of "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 "base" theme can only override existing feedbacks that are already present in the "base" theme. Any new feedbacks that the derived themes introduce will be 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 can add new feedbacks as well. Any new feedbacks should be placed in the application specific feedback directory of the "base" theme. These feedbacks can be overridden by derived themes but here also 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 will be converted to native fromat each time the feedback gets loaded. This assures 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 happens (e.g. pressing on a button) then all feedback devices will 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 (e.g. "vibra.ivt") then 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 "base" theme etc. 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 (e.g. "press-loud") then it tries to fallback to a generic event name (e.g. "press-loud" -> "press") and load the missing sample(s). Please 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 refers to low, medium and high levels. If these timeline effects are not available in the effect file then the fallback logic uses the first effect from the file (its type does not matter in this case).

Locales Directory

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

Locale Specific Directory

This directory is located to /usr/share/themes/<theme>/dui/locale/<locale>/ where the <locale> is fi, en, etc. Definitions in this directory will be applied for <theme> when the <locale> matches the system locale.

Locale Specific Constants

This file can contain fonts and color definitions for the locale.

Locale Specific Icons Directory

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

MeeGo API