Page tree


Search


 Recently Updated



 Latest Releases

 MediaPortal 1.17 Final
            Releasenews | Download
 MediaPortal 2.1.1 Final 
            Releasenews | Download


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

Overview

Skin settings provide the skin designer with the ability to define settings that can be used for many purposes within the skin, including making logical decisions about when or how controls are displayed, and what information those controls display.  Skin settings add the capability to have significant control over the design of the MediaPortal GUI.

Skin settings can be defined and used in conjunction with skin defines and skin expressions.  Common usage patterns for skin settings include:

  • Customization of the MediaPortal GUI
    The skin designer can provide MediaPortal windows that allow the end user to alter skin settings, and control how the skin appears or behaves.  Other windows in the skin use those values to decide how to display the windows, or what action to take.
  • Selection of MediaPortal Themes
    The skin designer can supply themes that provide predefined combinations of properties that the end user can choose (such as colors or font sizes), whilst still maintaining a consistent overall design for the skin.

Skin settings must have names that begin with the hash (#) character.  Examples:

#This_Is_A_Skin_Setting
#this.is.a.skin.setting.with.a.multipart.name
This_Is_Not_A_Skin_Setting
And.Neither.Is.This

An attempt to use a skin setting without a leading hash character results in intepretation of the skin setting as a string literal.

When MediaPortal loads a skin, all of the skin settings for the skin are read from the file "...\MediaPortal\skin\<skin-name>\SkinSettings.xml" and each is immediately promoted to become a MediaPortal property of the same name.  Only skin settings used in skin-setting functions are made peristent; see the description of the skin-setting functions below.

The remainder of this document introduces skin settings as follows:

  • SkinSettings.xml - Storing your skin settings
  • Skin Conditionals - Using skin settings to decide what to render
  • Skin Actions - Using skin settings in GUI control actions (changing skin setting values):
    • Generic - Generic skin setting actions
    • MediaPortal Themes - Actions related to managing MediaPortal themes

SkinSettings.xml

All skin settings are saved in a file named "SkinSettings.xml".  This file is stored in the same folder as the associated skin xml files, for example: "...\skin\DefaultWideHD\SkinSettings.xml".  Each skin has only one settings file. Skin themes do not have their own "SkinSettings.xml" file; all of the themes use the same settings file.  The presence of a "SkinSettings.xml" file is optional, and is needed only if the skin is designed to use skin settings.

The format of "SkinSettings.xml" is exactly the same as "MediaPortal.xml".  This is an example of a skin settings file:


<?xml version="1.0" encoding="utf-8"?>
<profile>
  <section name="booleansettings">
    <entry name="#skin.tvguide.rows.is_short">True</entry>
  </section>
  <section name="stringsettings">
    <entry name="#skin.mystring">This is a string</entry>
  </section>
  <section name="theme">
    <entry name="name">Skin default</entry>
  </section>
</profile>


Boolean and string settings are separated into two distinct sections: "booleansettings" and "stringsettings".  In these sections, the name of the setting is defined using the name attribute, and the value of the setting is defined as the xml inner text.

The selected theme has its own section.  The value of the theme name is either the reserved name "Skin default" (indicating no theme is applied), or the name of the selected theme.  For more information about themes see skin themes.

The skin designer should ensure that the copy of this file supplied with the skin defines initial values for all settings.

Skin Conditionals

Skin settings may be used to make a decisions about what is rendered in a MediaPortal window.

Attributes

The following skin attributes provide the most common support for skin setting functions.  However, any GUI control with a skin attribute that accepts a boolean value can make use of skin conditionals.

<selected>

When the control is rendered it's "selected" value is derived from this attribute.

Example:

When the control is rendered its value (e.g., as with a check button control) is set based on the skin setting named #show_hour12 (e.g., control not checked if #show_hour12 = False).

<selected>#(skin.hassetting(#show_hour12))</selected>


<visible>

When the control is rendered it is made visible based on the value of this attribute.

Example:

When the control is rendered it is made visible if the skin setting named #show_hour12 is set to "1".

<visible>#(skin.string(#show_hour12,1))</visible>

Defines

You can use skin actions in skin xml define statements to execute an action when a GUI window is loaded.

Example:

When the window loads execute skin.hassetting().

<define>#isWindowVisited:#(skin.hassetting(#thisWindowVisited))</define>

Functions

The names of functions are case-sensitive.

skin.hassetting(setting)

[Since 1.3]

Returns the value of the specified skin setting.  The setting must evaluate to a boolean value.  If the specified setting is not already a skin setting then one is created with an initial value of False.

Examples:

Use in a checkbutton to have the checkbutton set (via toggle) and reflect the value of the setting.

<onclick>#(skin.togglesetting(#show_hour12))</onclick>
<selected>#(skin.hassetting(#show_hour12))</selected>


skin.hastheme(theme)

[Since 1.3]

Returns True if the specified theme is selected.

Examples:

The control is visible if the selected theme is named 'Christmas'.

<visible>#(skin.hastheme('Christmas'))</visible>

Skin Actions

Skin settings functions may be used to perform MediaPortal actions that affect the value of skin settings.  This section highlights the GUI control attributes that may be combined with skin setting functions.

Attributes

The following skin attributes provide specific support for skin setting action functions.

<onfocus>

Provide some action when the control gains focus.

Example:

When the control gains focus the skin setting named #test is set to a value of "1".

<onfocus>#(skin.setstring(#Test,1))</onfocus>


<onclick>

Provide some action when the control is clicked.

Example:

When the control is clicked the skin setting named #show_hour12 is set to a value of "" (empty string).

<onclick>#(skin.setstring(#show_hour12))</onclick>

Defines

You can use skin actions in skin xml define statements to execute an action when a GUI window is loaded.

Example:

When the window loads execute skin.setbool().

<define>#thisWindowVisited:#(skin.setbool(#thisWindowVisited))</define>

Functions - Generic

The names of functions are case-sensitive.

skin.togglesetting(setting)

[Since 1.3]

Toggles the skin setting.  The setting must evaluate to a boolean value.  If the specified setting is not already a skin setting then one is created with an initial value of False; however, the end result of this function leaves the value as True.

Examples:

Use in a checkbutton to have the checkbutton set (via toggle) and reflect the value of the setting.

<onclick>#(skin.togglesetting(#show_hour12))</onclick>
<selected>#(skin.hassetting(#show_hour12))</selected>


skin.setstring(setting[,value[,kb_prompt]])

[Since 1.3]

Sets a skin setting with the specified value.  If no value is specified then the function displays a keyboard dialog and allows the user to input a string value.  The keyboard dialog may display an optionally specified keyboard prompt, kb_prompt.  If a value is specified, then the keyboard dialog does not display, and the setting is set directly.  If the specified setting is not already a skin setting then one is created.

Examples:

Set a string setting to "1".

<onclick>#(skin.setstring(#Test,1))</onclick>

Set a string setting to "" (empty string).

<onclick>#(skin.setstring(#Test,))</onclick>

Display a keyboard for the value; no prompt (label) on the keyboard is displayed.

<onclick>#(skin.setstring(#Test))</onclick>     OR
<onclick>#(skin.setstring(#Test,,))</onclick>

Display a keyboard for the value; the prompt (label) on the keyboard is set to the text in argument 3 (a numeric prompt value is a localized string from the language file).

<onclick>#(skin.setstring(#Test,,'This is my prompt'))</onclick>     OR
<onclick>#(skin.setstring(#Test,,123))</onclick>


skin.setbool(setting[,value])

[Since 1.3]

Sets the skin setting to the specified value.  If no value is specified then the function sets the setting to True.  The specified value must evaluate to a valid boolean value (True or False).

Examples:

Set a boolean setting to True.  If the specified setting is not already a skin setting then one is created.

<onclick>#(skin.setbool(#AbcEnable))</onclick>
<onclick>#(skin.setbool(#AbcEnable,False))</onclick>
<onclick>#(skin.setbool(#AbcEnable,#isValid))</onclick>


skin.reset(setting)

[Since 1.3]

Resets the skin setting. If setting is a boolean setting (i.e., set via skin.setbool() or skin.togglesetting()) then the setting is reset to False. If setting is a string (i.e., set via skin.setstring()) then it is set to an empty string ("").

Examples:

Set a boolean setting to False.

<onclick>#(skin.reset(#AbcEnable))</onclick>

Set a string setting to "" (empty string).

<onclick>#(skin.reset(#Test))</onclick>


skin.resetsettings()

[Since 1.3]

Resets all the boolean and string skin settings to their defaults; booleans are all set to False, strings are all set to an empty string ("").

Examples:

Reset all settings.

<onclick>#(skin.resetsettings())</onclick>

Functions - MediaPortal Themes

This section highlights the skin setting functions that are used to control the selection of MediaPortal Themes.

skin.theme([direction[,focusControlId]])

[Since 1.3]

Advances the current skin theme to the next theme in a list of available themes.  The list of themes is ordered alphabetically with the default skin theme (no theme) appearing first in the list.  If direction is specified it must be either 1 or -1; 1 advances to the next theme, -1 reverses to the previous theme.  Moving past the end or beginning of the list wraps the list.  After the theme is applied the window control with id focusControlId is focused.  If no focusControlId is specified then focus is put on the windows default control.

For more information see Skin Themes.

Examples:

Advance to the next theme and focus on control id 15 after the theme is applied.

<onclick>#(skin.theme(1,15))</onclick>


skin.settheme(theme[,focusControlId])

[Since 1.3]

Sets the current skin theme to the specified theme name.  After the theme is applied the window control with id focusControlId is focused.  If no focusControlId is specified then focus is put on the windows default control.

For more information see Skin Themes.

Examples:

Set the Christmas theme and focus on the window default control after the theme is applied.

<onclick>#(skin.settheme('Christmas'))</onclick>

Set the theme specified by the #selectedTheme property and focus on control id 15 after the theme is applied.

<onclick>#(skin.settheme(#selectedTheme,15))</onclick>

Additional Information and References

  • Mantis Issue: 3411

   

 

This page has no comments.