Page tree


Search

  Wiki Navigation

    Loading...


 Recently Updated


 Latest Releases

 MediaPortal 1.23 
            Releasenews | Download
 MediaPortal 2.2.2
            Releasenews | Download

Table of Contents

Overview

The layout, structure and tag definitions for the skin files.

Introduction

Unlike web pages, XML files are not forgiving of any mistakes and using the correct case for tag names is very important. 

NoteXML files are CASE SENSITIVE.

Skin XML Structure

XML Version and Character Encoding

Skin xmls start by defining the XML version and character encoding, usually:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

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

Note: Not all skin xmls contain a Window ID, for example, 'common' files which are imported into 'window' xmls.
 

Element Name

Data Type

Description

id

Integer

Each skin file must have a unique id and it must match the id in the application or plugin using the skin. This id is used to reference this skin page from a hyperlink in another skin page.

defaultcontrol

Integer

Specifies the id of the default control in this skin file

allowoverlay

Boolean (yes or no)

Show the video/tv/music preview screen in the bottom corner when a media file is playing

autohidetopbar

Boolean (yes or no)

Automatically hide the top bar

disabletopbar

Boolean (yes or now)

Disable top bar completely in the current window

define

String

Specify a value of "#Named Token:Replacement Value". Any occurrence of the token represented by the define's name will be replaced with the appropriate value in any imported markup. Images are imported from the Media within the current skin directory. Labels (e.g. 5900 in the above example) are imported from the language folder in the MediaPortal application folder. This element may be repeated as many times as tokens are required.

<define> tags

Define tags normally appear at the top of a skin xml for easy reference.They allow a basic form of parameter to be used so that imported files can be as generic as possible. A define tag's value is a simple name - value pairing.

  • <define> tags can be used in any XML with a window ID
  • <define> tags are entered in the window elements control at the top of the xml before the <controls>.
  • 'global' <define> tags can be also be used in the references.xml to define global values 

Note: As of v 1.3.0 beta, <define> tags are 'promoted' to skin properties to allow them to contain skin expressions, and be added to the window definition through the use of an <include> file. See Defines for further info.

Sample

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

<controls> element

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

Element Name

Data Type

Description

import

String

The name of a xml file to import within the same skin folder. Normally used to reference all the common markup into smaller and easier to manage files. You may have multiple import elements

include

String

Same as import - as of v 1

condition

Boolean

As of v 1.3.0 beta, skins may use any valid skin expression or skin setting that evaluates to a boolean

control

Control

A graphical control. There will be as many of these as there are controls on a window

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

 

Every control is derived from a base control (GuiControl) and has at least the following attributes:

Element Name

Data Type

Description

id

Integer

The id of the control. The id will couple the skin file to the code, so if we later on want to check that a user pressed a button, the id will be required and must be unique. For controls that will never be referenced in the code it is safe to set it to "1"

description

String

An optional description of the control for your reference

type

String

The type of control you want. See the list below for valid types of control

posX

Integer

The X-position on the window for this control (left edge = 0, measures positive to the right)

posY

Integer

The Y-position on the window for this control (top edge = 0, measures positive down)

width

Integer

The width of this control

height

Integer

The height of this control

onleft

Integer

The control id to move the focus to when the user moves left. If not specified (or zero) MediaPortal will find the closest control in that direction to move to

onright

Integer

The control id to move the focus to when the user moves right. If not specified (or zero) MediaPortal will find the closest control in that direction to move to

onup

Integer

The control id to move the focus to when the user moves up. If not specified (or zero) MediaPortal will find the closest control in that direction to move to

ondown

Integer

The control id to move the focus to when the user moves down. If not specified (or zero) MediaPortal will find the closest control in that direction to move to

colordiffuse

Long

Allows you to mix a color & a graphics texture. E.g. If you have a graphics texture like a blue button you can mix it with a yellow color diffuse and the end result will be green. Defaults to 0xFFFFFFFF

dimColor

Integer

Color for a control when it is not focused. Defaults to half transparent (0x60ffffff)

<import> or <include> 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.

See Import or include for further details.

   

 

This page has no comments.