Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
HTML Wrap
idtoc
Table of Contents
Table of Contents
outlinetrue
absoluteUrltrue
classwikitoc

Overview

Define <Define> tags allow skins to define a value to be used in multiple cases places in a skin xml (or in any xml imported or included in by a window xml).

Defines

Define <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 <define> tag 's value is a simple name - :value pairing.

  • <define> tags can be used in any xml file that has a window ID.
  • <define> tags are entered in the window elements control at the top of the xml, before the <controls> tag.<define> tags can be
  • The name used in any XML with a window ID'global' the <define> tag must begin with the hash character "#", and the name is case sensitive ("#abc" and "#ABC" are two different names).
  • Global <define> tags can be also be used in the file "references.xml" to define global values values.

Sample

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

Code Block
languagexml
linenumberstrue
<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 file ""strings_en.xml" " in the language folder in the MediaPortal application folder.

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

Code Block
languagexml
linenumberstrue
<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>
  ...

Enhanced Defines

As of v With effect from MediaPortal version 1.3.0 beta, <define> tags are 'can be promoted ' to become skin properties, to allow them to contain skin expressions, and be added to the window definition through the use of an the <include> filetag.

By promoting <define> tags to be so that they are tracked inside MediaPortal as properties, skin designers will be able to can use defines to transfer information from one page to another, and to use those values in skin expressions and functions. This is very useful for skin capabilities that provide for user controlled layout changes on a "skin settings" page. Enabling this behavior will significantly reduce reduces the need for skin developers to develop and distribute an MP plugin with their skin (where this decision logic has historically resided); e.g., for .  An example would be modifying the EPG length or home page layout and content.
The implementation handles a few important considerationsThe following points should be noted:

  • Multiple <define> tags with the same name - As skin xml files are loaded, the <define> tags in those windows are loaded and saved as properties. Property values have global scope and are available to be used on any other MediaPortal window. If a window loads and <define> tags 'A' defines a property  "#A", and a subsequent window is loaded that also <define> tags 'A' then defines "#A", the second value of <define> 'A' "#A" overwrites the first value loaded. This implementation was chosen (over in preference to ignoring the second <define> 'A') with definition of "#A" in the expectation that the window information loaded most recently loaded window information is more likely to be correct than window information loaded in the past.
  • <define> tags in conflict with built-in property names - If a window is loaded with a <define> that redefines a built-in property name then , the <define> in the skin xml will overwrite overwrites the current value of the built-in property. However, this cannot be relied upon since should be used with caution, as the skin designer does not have any control over when the built-in property value is written.
  • Property/<define> namespaces - Because <define> tags are now can be managed as properties, it makes good sense for skins to maintain <define> tags using a namespace that will not be in conflict with built-in properties. This is easily done by adopting a simple naming convention for the names used in <define> tags. The recommendation is to preface all names in <define> tags with the word "Skin#Skin". This convention is safe since because MediaPortal does not maintain any properties that begin with "Skin#Skin". For example, use the name "#Skin.tvguide.rows.is_short" rather then simply "tvguide#tvguide.rows.is_short".  Note that names are case sensitive, so "#skin" and "#Skin" represent two different values.

Defines can be added to a skin xml file using

...

the <include>

...

tag.  This behavior allows for the skin designer to create skin files that contain a common set of values that may be used throughout the skin.  For example, you can create a skin file named "colors.xml" with the

...

content shown below.  Each skin xml file that includes "colors.xml" (by using: <include>colors.xml</include> )

...

is able to use the <define> tags that it contains.


Code Block
language

...

xml
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<window>
  <define>#red:ffff0000</define>
  <define>#green:ff00ff00</define>
  <define>#blue:ff0000ff</define>
</window>

Syntax and use

The syntax for a <define>

...

supports the following

...

attributes:


  • property - a boolean value; either "true" or "false.  If "true" then , the <define> definition is promoted to become a MediaPortal property status , and can be used just as any other property is used (in any MediaPortal window).
  • evaluateNow - Specifies whether or not the <define>  a boolean value; either "true" or "false. This specifies whether the definition (which would normally be a skin expression in this case) should be evaluated when it is loaded ("true"), or evaluated later by its consumer ("false").  The consumer must provide expression evaluation if the value is "false".

In the following, at the moment the

...

definition is read in (on window load), the

...

definition is promoted to be

...

become a MediaPortal property (via GUIPropertyManager.SetProperty()). Expressions in the

...

definition's value are not evaluated when the window loads; they

...

areevaluated later, when the control that consumes the define/property is loaded.


Code Block
language

...

xml
<define property="true">#name:value</define>



In the following, at the moment the

...

definition is read in (on window load), the

...

definition is evaluated and any expressions are resolved immediately (via GUIPropertyManager.Parse()). The

...

definition is not promoted to become a MediaPortal property.


Code Block
language

...

xml
<define evaluateNow="true">#name:value</define>



In the following, the expression is evaluated on window load and the result is promoted to become a MediaPortal property.


Code Block
language

...

xml
<define property="true" evaluateNow="true">#name:value</define>



The following alternatives implement the legacy behavior of a <define> tag, and are all functionally equivalent.


Code Block
language

...

xml
<define>#name:value</define>
<define property="false">#name:value</define>
<define evaluateNow="false">#name:value</define>
<define property="false" evaluateNow="false">#name:value</define>


Example

...

This example shows how you can modify the number of TV EPG rows via a GUI user setting using <define> tags and skin settings.

...

  In a settings xml skin file, the following user control is defined to control the length of the EPG (short

...

or long). The

...

<selected> and <onclick> tags manage a skin setting that

...

determines whether the EPG length should be short or long (using the skin setting "#Skin.tvguide.rows.is_short"). When the checkbutton control is clicked, the boolean setting is toggled. Using the skin setting capability provides persistence for the setting (the setting is written to a skin

...

configuration file).


Code Block
language

...

xml
<control>
  <description>Guide Rows</description>
  <type>checkbutton</type>
  <id>14</id>
  <label>Display Less Rows In Guide</label>
  <font>font12</font>
  <width>471</width>
  <height>52</height>
  <textXOff>28</textXOff>
  <textYOff>8</textYOff>
  <markalign>right</markalign>
  <markvalign>top</markvalign>
  <markWidth>33</markWidth>
  <markHeight>21</markHeight>
  <markXOff>30</markXOff>
  <markYOff>10</markYOff>
  <textureFocus>settings_button_focus.png</textureFocus>
  <textureNoFocus>settings_button_nofocus.png</textureNoFocus>
  <textureCheckmark>settings_checkmark_checked.png</textureCheckmark>
  <textureCheckmarkNoFocus>settings_checkmark_unchecked.png</textureCheckmarkNoFocus>
  <textcolor>ffffffff</textcolor>
  <textcolorNoFocus>ffffffff</textcolorNoFocus>
  <onleft>#defaultcontrol.onleft</onleft>
  <selected>skin.hassetting(#Skin.tvguide.rows.is_short)</selected>
  <onclick>skin.togglesetting(#Skin.tvguide.rows.is_short)</onclick>
</control>


Rendering with the setting

In the skin xml file that renders the EPG, the following <define> tags are used to configure the individual controls that make up the EPG. Notice that each <define> contains as its value a skin expression that is calculated when the <define> is read in by the skin engine. Since each <define> is resolved completely at window load time, and in the order in which it appears in the skin xml file, it is possible to build relationships between <define> tags to lessen the complexity of a compound expression.

In this example each <define> consumes the value of the skin setting that is managed via the checkbutton control described above ("#Skin.tvguide.rows.is_short")

...

. Since "#Skin.tvguide.rows.is_short" is a boolean, it may be used in the skin expression iif(condition, true part, false part) as the condition. In each case the appropriate value is selected (either the true part or false part) and assigned to the <define>

...

name at the moment the <define> is read in by the skin engine (during window load).


Code Block
language

...

xml
<define>#Skin.tvguide.viewport.height:#(iif(#Skin.tvguide.rows.is_short, 101, 789))</define>
<define>#Skin.tvguide.viewport.texture:#(iif(#Skin.tvguide.rows.is_short, 'tvguide_timeline_bg.png', 'viewport_tv_guide_10rows.png'))</define>
<define>#Skin.tvguide.panel.height:#(iif(#Skin.tvguide.rows.is_short, 566, 666))</define>
<define>#Skin.tvguide.channel_template.height:#(iif(#Skin.tvguide.rows.is_short, 64, 66))</define>
<define>#Skin.tvguide.current_program_title.posy:#(iif(#Skin.tvguide.rows.is_short, 816, 950))</define>
<define>#Skin.tvguide.current_program_time.posy:#(iif(#Skin.tvguide.rows.is_short, 868, 1006))</define>
<define>#Skin.tvguide.description1.visible:#(iif(#Skin.tvguide.rows.is_short, 'yes', 'no'))</define>
<define>#Skin.tvguide.horizontal_scrollbar.posy:#(iif(#Skin.tvguide.rows.is_short, 905, 505))</define>
<define>#Skin.tvguide.vertical_scrollbar.posx:#(iif(#Skin.tvguide.rows.is_short, 1829, 1329))</define>
<define>#Skin.tvguide.tv_group_button.height:#(iif(#Skin.tvguide.rows.is_short, 533, 665))</define>
<define>#Skin.tvguide.tv_group_label.posy:#(iif(#Skin.tvguide.rows.is_short, 733, 860))</define>



In the body of the skin xml that renders the EPG

...

, the <define> tags

...

above

...

are consumed by

...

GUI controls. Simply use the appropriate <define> in place of a hard-coded value

...

. Example:


Code Block
language

...

xml
<control>
  <description>VIEWPORT</description>
  <type>image</type>
  <id>0</id>
  <posX>0</posX>
  <posY>162</posY>
  <width>1893</width>
  <height>#Skin.tvguide.viewport.height</height>
  <texture>#Skin.tvguide.viewport.texture</texture>
  <shouldCache>true</shouldCache>
</control>


See also: Skin Expressions

...