Skin Theme

Skin Themes is new as of version 1.3.0 alpha and later.

Overview

It's a lot of work to create a complete skin including plugins and we appreciate those who work so hard to produce the great skins for MediaPortal.   Several skins come in many flavors including new concepts from the ground up as well as slight to major modifications of existing skins.  The main objective of skin themes is to make it easier to create new skins or variants of existing skins.  You can start with a skin you like and simply make some tweaks to it to change colors, icons, fonts, etc.  The beauty of using a theme is that the authors base skin is never changed, none of it, not a bit.  This allows the original skin author to make updates to their own base skin while others may contribute to the themes for that same skin.  This is just one scenario that we believe can lead to a really great skins each with multiple themes.

When you intermix the use of themes with the Skin Settings there is a whole new world of possibilities for MediaPortal.

The use of themes is optional and none of what is explained here is necessary for skins to continue to work without themes - this implementation is designed to be 100% backward compatible.

Steps to create a theme

1. Create a directory named "Themes" inside your skin directory; e.g., ...skin/Default/Themes
2. Create a directory named for your theme inside your "Themes" directory; e.g., create a theme named "My Theme" as ...skin/Default/Themes/My Theme
3. Create a theme.xml skin file inside your theme directory; e.g., ...skin/Default/Themes/My Theme/theme.xml (see below for content of this skin file)
4. Implement your theme by overriding skin files containing your theme content inside your theme directory; e.g., to create a new theme that changes all the skin fonts simply copy your skin fonts.xml to your theme directory and edit the theme fonts.xml to implement fonts to be set when the theme is selected.

How themes work

Skin directory structure for themes

There is extensive support in the skin engine to scan for available themes and to make selection of a theme possible.  The selected theme is saved to a skin settings file: ...\skin\<skin-name>\SkinSettings.xml.  This skin settings file is shared with skin functions that save skin settings.  See Skin Settings for more information.

Each skin may have one or more themes.  This is accomplished with the addition of a skin level directory called "Themes" (e.g., ...skin/Default/Themes).  Inside the Themes directory you create a directory to hold an entire theme.  The name of the directory is the name of the theme.

...\skin\<skin-name>\Themes\<theme-name>

Example (5 themes for one skin):

...\skin\Fidelity 1.3\Themes\Blue
...\skin\Fidelity 1.3\Themes\Green
...\skin\Fidelity 1.3\Themes\Purple
...\skin\Fidelity 1.3\Themes\Red
...\skin\Fidelity 1.3\Themes\Time of the Day

Theme structure and content

The content of each theme folder exactly matches the folder hierarchy of the skin itself (less the Themes folder).  This means that each theme folder could have "Media", "Sounds" etc.  Additionally, each theme must contain a "theme.xml" skin file in the root folder for the theme.

...\skin\<skin-name>\Themes\<theme-name>\theme.xml
...\skin\<skin-name>\Themes\<theme-name>\Media
...\skin\<skin-name>\Themes\<theme-name>\Sounds

Example:

...\skin\Fidelity 1.3\Themes\Blue\theme.xml
...\skin\Fidelity 1.3\Themes\Blue\Media
...\skin\Fidelity 1.3\Themes\Blue\Sounds

This structure allows for themes to contain both images (in the Media folder) and skin xml files (in the root folder for the theme).

...\skin\<skin-name>\Themes\<theme-name>\<skin-xml-files>
...\skin\<skin-name>\Themes\<theme-name>\Media\<image-files>

Example:

...\skin\Fidelity 1.3\Themes\Blue\common.backgroundcolour.xml
...\skin\Fidelity 1.3\Themes\Blue\Media\hover_my pictures.png

The content of the theme.xml file must be structured as in the following example:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<controls>
  <theme>
    <version>1.3.0.0</version>
    <author>ajp8164</author>
  </theme>
</controls>

Theme files have priority over default skin files

When the skin engine needs to load a skin xml file or an image it first looks in the Themes directory for the selected theme (if one was selected by the user).  If it finds, in the theme, a skin xml file or image of the same name as that which needs to be loaded then it loads it from the theme.  If it does not find an exact match in the theme then it simply loads it from the default skin location (outside the Themes directory).  MediaPortal incorporates this theme prioritization behavior for every skin xml and image file it loads including all of the built-in plugins.

A note about how images should be handled:  Images contained in the themes Media directory are packed and cached exactly as the images in the default skin Media directory.  For this reason the skin cache must be deleted if theme images are changed or added.  Also, since MediaPortal will pack and cache all images in the themes Media directories care should be taken to include in the theme Media directory only images that are truly different than their skin defaults.  The MediaPortal fontEngine only allows for 2000 textures and with over 400 images in a skin simply copying all skin images to the theme and changing only a few will cause this hard limit to be reached with only 5 skin themes built in this manner.  Again, themes should contain only the desired differences from the default skin.

Theme compatibility assurance

When a theme is loaded by MediaPortal it is checked for compatibility against the version of the base skin.  The theme version must exactly match the version of the base skin or the theme will not load.  The skin version information is stored in the skins "references.xml" file.

If the theme is not allowed to load due to incompatibility then the skins default theme (no theme) is set.

Theme version information is specified in "theme.xml" in the controls/theme/version attribute.  The value should be a string that matches the version information of the base skin.

Managing themes from skin controls

There are several capabilities that allow the skin designer to present the selection of themes in the user interface.  The following functions, conditionals, and properties support the selection and use of a theme in the skin:

Note: The end user may also select themes from the MediaPortal Configuration tool, see MediaPortal Configuration tool GUI section.

Functions

For more information see Skin Settings.

skin.theme() - A function that cycles the skin theme.

skin.settheme() - A function that sets the theme to the value specified.

skin.hastheme() - A conditional that returns True if the user has selected the specified theme.

Properties

#skin.currenttheme - A property that returns the name of the current theme.

#skin.themes - A property that returns a CSV (comma-separated value) string of theme names (e.g., "theme1,theme2,theme3").  This property is set when the skin is initially loaded.  This is used in conjunction with MediaPortal GUI controls as specified below.

MediaPortal controls that support selecting themes

The MenuButton control has the flexibility to present a list of selectable options as either a spin control (combined with a button) or a popup menu dialog (combined with a button).  This control has attributes that faciliate the selection of a theme:

<binding> - This tag guarantees that the value (the selected item) of the menu button be set to the value of the content of the tag.  The value of the tag may be an expression.

<subitem> - This tag appears within a <subitems> wrapper.  If the content of this tag is a comma-separated value (CSV) string then each item (separated by commas) is presented as a separate subitem for the control.  This is useful when the MediaPortal developer or plugin developer wishes to present a list of subitems for use by the skinner but the content of this list is not known until runtime (as is the case with a list of available themes).

#selectedlabel{n} - A property that returns the menu buttons currently selected label string.  {n} is the id of the control which made the selection; this is necessary to deconflict between multiple menu buttons on the same window.  Each item in the menu button has both a display text and an integer value; selectedlabel is the display text.

#selectedvalue{n} - A property that returns the menu buttons currently selected integer value.  {n} is the id of the control which made the selection; this is necessary to deconflict between multiple menu buttons on the same window.  Each item in the menu button has both a display text and an integer value; selectedvalue is the integer value.

Menu button usage example to manage theme selection (only relevant skin tags are shown):

<type>menubutton</type>
<id>21</id>
...
<binding>#skin.currenttheme</binding>                    // Ensures that the selected menu option is always the current skin theme.
<onclick>#(skin.settheme(#selectedlabel21))</onclick>    // When the control is selected/clicked the theme will be set to the label for this (id=21) control
...
<subitems>
  <subitem>#skin.themes</subitem>                        // Adds a new entry for each in the csv list
</subitems>

Ideas for implementing Skin Themes

A list of ideas for how themes can be used to enhance MediaPortal.

• If all skin colors are placed into a file called colors.xml (a file full of defines) and that file is included from references.xml then themes based on simply changing the colors in this file are easily done by anyone.  Same applies with fonts.Note; this is proposed as a future development, not yet supported in 1.3.0 alpha)
• Themes may be used to help manage skin variants based on screen resolution.  Themes could exist that allow for a skin to work well for alternate screen resolutions/aspects.  Perhaps Default could be reworked so that there is only one skin with a "Wide" theme.  This eliminates all of the coordination between two skins that are really nearly identical.
• Themes may add or remove plugins from the skin default.
• Use of themes may help to eliminate the need for special skin plugins that manage customization (e.g., selecting the number of TV guide rows - this should be able to be done using themes and Skin Settings).