Add-on settings

Template:DevsHeader

Description

settings.xml is a XML file that contains the current configuration for the addon and should be placed in the resources direcory. If your addon has configurable items that are set by the user, put them here. This file defines what the user sees when they click on Addon settings for your addon. You don't need to do any coding to utilise this functionality. The format for the settings file is relatively straightforward as can be seen in the following example:

Example code:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
    <category label="32001">
        <setting label="32011" type="text"   id="username" default=""/>
        <setting label="32012" type="text"   id="password" option="hidden"  enable="!eq(-1,)" default=""/>
        <setting label="32053" type="slider" id="limit" subsetting="true" default="20" range="5,5,100" option="int" />
        <setting type="sep"/>
        <setting id="debug" type="bool" label="32013" default="false"/>
    </category>
    <category label="32010">
        <setting label="32032" type="action" action="RunScript($CWD/resources/lib/viewer.py, downloadreport)"/>
    </category>
</settings>

You need to supply at least one category element. The label attribute of both categories and settings should be the id of a language string in your language files or the one of the main XBMC language file.

Different types

Setting type and additional attributes can be one in the following table:

Type	Description	Value attribute (value="")	Notes
music
video
pictures
programs
local

Settings can have additional attributes:

source=""	"video", "music", "pictures", "programs", "files", "local" or blank." if source is blank it will use the type for shares if it is a valid share if not a valid share it will use, both local and network drives.
visible=""	"true", "false" or conditional." Determines if the setting is displayed in the settings dialog (default = 'true')" You can also use a conditional statement: visible="System.HasAddon(plugin.video.youtube)"
enable=""	Allows you to determine whether this setting should be shown based on the value of another setting. 3 comparators are available:" eq() Equal to gt() Greater than lt() Less than You can AND the comparators using the + symbol and negate it using the ! symbol (e.g. !eq() ). Each comparator takes 2 operands: Relative position of setting to compare Value to compare against Thus if we place settings in our file in this order: myFirst setting mySecondSetting myThirdSetting for the third setting we might add the option: enable="gt(-2,3) + lt(-2,10)" You can also use a conditional statement: enable="System.HasAddon(plugin.video.youtube)"

Elements

Line separator

Separator adds a horizontal separating line between other element

Example code:

    <setting type="sep"/>

Label separator

Separator adds a label as separator between other element

Example code:

    <setting label="32032" type="lsep"/>

Text input

Example code:

    <setting label="32033" type="text" id="username"/>

Values is saved as a string value:

    <setting id="username" value="john.doe" />

Attribute:

• option="false" (This controls if text is visible or hidden as password field. Possible values are true or false.)
• option="urlencoded"

IP address input

Example code:

    <setting label="32033" type="ipaddress" id="ipaddress"/>

Values is saved as a float value:

    <setting id="ipaddress" value="127.0.0.1" />

Numeric input

Example code:

    <setting label="32033" type="number" id="code"/>

Values is saved as a string value:

    <setting id="code" value="127000" />

Browsing

This lets you browse and select for specific media types.

audio|video|image|executable|file|folder

File selector

Example code:

    <setting label="32033" type="fileenum" id="file" value="path_to_files"/>

Values is saved as a string value:

    <setting id="file" value="smb://path_to_files/file.ext" />

Folder selector

Example code:

    <setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>

Values is saved as a string value:

    <setting id="folder" value="smb://path_to_files/"/>

Attributes:

• source="auto" (auto|images|....)
• option="writeable" (enables folder creation button in select dialog)

Audio selector

Example code:

    <setting label="32033" type="audio" id="file" value="path_to_files"/>

Values is saved as a string value:

    <setting id="file" value="smb://path_to_files/file.ext" />

Bool

Creates radio button with two states on/off. Set default or value attribute to true or false (note case sensitive). Using xbmcplugin.getSetting(pluginId,'setting_id_tag') on a bool will return string true or false. Use appropriate conversion to turn into real boolean.

Example code:

    <setting label="32033" type="bool" id="background" default="false"/>

Values is saved as a string value:

    <setting id="background" value="false" />

Rotary selecting using enum or labelenum

A rotary selector allows the user to selected from a list of predefined values. The possible values must be specified in the "values" or "lvalues" attribute and separated using a pipe "|". You can specify the values from which the user can choose in the settings.xml file by using the "values" attribute. Or you can use the "lvalues" attribute to specify language file ids, so that the values from which the user can choose are taken from the language file.

type="enum"

The "enum" setting will return the index of the selected value:

    <setting label="32019" type="enum" id="service" values="One|Two|Three|Four"/>

• Selecting the value "One" will return the int value "0", selecting the value "Two" will return the int value "1", etc.

type="labelenum"

The "labelenum" setting will return the selected value itself, rather than its index:

    <setting label="32019" type="labelenum" id="service" values="One|Two|Three|Four"/>

• Selecting the value "One" will return the string value "One", selecting the value "Two" will return the string value "Two", etc.

the "lvalues" attribute

As previously mentioned, both "enum" and "labelenum" support using language file ids instead of hard-coded string, by using the "lvalues" attribute, rather than "values":

    <setting label="32019" type="labelenum" id="service" lvalues="32001|32002"/>

• When using "enum", the index of the selected option will be returned as usual. When using "labelenum", the language file id will be returned, as in "32001", "32002", etc. (rather than the text from the language file)

Selection

Selector gives you a control from which you can selected predefined values. Below are some possible applications.

Attributes:

• mask="" (????????????????)
• option="" (????????????????)

Slider

With the slider you can let the user slect a value with the keyboard/mouse specified within the set ranges

Example code:

    <setting label="32053" type="slider" id="limit" default="20" range="5,5,100" option="int" />
    <setting label="32053" type="slider" id="limit" default="20" range="0,100"/>

Attributes:

• range="min,step,max"

   range="5,5,100"

• range="min,max"

   range="5,100"

• option="int" (only shows int values on the slider).
• option="float"
• option="percent"

Values is saved as a float value:

    <setting id="limit" value="5.000000" />

Execute action

Separator adds a label as separator between other element

Example code:

    <setting label="32032" type="action" action="RunScript($CWD/resources/lib/viewer.py, downloadreport)"/>

List of actions that can be used:

• List_of_built-in_functions

Attributes:

• option="close" (close the settings dialog before executing the action)

See also

• Add-ons
• Category:All add-ons

Development:

• Add-on development
• Python development