Add-on settings: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>SkyLined
(→‎Rotary selecting: de-duplicating information, rewording)
No edit summary
 
(77 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{DevsHeader|'''XBMC Add-on development'''}}<br />
{{note|Deprecated - Addons submitted to the Kodi 19 Matrix (and up) can use the new setting format.  see [[Add-on_settings_conversion]]}}


{{mininav|[[Development]]|[[Add-on development]]}}<br />
{{see also|Python development}}


== Description ==
== 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
settings.xml is a XML file that contains the current configuration for the addon and should be placed in the resources direcory (my.addon.id/resources/settings.xml). If your addon has
configurable items that are set by the user, put them here. This file defines what the user sees
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.
when they click on Addon settings for your addon. You don't need to do any coding to utilise this functionality.
Line 10: Line 14:


Example code:
Example code:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
<settings>
Line 21: Line 25:
     </category>
     </category>
     <category label="32010">
     <category label="32010">
         <setting label="32032" type="action" action="RunScript($CWD/resources/lib/viewer.py, downloadreport)"/>
         <setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
     </category>
     </category>
</settings>
</settings>
</source>
</syntaxhighlight>




You need to supply at least one category element.
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.
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 Kodi language file.
 
== Different types ==
 
'''Setting type and additional attributes can be one in the following table:'''
 
{| class="wikitable" border="1"
! Type !! Description !! Value attribute (value="") !! Notes
|-
| music ||  ||  ||
|-
| video ||  ||  ||
|-
| pictures ||  ||  ||
|-
| programs ||  ||  ||
|-
| local ||  ||  ||
|-
|}
 
 
'''Settings can have additional attributes:'''
{| class="wikitable" border="0"
|-
| source="" || "video", "music", "pictures", "programs", "files", "local" or blank."<br />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."<br />Determines if the setting is displayed in the settings dialog (default = 'true')"<br />You can also use a conditional statement: visible="System.HasAddon(plugin.video.youtube)"
|-
| enable="" || Allows you to determine whether this setting should be shown based on the value of another setting. 3 comparators are available:"
* eq() Equal to
* gt() Greater than
* lt() Less than
 
You can AND the comparators using the + symbol and negate it using the ! symbol (e.g. !eq() ). Each comparator takes 2 operands:
* Relative position of setting to compare
* Value to compare against
 
Thus if we place settings in our file in this order:
: myFirst setting
: mySecondSetting
: myThirdSetting


for the third setting we might add the option:<br />
There are some functionality not cover by this wiki page. See C++ source:
enable="gt(-2,3) + lt(-2,10)"<br /><br />
  https://github.com/xbmc/xbmc/tree/master/xbmc/addons/settings/GUIDialogAddonSettings.cpp
You can also use a conditional statement: enable="System.HasAddon(plugin.video.youtube)"
|}


==Elements==
== Elements ==


=== Line separator ===
=== Separators ===
Separators are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.


Separator adds a horizontal separating line between other element
==== type="sep" ====
A line separator, it adds a horizontal line that is useful to separate groups of settings.


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


==== type="lsep" ====
A label separator, it adds a heading text that can be used to display on top of a group of settings.


=== Label separator ===
Attributes:
 
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
Separator adds a label as separator between other element


Example code:
Example code:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting label="32032" type="lsep"/>
     <setting label="32032" type="lsep"/>
</source>
</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.


=== Text input ===
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:
Example code:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting label="32033" type="text" id="username"/>
     <setting label="32033" type="text" id="username" />
</source>
</syntaxhighlight>
 


Values is saved as a string value:
The value entered by the user is saved as a string value on disk:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting id="username" value="john.doe" />
     <setting id="username" value="john.doe" />
</source>
</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.


Attribute:
Attributes:
*option="false" (This controls if text is visible or hidden as password field. Possible values are ''true'' or ''false''.)
* '''id="''string''"''' (required) - the name of the setting.
*option="urlencoded"
* '''label="''id''"''' (required) - an id from the language file that indicates which text to display.
 
* default="''value''" (optional) - the default value.
=== IP address input ===


Example code:
Example code:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting label="32033" type="ipaddress" id="ipaddress"/>
     <setting label="32035" type="ipaddress" id="ipaddress"/>
</source>
</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>


Values is saved as a float value:
<source lang="xml">
    <setting id="ipaddress" value="127.0.0.1" />
</source>


=== 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.


=== Numeric input ===
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:
Example code:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting label="32033" type="number" id="code"/>
     <setting label="32036" type="number" id="code"/>
</source>
</syntaxhighlight>
 


Values is saved as a string value:
The value entered by the user is saved as a string value on disk:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting id="code" value="127000" />
     <setting id="code" value="127000" />
</source>
</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}}


=== Browsing ===


This lets you browse and select for specific media types.


audio|video|image|executable|file|folder
=== 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="32030" default="2015-03-12"/>
</syntaxhighlight>


==== File selector ====
==== 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:
Example code:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting label="32033" type="fileenum" id="file" value="path_to_files"/>
     <setting id="record_time" type="time" label="32031" default="13:13"/>
</source>
</syntaxhighlight>


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


Values is saved as a string value:
==== type="bool" ====
<source lang="xml">
Attributes:
    <setting id="file" value="smb://path_to_files/file.ext" />
* '''id="''string''"''' (required) - the name of the setting
</source>
* '''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>


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


Example code:
The value entered by the user is saved as a string "true" or "false":
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
     <setting id="background" value="false" />
</source>
</syntaxhighlight>


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


Values is saved as a string value:
<source lang="xml">
    <setting id="folder" value="smb://path_to_files/"/>
</source>


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


=== Select dialog ===
Will open separate selection window


==== Audio selector ====
==== 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="select" label="32000" lvalues="32001|32002|32003|32004" />
</syntaxhighlight>


Example code:
<source lang="xml">
    <setting label="32033" type="audio" id="file" value="path_to_files"/>
</source>


==== 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="32111" default="" addontype="xbmc.metadata.scraper.movies"  multiselect="true" />
</syntaxhighlight>


Values is saved as a string value:
=== Spinner ===
<source lang="xml">
A rotary selector allows the user to selected from a list of predefined values.  
    <setting id="file" value="smb://path_to_files/file.ext" />
</source>


==== 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.


=== Bool ===
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
* sort="yes" - sorts labels ( works only for type="labelenum" )


Creates radio button with two states on/off. Set default or value attribute to ''true'' or ''false'' (note case sensitive). Using xbmcplugin.getSetting(pluginId,'setting_id_tag') on a bool will return string ''true'' or ''false''. Use appropriate conversion to turn into real boolean.
Example code:
<syntaxhighlight lang="xml" enclose="div">
    <setting label="32018" type="enum" id="service1" lvalues="32021|32022|32023|32024"/>
    <setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
    <setting label="32022" 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.


Example code:
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.
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting label="32033" type="bool" id="background" default="false"/>
     <setting id="service1" value="0" />
</source>
    <setting id="service3" value="SomethingTranslated" />
</syntaxhighlight>




Values is saved as a string value:
<source lang="xml">
    <setting id="background" value="false" />
</source>


=== Slider ===
Will display a slider control
==== type="slider" ====
Allows the user to select a numberic value 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>


=== Rotary selecting using enum or labelenum ===
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.


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


===type="enum"===
{{Note|In Python, calling xbmcplugin.getSetting will return a string, which must be converted to an int, float or percentage value if needed}}
The "enum" setting will return the index of the selected value:
<source lang="xml">
    <setting label="32019" type="enum" id="service" values="One|Two|Three|Four"/>
</source>
* Selecting the value "One" will return the int value "0", selecting the value "Two" will return the int value "1", etc.


===type="labelenum"===
The "labelenum" setting will return the selected value itself, rather than its index:
<source lang="xml">
    <setting label="32019" type="labelenum" id="service" values="One|Two|Three|Four"/>
</source>
* Selecting the value "One" will return the string value "One", selecting the value "Two" will return the string value "Two", etc.


==== the "lvalues" attribute ====
As previously mentioned, both "enum" and "labelenum" support using language file ids instead of hard-coded string, by using the "lvalues" attribute, rather than "values":
<source lang="xml">
    <setting label="32019" type="labelenum" id="service" lvalues="32001|32002"/>
</source>
* When using "enum", the index of the selected option will be returned as usual. When using "labelenum", the language file id will be returned, as in "32001", "32002", etc. (rather than the text from the language file)


=== Selection ===
=== Browser dialog ===
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.


Selector gives you a control from which you can selected predefined values.
==== type="file", "audio", "video", "image" or "executable" ====
Below are some possible applications.
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:
Attributes:
*mask="" (????????????????)
* '''id="''string''"''' (required) - the name of the setting
*option="" (????????????????)
* '''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="32033" type="file" id="file" default="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>


==== Use value string id ====
==== 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="video", "music", "pictures", "programs", "files", "local" or blank - will show the respective folders from sources.xml in the browse dialog. source="" will list both local drives and network shares.
* default="''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:
Example code:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
     <setting label="32019" type="select" id="service" lvalues="32001|32002"/>
     <setting label="32033" type="folder" id="folder" source="auto" option="writeable"/>
</source>
</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>


Values is saved as a string value:
==== type="fileenum" ====
<source lang="xml">
Display files in a folder as an enum selector.
    <setting id="service" value="32001" />
</source>


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


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


==== Use value string ====
==== Extra attributes ====


Example code:
* mask="''value''" - filter selectable files. Examples: "/" - display only folders. "*.txt" - display only .txt files.
<source lang="xml">
* option="hideext" - hide file extensions.
    <setting label="32019" type="select" id="service" values="One|Two|Three|Four"/>
</source>


Values is saved as a int value:
<source lang="xml">
    <setting id="service" value="1" />
</source>


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


With the slider you can let the user slect a value with the keyboard/mouse specified within the set ranges
Adds line to configuration windows which allow to execute action


Example code:
Example code:
<source lang="xml">
<syntaxhighlight lang="xml" enclose="div">
    <setting label="32053" type="slider" id="limit" default="20" range="5,5,100" option="int" />
     <setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>
     <setting label="32053" type="slider" id="limit" default="20" range="0,100"/>
</syntaxhighlight>
</source>
 


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


Attributes:
Attributes:
*range="min,step,max"
* option="close" (close the settings dialog before executing the action)
    range="5,5,100"
*range="min,max"
    range="5,100"
*option="int" (only shows int values on the slider).
*option="float"
*option="percent"




Values is saved as a float value:
== Conditions ==
<source lang="xml">
    <setting id="limit" value="5.000000" />
</source>


=== Execute action ===


Separator adds a label as separator between other element
'''Settings can optionally have a visible and/or enable attribute:'''
{| class="prettytable" border="0"
|-
| visible="" || "true", "false" or conditional.<br />Determines if the setting is displayed in the settings dialog (default = 'true')"<br />
|-
| enable="" || "true", "false" or conditional.<br />Allows you to determine whether this setting should be shown as greyed-out and unable to be changed.
|-
| conditions || 3 comparators are available to allow a setting to be made visible or enabled based on other settings:
* eq() Equal to
* gt() Greater than
* lt() Less than


Example code:
One can AND the comparators using the + symbol, and OR the comparators using the | symbol. A combination of AND and OR is not currently supported.
<source lang="xml">
    <setting label="32032" type="action" action="RunScript($CWD/resources/lib/viewer.py, downloadreport)"/>
</source>


One can negate a comparator using the ! symbol (e.g. !eq() ).


List of actions that can be used:
Each comparator takes 2 operands:
*[[List_of_built-in_functions]]
* Relative position of setting to compare
* Value to compare against


Thus if we place settings in our file in this order:
: myFirstSetting
: mySecondSetting
: myThirdSetting


Attributes:
for the third setting we might add the option:<br />
*option="close" (close the settings dialog before executing the action)
enable="gt(-2,3) + lt(-2,8)"<br /><br />
You can also use a conditional statement: enable="System.HasAddon(plugin.video.youtube)"


Comparisons CANNOT be made across category/page boundaries. If one needs to compare to a setting on a different page, a copy of the setting with the same id can be placed on the page where the comparison is to take place and then hidden by setting visible to 'false'. The value is automatically updated when the setting on the other page is updated.
|}


==Subsettings==


==See also==
You can create a subsetting by adding '''subsetting="true"''' to a setting.
* [[Add-ons]]
This will add dash in front of the setting.
* [[:Category:All add-ons]]


'''Development:'''
* [[Add-on development]]
* [[Python development]]


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

Latest revision as of 00:17, 18 August 2020

Note: Deprecated - Addons submitted to the Kodi 19 Matrix (and up) can use the new setting format. see Add-on_settings_conversion


Home icon grey.png   ▶ Development ▶ Add-on development ▶ Add-on settings


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 (my.addon.id/resources/settings.xml). If your addon has configurable items that are set by the user, put them here. This file defines what the user sees when they click on Addon settings for your addon. You don't need to do any coding to utilise this functionality. The format for the settings file is relatively straightforward as can be seen in the following example:

Example code: 

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


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

There are some functionality not cover by this wiki page. See C++ source: 

 https://github.com/xbmc/xbmc/tree/master/xbmc/addons/settings/GUIDialogAddonSettings.cpp

Elements

Separators

Separators are purely user-interface elements that do not allow user input and therefore have no meaningful value as a setting.

type="sep"

A line separator, it adds a horizontal line that is useful to separate groups of settings.

Example code: 

    <setting type="sep"/>

type="lsep"

A label separator, it adds a heading text that can be used to display on top of a group of settings.

Attributes:

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

Example code: 

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

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: 

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

The value entered by the user is saved as a string value on disk: 

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

Note: Security consideration: when using option="hidden", 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: 

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

The value entered by the user is saved as a string value on disk: 

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


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: 

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

The value entered by the user is saved as a string value on disk: 

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

Note: In Python, calling xbmcplugin.getSetting will return the number as a string value, which must be converted to an integer 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: 

    <setting id="record_date" type="date" label="32030" default="2015-03-12"/>

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: 

    <setting id="record_time" type="time" label="32031" default="13:13"/>

Boolean

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: 

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

Note: "true" and "false" are case sensitive!

The value entered by the user is saved as a string "true" or "false": 

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

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


Select dialog

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.
    <setting id="id_select" type="select" label="32000" lvalues="32001|32002|32003|32004" />


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
    <setting id="id_addon" type="addon" label="32111" default="" addontype="xbmc.metadata.scraper.movies"  multiselect="true" />

Spinner

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
  • sort="yes" - sorts labels ( works only for type="labelenum" )

Example code: 

    <setting label="32018" type="enum" id="service1" lvalues="32021|32022|32023|32024"/>
    <setting label="32020" type="labelenum" id="service3" lvalues="32021|32022|32023|32024"/>
    <setting label="32022" type="enum" id="default_enumhours" values="$HOURS" />
  • 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. 

    <setting id="service1" value="0" />
    <setting id="service3" value="SomethingTranslated" />


Slider

Will display a slider control

type="slider"

Allows the user to select a numberic value using a horizontal sliding bar.

Example: 

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

Attributes:

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

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

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


Browser dialog

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.
  • default="value" (optional) - the default value.

Example code: 

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

The full path to the file selected by the user is saved as a string value on disk: 

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

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="video", "music", "pictures", "programs", "files", "local" or blank - will show the respective folders from sources.xml in the browse dialog. source="" will list both local drives and network shares.
  • default="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: 

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

The full path to the folder selected by the user is saved as a string value on disk: 

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

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. 

    <setting label="32000" id="myenum" type="fileenum" values="resources" mask="/" />

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: 

    <setting label="32032" type="action" action="RunScript(my.addon.id, downloadreport)"/>

List of actions that can be used:

Attributes:

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


Conditions

Settings can optionally have a visible and/or enable attribute:

visible="" "true", "false" or conditional.
Determines if the setting is displayed in the settings dialog (default = 'true')"
enable="" "true", "false" or conditional.
Allows you to determine whether this setting should be shown as greyed-out and unable to be changed.
conditions 3 comparators are available to allow a setting to be made visible or enabled based on other settings:
  • eq() Equal to
  • gt() Greater than
  • lt() Less than

One can AND the comparators using the + symbol, and OR the comparators using the | symbol. A combination of AND and OR is not currently supported.

One can negate a comparator 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:

myFirstSetting
mySecondSetting
myThirdSetting

for the third setting we might add the option:
enable="gt(-2,3) + lt(-2,8)"

You can also use a conditional statement: enable="System.HasAddon(plugin.video.youtube)"

Comparisons CANNOT be made across category/page boundaries. If one needs to compare to a setting on a different page, a copy of the setting with the same id can be placed on the page where the comparison is to take place and then hidden by setting visible to 'false'. The value is automatically updated when the setting on the other page is updated.

Subsettings

You can create a subsetting by adding subsetting="true" to a setting. This will add dash in front of the setting.

Retrieved from "https://kodi.wiki/index.php?title=Add-on_settings&oldid=219353"