Add-on settings
Description
settings.xml is a XML file that contains the current configuration for the addon and should be places in the resources direcory. If your addon has configurable items that are set by the user, put them here. This file defines what the user sees when they click on Addon settings for your addon. You don't need to do any coding to utilise this functionality. The format for the settings file is relatively straightforward as can be seen in the following example:
Example code:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <settings> <category label=”32001”> <setting label="32011" type="text" id="username" default=""/> <setting label="32012" type="text" id="password" option="hidden" enable="!eq(-1,)" default=""/> <setting label="32053" type="slider" id="limit" subsetting="true" default="20" range="5,5,100" option="int" /> <setting type="sep"/> <setting id="debug" type="bool" label="32013" default="false"/> </category> </settings>
You need to supply at least one category element.
The label attribute of both categories and settings should be the id of a language string in your language files or the one of the main XBMC language file.
Different types
Setting type and additional attributes can be one in the following table:
Type | Description | Value attribute (value="") | Notes |
---|---|---|---|
text | Creates keyboard input | Can have 'option' attribute set “true” or “false”, will hide the text value if false. | |
file | Creates a file selector | ||
folder | Creates a folder selector | ||
enum | Creates a select box | separated list of values: '1|3|5|10|All' | Using xbmcplugin.getSetting(pluginId,'mytagname') on an enum will return the index into the list, not the value itself. Also be aware that 1 digit indexes may be returned as '01', '02' etc |
labelenum | Same as enum except the value is returned by getSetting() instead of the index | ||
ipaddress | Creates IP dialog | ||
number | Creates numeric dialog | ||
bool | Creates radio button | Set default or value attribute to to “true” or “false” (note case). Using xbmcplugin.getSetting(pluginId,'mytagname') on a bool will return 'true' or 'false'. Use appropriate conversion to turn into real boolean. | |
sep | Creates a separator line in the dialog | Ignored | |
music | |||
video | |||
pictures | |||
programs | |||
local | |||
fileenum | Create a file selector based on path set in value attribute | Set value to root of directory you want to use for selection | |
action | Executes a script when selected | Set the 'action' attribute to the name of your function to execute: action="RunPlugin(plugin://video/Apple Movie Trailers Plugin/?update=newest)" Optionally set the 'option' attribute to “close” if you want to close the settings dialog when you click the setting. |
Settings can have additional attributes:
source="" | "video", "music", "pictures", "programs", "files", "local" or blank." if source is blank it will use the type for shares if it is a valid share if not a valid share it will use, both local and network drives. |
visible="" | "true", "false" or conditional." Determines if the setting is displayed in the settings dialog (default = 'true')" You can also use a conditional statement: visible="System.HasAddon(plugin.video.youtube)" |
enable="" | Allows you to determine whether this setting should be shown based on the value of another setting. 3 comparators are available:"
You can AND the comparators using the + symbol and negate it using the ! symbol (e.g. !eq() ). Each comparator takes 2 operands:
Thus if we place settings in our file in this order:
for the third setting we might add the option: |
Elements
Line separator
Separator adds a horizontal separating line between other element
Example code:
<setting type="sep"/>
Label separator
Separator adds a label as separator between other element
Example code:
<setting label="32032" type="lsep"/>
Bool
This add a bool switch with two states "on|off" (true|false).
Example code:
<setting label="32033" type="bool" id="background" default="false"/>
Selector
Selector gives you a control from which you can selected predefined values. Below are some possible applications.
Return string
Example code:
<setting label="32019" type="labelenum" id="service" values="One|Two|Three|Four"/>
Selected value "Two" will return string value "Two"
Return int
This return the int value of the selected value starting with 0
Example code:
<setting label="32019" type="enum" id="service" values="One|Two|Three|Four"/>/>
Selected value "Two" will return int value "1"
Use value string id
Import code part:
lvalues="32001|32002"
Example code:
<setting label="32019" type="labelenum" id="service" lvalues="32001|32002"/>
Use value string
Import code part:
values="foo|bar"
Example code:
<setting label="32019" type="labelenum" id="service" values="One|Two|Three|Four"/>
Slider
With the slider you can let the user slect a value with the keyboard/mouse specified within the set ranges
Example code:
<setting label="32053" type="slider" id="limit" subsetting="true" default="20" range="5,5,100" option="int" /> <setting label="32053" type="slider" id="limit" subsetting="true" default="20" range="5,100" option="int" />
Specific options:
range="min,step,max"
range="5,5,100"
range="min,max"
range="5,100"
option="int" (only shows int values on the slider. Values is saved as a float value)
<setting id="limit" value="5.000000" />
See also
Development: