MediaPortal Windows Media Center
MediaPortal Wiki > MediaPortal 1 > Contribute > Skins > Skin Architecture > Skin Logic > Skin Settings

Skin Settings

Was this page helpful?
Redirected from 1 MEDIAPORTAL 1/18 Contribute/7 Skins/Skin Architecture/Skin Settings
    MPLogo120.png

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

    Overview

    Skin settings provide skins with user-definable (by the skin designer) property settings that can be leveraged for many purposes including making logical decisions about when or how controls are displayed and what the controls display.  Skin settings add the capability to have significant design control over GUI customization.

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

    • Customization of the MediaPortal GUI - End-user (GUI) manipluation of the value of a skin setting (e.g. on MediaPortal settings windows) followed by consuming the value of the skin setting as a skin define in GUI controls in another window.
    • Selection of MediaPortal Themes

    Skin settings must be defined and referred to using a leading hash ('#') character; e.g. #ThisIsASkinSetting, ThisIsNot.  An attempt to use a skin setting without a leading hash character will result 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 skin/<skin-name>/SkinSettings.xml and each is immediatley promoted to a MediaPortal property of the same name.  Only skin settings used in skin setting functions are made peristent; see description of functions.

    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 to a file named SkinSetting.xml.  The SkinSettings.xml file is saved to the same directory as the associated skin xml files; e.g., skin/DefaultWide/SkinSettings.xml.  Each skin will have only one SkinSettings.xml file. Skin themes do not have their own SkinSettings.xml; one settings file is shared among all themes.  The presense of a SkinSettings.xml file is optional and only needed if the skin is designed using skin settings.

    The format of SkinSettings.xml is exactly the same as MediaPortal.xml.  An example of the files content follows:

     

    <?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 distict sections; booleansettings and stringsettings.  Entries in these sections have the name of the setting defined using the name attribute and its value 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 content of this file should be specified by the skin designer to setup 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



    Tag page (Edit tags)
    • No tags
    Running the latest version?

    V1.7.0 - released April 2014
    Releasenews | Download
    Changelog
     | Requirements
    HTPC
    Team-MediaPortal
     
    About
    Contact |  Press
    Partners