Official Kodi Wiki - User contributions [en]

Add-on settings

2015-04-07T18:38:01Z

Miszka999: /* type="enum" or "labelenum" */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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.

There are some functionality not cover by this wiki page. See C++ source:
https://github.com/xbmc/xbmc/tree/master/xbmc/addons/GUIDialogAddonSettings.cpp

== Different types ==

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

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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)"
|-
| subsetting="true" || Add dash in front of option
|}

== Elements ==

=== Line separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Selector ===
Will open separate selection window
==== type="select" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required): A list of values or language file ids from which the user can choose.
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_select" type="34231" label="Select" values="One|Two|Three|Four" />
</syntaxhighlight>
==== type="addon" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''addontype="''xbmc.metadata.scraper.movies''"''' (required) - type of addon.
* multiselect="''true|false''" (optional) - allows to select several addons
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_addon" type="addon" label="Addon" default="" addontype="xbmc.metadata.scraper.movies" multiselect="true" />
</syntaxhighlight>

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.
* values="$HOURS" is special case to select hour ( works only for type="enum" )
* sort="yes" - sorts labels ( works only for type="labelenum" )

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
<setting label="EnumHours" type="enum" id="default_enumhours" values="$HOURS" />
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T09:21:24Z

Miszka999: /* Different types */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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.

There are some functionality not cover by this wiki page. See C++ source:
https://github.com/xbmc/xbmc/tree/master/xbmc/addons/GUIDialogAddonSettings.cpp

== Different types ==

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

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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)"
|-
| subsetting="true" || Add dash in front of option
|}

== Elements ==

=== Line separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Selector ===
Will open separate selection window
==== type="select" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required): A list of values or language file ids from which the user can choose.
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_select" type="34231" label="Select" values="One|Two|Three|Four" />
</syntaxhighlight>
==== type="addon" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''addontype="''xbmc.metadata.scraper.movies''"''' (required) - type of addon.
* multiselect="''true|false''" (optional) - allows to select several addons
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_addon" type="addon" label="Addon" default="" addontype="xbmc.metadata.scraper.movies" multiselect="true" />
</syntaxhighlight>

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.
* values="$HOURS" is special case to select hour ( works only for type="enum" )

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
<setting label="EnumHours" type="enum" id="default_enumhours" values="$HOURS" />
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T08:39:08Z

Miszka999: /* Description */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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.

There are some functionality not cover by this wiki page. See C++ source:
https://github.com/xbmc/xbmc/tree/master/xbmc/addons/GUIDialogAddonSettings.cpp

== Different types ==

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

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Selector ===
Will open separate selection window
==== type="select" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required): A list of values or language file ids from which the user can choose.
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_select" type="34231" label="Select" values="One|Two|Three|Four" />
</syntaxhighlight>
==== type="addon" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''addontype="''xbmc.metadata.scraper.movies''"''' (required) - type of addon.
* multiselect="''true|false''" (optional) - allows to select several addons
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_addon" type="addon" label="Addon" default="" addontype="xbmc.metadata.scraper.movies" multiselect="true" />
</syntaxhighlight>

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.
* values="$HOURS" is special case to select hour ( works only for type="enum" )

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
<setting label="EnumHours" type="enum" id="default_enumhours" values="$HOURS" />
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T08:13:44Z

Miszka999: /* type="enum" or "labelenum" */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Selector ===
Will open separate selection window
==== type="select" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required): A list of values or language file ids from which the user can choose.
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_select" type="34231" label="Select" values="One|Two|Three|Four" />
</syntaxhighlight>
==== type="addon" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''addontype="''xbmc.metadata.scraper.movies''"''' (required) - type of addon.
* multiselect="''true|false''" (optional) - allows to select several addons
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_addon" type="addon" label="Addon" default="" addontype="xbmc.metadata.scraper.movies" multiselect="true" />
</syntaxhighlight>

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.
* values="$HOURS" is special case to select hour ( works only for type="enum" )

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
<setting label="EnumHours" type="enum" id="default_enumhours" values="$HOURS" />
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T08:12:24Z

Miszka999: /* Rotary selector */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Selector ===
Will open separate selection window
==== type="select" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required): A list of values or language file ids from which the user can choose.
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_select" type="34231" label="Select" values="One|Two|Three|Four" />
</syntaxhighlight>
==== type="addon" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''addontype="''xbmc.metadata.scraper.movies''"''' (required) - type of addon.
* multiselect="''true|false''" (optional) - allows to select several addons
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_addon" type="addon" label="Addon" default="" addontype="xbmc.metadata.scraper.movies" multiselect="true" />
</syntaxhighlight>

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.
* values="$HOURS" is special case to select hour ( works only for type="enum" ??)

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T08:10:19Z

Miszka999: /* Selector */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Selector ===
Will open separate selection window
==== type="select" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required): A list of values or language file ids from which the user can choose.
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_select" type="34231" label="Select" values="One|Two|Three|Four" />
</syntaxhighlight>
==== type="addon" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''addontype="''xbmc.metadata.scraper.movies''"''' (required) - type of addon.
* multiselect="''true|false''" (optional) - allows to select several addons
<syntaxhighlight lang="xml" enclose="div">
<setting id="id_addon" type="addon" label="Addon" default="" addontype="xbmc.metadata.scraper.movies" multiselect="true" />
</syntaxhighlight>

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T08:08:21Z

Miszka999: /* Selector */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Selector ===
Will open separate selection window
==== type="select" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required): A list of values or language file ids from which the user can choose.
==== type="addon" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''addontype="''xbmc.metadata.scraper.movies''"''' (required) - type of addon.
* multiselect="''true|false''" (optional) - allows to select several addons

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T08:02:12Z

Miszka999: /* Selectors */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="select" ====
==== type="addon" ====
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T07:59:42Z

Miszka999: /* type = "action" */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Action execution ===
==== type = "action" ====

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T07:58:00Z

Miszka999: /* Execute action */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== type = "action" ===

Adds line to configuration windows which allow to execute action

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T07:53:38Z

Miszka999: /* type="time" */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="13:13" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_time" type="time" label="Time" default="13:13"/>
</syntaxhighlight>

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Execute action ===

Separator adds a label as separator between other element

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T07:52:16Z

Miszka999: /* type="date" */

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display or string
* default="2015-03-12" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting id="record_date" type="date" label="Date" default="2015-03-12"/>
</syntaxhighlight>

==== type="time" ====
=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Execute action ===

Separator adds a label as separator between other element

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T07:48:08Z

Miszka999: date and type

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Date and time input ===
==== type="date" ====
==== type="time" ====
=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Execute action ===

Separator adds a label as separator between other element

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]

Add-on settings

2015-04-03T07:46:23Z

Miszka999: conditinal visibility clarification

{{mininav|[[Development]]|[[Add-on development]]}} 

{{see also|Python development}}

== 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:
<syntaxhighlight lang="xml" enclose="div">
<?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(my.addon.id, downloadreport)"/>
</category>
</settings>
</syntaxhighlight>

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:'''

{| class="prettytable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music || || ||
|-
| video || || ||
|-
| pictures || || ||
|-
| programs || || ||
|-
| local || || ||
|-
|}

'''Settings can have additional attributes:'''
{| class="prettytable" border="0"
|-
| 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)" visible="eq(-2,true)" ( same syntax like for enable="" )
|-
| 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 separators ===
Line separators add a horizontal separating line between other element. They are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

==== type="sep" ====
Shows a horizontal line.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting type="sep"/>
</syntaxhighlight>

==== type="lsep" ====
Shows a horizontal line with a text.

Attributes:
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="lsep"/>
</syntaxhighlight>

=== Text input ===
Text input elements allow a user to input text in various formats. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="text" ====
Allow a user to enter one line of text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* option="hidden"|"urlencoded" (optional)
:if set to "hidden", each characters entered by the user will be obfuscated with an asterisks ("*"), as is usual for entering passwords.
:if set to "urlencoded", each non-alphanumeric characters entered by the user will be "escaped" using %XX encoding.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="text" id="username" />
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="username" value="john.doe" />
</syntaxhighlight>
{{Note|Security consideration: when using <nowiki>option="hidden"</nowiki>, the value entered by the user is still saved as an unencrypted string value on disk.}}

==== type="ipaddress" ====
Allow a user to enter an ip address as text.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32035" type="ipaddress" id="ipaddress"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="ipaddress" value="127.0.0.1" />
</syntaxhighlight>

=== Numeric input ===
Numeric input elements allow a user to enter a number. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="number" ====
Allows the user to enter an integer using up/down buttons.

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32036" type="number" id="code"/>
</syntaxhighlight>

The value entered by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="code" value="127000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer value if needed}}

==== type="slider" ====
Allows the user to enter a number using a horizontal sliding bar.

Example:
<syntaxhighlight lang="xml" enclose="div">
<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"/>
</syntaxhighlight>

Attributes:
* '''id="''string''"''' (required) - the name of the setting.
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''range="''min''[,''step''],''max''"''' (required) - specify the range of valid values.
* '''option="int"|"float"|"percent"''' (required) - specifies whether to allow the user to choose between integers, floating point numbers or a percentage.
* default="''value''" (optional) - the default value.

The value entered by the user is saved as a string representation of a floating point value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="limit" value="5.000000" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}

=== Boolean input ===
Boolean input elements allow a user to switch a setting on or off.

==== type="bool" ====
Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* default="true"|"false" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="bool" id="background" default="false"/>
</syntaxhighlight>

{{Note|"true" and "false" are case sensitive!}}

The value entered by the user is saved as a string "true" or "false":
<syntaxhighlight lang="xml" enclose="div">
<setting id="background" value="false" />
</syntaxhighlight>

{{Note|In Python, calling xbmcplugin.getSetting will return a string "true" or "false", which must be converted to a boolean value if needed}}

=== Rotary selector ===
A rotary selector allows the user to selected from a list of predefined values.

==== type="enum" or "labelenum" ====
Both element types work the same except that the "enum" type will use the index of the chosen value, wheras the "labelenum" will use the actual value.

Arguments:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* '''values="''value1''[|''value2''[...]]" - or -
* '''lvalues="''id1''[|''id2''[...]]" (required):
: A list of values or language file ids from which the user can choose.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32018" type="enum" id="service1" values="One|Two|Three|Four"/>
<setting label="32019" type="labelenum" id="service2" values="One|Two|Three|Four"/>
<setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
</syntaxhighlight>

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

The value entered by the user is saved as a string. For "enum"-type settings the index of the value is saved, starting at 0 for the first value. For "labelenum"-type settings the value is saved or, in case the lvalues attribute is used, the label translated in the language of the user.
<syntaxhighlight lang="xml" enclose="div">
<setting id="service1" value="0" />
<setting id="service2" value="One" />
<setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>

=== File and folder browsing ===
File and folder browsing elements allow a user to select a file or folder by browsing the local disks or network. You can specify a media type to show only files of the chosen type to the user. The "label" attribute must contain an id from the language file that indicates which text to display for the input field.

==== type="file", "audio", "video", "image" or "executable" ====
Allow the user to browse for and select a file. When using type="audio", "video", "image" or "executable", only files of those types are displayed to the user.

Attributes:
* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* value="''value''" (optional) - the default value.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="file" id="file" value="path_to_files"/>
</syntaxhighlight>

The full path to the file selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="file" value="smb://path_to_files/file.ext" />
</syntaxhighlight>

==== type="folder" ====
Allow the user to browse for and select a folder.

* '''id="''string''"''' (required) - the name of the setting
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
* source="auto"|"images"|... (optional, default="auto") - select a starting folder for the browse dialog.
* value="''value''" (optional, default="") - the default value.
* option="writeable" (optional, default="") - the user can be allowed to create and select new folders by setting this argument.

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</syntaxhighlight>

The full path to the folder selected by the user is saved as a string value on disk:
<syntaxhighlight lang="xml" enclose="div">
<setting id="folder" value="smb://path_to_files/"/>
</syntaxhighlight>

==== type="fileenum" ====
Display files in a folder as an enum selector.

Example: List sub-folders of the 'resources' folder for this add-on in the settings.

<syntaxhighlight lang="xml" enclose="div">
<setting id="myenum" type="fileenum" values="resources" mask="/" "/>
</syntaxhighlight>

==== Extra attributes ====

* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
* option="hideext" - hide file extensions.

=== Execute action ===

Separator adds a label as separator between other element

Example code:
<syntaxhighlight lang="xml" enclose="div">
<setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
</syntaxhighlight>

List of actions that can be used:
* [[List of built-in functions]]

Attributes:
* option="close" (close the settings dialog before executing the action)

[[Category:Add-ons|*]]
[[Category:Settings]]
[[Category:Add-on development]]
[[Category:Skin development]]
[[Category:Development]]