Skin Architecture

On 24 Sep 2010, chefkoch suggested that the content of this page or section be split into sub pages.

Introduction

The MediaPortal graphical user interface is a modular solution that uses skins to separate the look and feel from the logic in the application code. MediaPortal application functionality is surfaced through user interface windows (GUIWindow) containing many graphical user interface controls (GUIControl). However, without a skin file, none of this functionality is visible to the user.

The user accesses the functionality surfaced from the application code through skins which are defined using XML. The application will load the appropriate XML skin file upon initialization. For example, when MediaPortal starts, the first skin to generally be loaded will be the myHome.xml or BasicHome.xml skin file depending on which option the user has configured.

The use of XML simply provides a structured way to tell MediaPortal the layout, type of control and coordinates of every item on screen such as color of text, transparency if graphics etc. By changing the XML file within a skin the entire look and feel can be modified. Although the details are very different, the idea is the same as making a webpage however XML files are CASE SENSITIVE.

Skin Folders

Skin files are contained in the skins folder within the main MediaPortal application folder.

Within the main skins folder there are sub-folders for each skin (Default and DefaultWide are installed with MediaPortal) and those folders contain the individual skin files (e.g. myHome.xml).

There are also sub-folders for fonts, media and sounds. The media folder should have all the textures that the skin file uses (normally in PNG format for best quality).

<controls>
  <skin>
    <width>720</width>
    <height>576</height>
    <version>0.1.0.15</version>
  </skin>
  <control>
    <description>default button</description>
    <type>button</type>
    <id>1</id>
    <posX>300</posX>
    <posY>200</posY>
    <width>190</width>
    <height>32</height>
    <textXOff>10</textXOff>
    <textYOff>5</textYOff>
    <textureFocus>menu_list_focus.png</textureFocus>
    <textureNoFocus>menu_list_nofocus.png</textureNoFocus>
    <font>font13</font>
    <textcolor>ffffffff</textcolor>
    <colordiffuse>ffffffff</colordiffuse>
    <disabledcolor>60ffffff</disabledcolor>
  </control>
  ...

Skin Files

This section covers the layout and tag definitions for the skin files. Unlike web pages, XML files

are not forgiving of any mistakes and using the correct case for tag names is very important.

<import> files

Skin files have the ability to import/include files into the skin markup using the <import> or <include> tags.

The concept is to move all the common markup into smaller and easier to manage files to minimize the amount of work required to create new skin files and to make it easier to maintain and modify existing skin files.

The <import> control should be added to the <controls> section of the xml. The elements defined in the imported file will overlay elements which are defined previously in the xml, so the location of the <import> control is significant.

Two of the most commonly imported files are common.window.xml which defines elements common to most or all windows, and common.time.xml which defines the display of the date and time on each window.

<define> tags

In order to realize the full benefits from import/include files there is also the <define> tag. The tag allows a basic form of parameter to be used so that the imported files can be as generic as possible. A define tag's value is a simple name - value pairing.

 

1.2.0 alpha:   <define> tags can be used in the references.xml to define global defines. See Global Define Tags for details.

<define> tags can also be used in any xml not only imported files

<define> tags are entered in the window elements control at the top of the xml before the <controls>.

The following would be a typical example of how this new feature could be used:

<window>
  <!-- include the common window features here -->
  <define>#header.label:134</define>
  <define>#header.image:videos_logo.png</define>
  <define>#header.hover:hover_my videos.png</define>
  <controls>
    <!-- include the header logo, text and other common elements -->
    <import>common.window.xml</import>
    <control>
    ...

The value 134 in the above example references a text string in the corresponding language file. For english, this would be the ""strings_en.xml"" in the language folder in the MediaPortal application folder.

Any occurance of the token represented by the define's name will be replaced with the appropriate value in any imported markup. The following is an example of how an imported file could look:

<window>
  <control>
    <type>image</type>
    <id>1</id>
    <posX>60</posX>
    <posY>20</posY>
    <texture>#header.image</texture>
  </control>
  <control>
    <type>label</type>
    <id>1</id>
    <posX>250</posX>
    <posY>70</posY>
    <label>#header.label</label>
    <font>font16</font>
    <textcolor>ffffffff</textcolor>
  </control>
  ...

<window>
  <id>1234</id>
  <defaultcontrol>2</defaultcontrol>
  <allowoverlay>yes</allowoverlay>
  <autohidetopbar>no</autohidetopbar>
  <disabletopbar>no</disabletopbar>
  <define>#header.label:5900</define>
  <define>#header.image:trailers_logo.png</define>
  <define>#header.hover:hover_my trailers.png</define>
  <controls>
    <import>common.window.xml</import>
    <control>
    ...

<window>
  ...
  <controls>
    ...
    <control>
      <id>1</id>
      <description>default button</description>
      <type>button</type>
      ...

Control Types

Depending on the value of the control type tag in the control element above there will be additional tags specific to that type of control. A list of all available controls and a description on how to use them can be found on the Skin Controls page.

Example plugin with most controls implemented

If you want to see how the different controls look/work within MediaPortal download and install the plugin GuiControlsDemo, which can be found in the MP Repository.

Detailled Description of GuiControlsDemo

Colors

• Colors can be specified in the following ways:

• Named colors from the W3C standard HTML palette e.g.

  • White
  • Gainsboro

  • White:#60 (White using an alpha hex channel value of 60)

  • White:96 (White using an alpha non-hex channel value of 60)

• Hex values in the format #RRGGBB (e.g. #330099)
  • RR = red hex value
  • GG = green hex value
  • BB = blue hex value
• Hex values in the format #AARRGGBB (e.g. #20FFFFFF)
  • AA = Alpha (transparency) channel hex value
  • RR = red hex value
  • GG = green hex value
  • BB = blue hex value

Examples:

<textcolor>White</textcolor>
<textcolor>#20FFFFFF</textcolor>
<textcolor>#330099</textcolor>
<textcolor>Gainsboro</textcolor>
<!-- specify a named color with non-default alpha (using hex, preferred) -->
<textcolor>White:#60</textcolor>
<!-- not using hex -->
<textcolor>White:96</textcolor>

Styles

Styles are a 'set' of tags that can be used to format the presentation of a control in a skin xml. As is the case with the use of styles in any software, they help ensure consistency of formatting and reduce the duplication of control tags throughout the skin.

Styles are defined in the references.xml file, usually right after the <skin> control at the top of the file. They are defined using the following format:

• <style Name="stylename"> where stylename is any name you choose for the style

  </style>

  • <id>0</id> (optional)

  • .. whatever tags you wish to include (see examples)

Once the style has been defined in references.xml, it can be used instead of <control> in an xml in the following format:

• <control Style="stylename"> where stylename is the name of the style in references.xml

Example (from streamedMP skin)

• in references.xml:

<style Name="smallTitle">
  <id>0</id>
  <width>220</width>
  <font>mediastream9c</font>
  <textcolor>ffffffff</textcolor>
</style>

• in movingpictures.views.xml:

<control Style="smallTitle">
  <type>label</type>
  <label>#MovingPictures.SelectedMovie.genres</label>
  <posX>825</posX>
  <posY>485</posY>
  <width>580</width>
  <visible>facadeview.filmstrip+Control.IsVisible(50)</visible>
</control>

Example (from aMPed skin)

• in references.xml:

<style Name="Square Filmstrip">
  <posX>40</posX>
  <posY>225</posY>
  <width>720</width>
  <height>576</height>
  <itemWidth>135</itemWidth>
  <itemHeight>135</itemHeight>
  <textureWidth>123</textureWidth>
  <textureHeight>123</textureHeight>
  <thumbWidth>115</thumbWidth>
  <thumbHeight>116</thumbHeight>
  <thumbPosX>3</thumbPosX>
  <thumbPosY>3</thumbPosY>
  <frame>Picture_cover.png</frame>
  <frameFocus>Picture_cover.png</frameFocus>
  <keepaspectratio>no</keepaspectratio>
</style>

• in common.facade.music.xml:

<control Style="Square Filmstrip">
  <description>Filmstrip view</description>
  <type>filmstrip</type>
  <id>50</id>
  <onup>2</onup>
  <animation effect="rotatey" start="60" end="0" center="600,0"
  tween="back" ease="easeout" time="500" reversible="false">
  focus</animation>
  <animation effect="rotatey" start="0" end="60" center="600,0"
  tween="back" ease="easeout" time="500" reversible="false">
  unfocus</animation>
</control>

Internationalization

MediaPortal supports internationalization of skin files through the use of strings.xml which is used for all skins. You will find this file in the language folder of the application directory. There are sub-folders for each supported language. Instructions on creating a translation can be found in the Translator Guide.

Tip: When designing skins, remember that the same words in other languages are often longer than in English so as a rule of thumb, add 30% to the width of dialogs.

The following is the start of the English strings.xml file:

<strings>
  <characters>512</characters>
  <string Prefix="My">
    <id>0</id>
    <value>Programs</value>
  </string>
  <string Prefix="My">
    <id>1</id>
    <value>Pictures</value>
  </string>
  <string Prefix="My">
    <id>2</id>
    <value>Music</value>
  </string>
  <string Prefix="My">
    <id>3</id>
    <value>Videos</value>
  </string>
  ...

The following are the set of attributes that all string elements have:

• The following are the set of tags that all string elements have:

Conditional Visibility

1. Conditional Visibility

2. The visibility of all controls can be determined using the <visible> tag (yes/no). Also, many preset boolean conditions can be used to determine the conditions under which a control displays. Not only that, you can also specify how Mediaportal should transition between a visible state and a hidden state, using animations.

Animations

1. Animations

How to Install a New Skin

1. Download the .ZIP file.
2. Unzip the files to a New directory under 'MediaPortal\Skin'
3. Run the MediaPortal Configuration/Setup
4. Select the new skin under 'General', 'Skin'
5. Enjoy! 

Optimize your skin

Index of Skin related changes between MediaPortal releases

In virtually every MediaPortal release, we must make changes which require that the updates to skins.

If this happens, then all community skins must be updated with this change as well, in order to maintain its functionality.

Appendix

1. MP Core XML Files
2. Third Party Plugin XML Files
3. Displaying Details for Currently Playing File