• MediaPortal1_Development
• SkinArchitecture

Skin Architecture

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 home.xml skin file.

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 (BlueTwo, BlueTwo wide, Blue3 and Blue3 wide come with MediaPortal) and those folders contain the individual skin files (e.g. home.xml). There are also sub-folders for fonts, media and sounds. The media folder should has all the textures that the skin file uses (normally in PNG format for best quality).

Special XML files

There are two special XML files within the skin directory. fonts.xml and references.xml:

Fonts (fonts.xml)

The fonts that are available to the skin are defined in the fonts.xml file. The actual fonts are stored in the fonts sub-folder. Each font element defines:

• The name that it will be referenced as in the skin files
• The filename of the actual font file
• The height of the font

• Whether the font is bold

• Whether the font is italic

• The numeric start character (default 0)
• The numeric end character (default 255)

References (references.xml)

The references.xml file contains at minimum information about the skin version and resolution (width and height). It can also include default values for any of the controls (using the <control> tag) that are used in the skin so you don't have to define, for example, the sizes of buttons each and every time you use one in your other skin files. It can also defines styles that can be applied to any control although this feature is not covered in this document.

Here is an partial references.xml file for example purposes. It shows that this skin is designed for a 720x576 pixel display (MediaPortal will scale it to whatever display the end user has) and the version is 0.1.0.15. It also contains the default values that will be used for any button control in any other skin file within this skin folder:

<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>
        ...
        ...

Information on controls can be found in the controls section of this document.

Media and Sound Folders

The sounds folder contain WAV files used by the MediaPortal application and plugins.

The following sounds are included in the default skins for navigational sounds. They can be adjusted in the configuration utility by using the input mapper.

• back.wav
• click.wav
• cursor.wav
• photo.wav

The following sounds are used by plugins:

• notify.wav (?MyMail plugin)

• MyTetris.Block.wav (MyTetris plugin)

• MyTetris.Knock.wav (MyTetris plugin)

• MyTetris.Level.wav (MyTetris plugin)

• MyTetris.Line.wav (MyTetris plugin)

Packed Graphic Files

Packed graphics are generated at runtime and are used to help keep the rendering portion of the application as efficient as possible. They are only created when no packed graphics already exist. They can be identified by the filename prefix packedgfx and end with either .bxml (binary xml) or .png.

When the individual graphic files of a skin are modified the packed graphic files and the related .bxml files must be deleted otherwise you'll not see your changes in MediaPortal.

The packed graphics files are located in C:\Program Files\Team MediaPortal\MediaPortal\Cache\ and then within individual skin folders.

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.

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:

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>
                ...
                ...

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> element

The first element in a skin file must be the <window> tag which contains information that applies to the entire window. Here is an partial skin.xml file for example purposes. Each of the tags is defined below:

<window>
        <id>1234</id>
        <defaultcontrol>2</defaultcontrol>
        <allowoverlay>yes</allowoverlay>
        <autohidetopbar>no</autohidetopbar>
        <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>
                ...

<controls> element

The controls element is a container for all of the controls on a page.

<control> element

All the GUI controls are put between the <controls> and </controls> tag and each one is contained with a <control> tag. Some controls (e.g. group) may allow you to nest subcontrols within them so you may have <control> tags within a parent <control> tag.

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

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

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.

The list below contains all the control types along with their internal class name in the MediaPortal code and a short description. Click on the name of the class for more details:

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>

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:

--- CategoryDevelopment ---

Animations

1. Conditional Visibility

2. 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!

Appendix

1. MP Core XML Files

2. Third Party Plugin XML Files

3. Displaying Details for Currently Playing File