Add-on settings conversion: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
No edit summary
(21 intermediate revisions by 4 users not shown)
Line 29: Line 29:
</syntaxhighlight>
</syntaxhighlight>


* your addon settings file can only have one '''<section>''' tag. (the use of multiple sections is reserved for kodi's main settings.xml file)
* The '''<settings>''' tag '''must''' have a '''version="1"''' attribute (or the '''<section>''' tag will not be supported)
* you can use multiple '''<category>''' tags, just like in the old addon settings format.
* your addon settings file can only have one '''<section>''' tag. the id should be the id of your addon. (the use of multiple sections is reserved for kodi's main settings.xml file)
* you can use multiple '''<category>''' tags, just like in the old addon settings format. the id of a category needs to be a string.
* the '''<group>''' tag is a replacement for the old '''sep''' and '''lsep''' types, you can define multiple groups in order to group a number of settings.
* the '''<group>''' tag is a replacement for the old '''sep''' and '''lsep''' types, you can define multiple groups in order to group a number of settings.


Line 61: Line 62:
<level>0</level>
<level>0</level>
<default/>
<default/>
<constraints>
<allowempty>true</allowempty>
</constraints>
<control type="edit" format="string">
<control type="edit" format="string">
<heading>32001</heading>
<heading>32001</heading>
Line 75: Line 79:
<level>0</level>
<level>0</level>
<default/>
<default/>
<constraints>
<allowempty>true</allowempty>
</constraints>
<control type="edit" format="string">
<control type="edit" format="string">
<heading>32002</heading>
<heading>32002</heading>
Line 90: Line 97:
<level>0</level>
<level>0</level>
<default/>
<default/>
<constraints>
<allowempty>true</allowempty>
</constraints>
<control type="edit" format="urlencoded">
<control type="edit" format="urlencoded">
<heading>32003</heading>
<heading>32003</heading>
Line 204: Line 214:
<constraints>
<constraints>
<options>
<options>
<option label="aa">0</option>
<option>aa</option>
<option label="bb">1</option>
<option>bb</option>
<option label="cc">2</option>
<option>cc</option>
<option label="dd">3</option>
<option>dd</option>
</options>
</options>
<allowempty>true</allowempty>
<allowempty>true</allowempty>
Line 216: Line 226:
</setting>
</setting>
</syntaxhighlight>}}
</syntaxhighlight>}}


==type="addon"==
==type="addon"==
Line 228: Line 237:
<constraints>
<constraints>
<addontype>xbmc.metadata.scraper.movies</addontype>
<addontype>xbmc.metadata.scraper.movies</addontype>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="addon">
<control type="button" format="addon">
Line 246: Line 256:
<constraints>
<constraints>
<addontype>xbmc.metadata.scraper.movies</addontype>
<addontype>xbmc.metadata.scraper.movies</addontype>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="addon">
<control type="button" format="addon">
Line 339: Line 350:
</setting>
</setting>
</syntaxhighlight>}}
</syntaxhighlight>}}
note: for labelenum settings, the label attribute for the options is optional.
if you use it, it can either be a hardcoded string (label="foobar") or a localized id (label="32085").


==type="slider"==
==type="slider"==
Line 408: Line 422:
<constraints>
<constraints>
<writable>false</writable>
<writable>false</writable>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="file">
<control type="button" format="file">
Line 427: Line 442:
<writable>false</writable>
<writable>false</writable>
<masking>audio</masking>
<masking>audio</masking>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="file">
<control type="button" format="file">
Line 446: Line 462:
<writable>false</writable>
<writable>false</writable>
<masking>video</masking>
<masking>video</masking>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="file">
<control type="button" format="file">
Line 465: Line 482:
<writable>false</writable>
<writable>false</writable>
<masking>image</masking>
<masking>image</masking>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="image">
<control type="button" format="image">
Line 484: Line 502:
<writable>false</writable>
<writable>false</writable>
<masking>executable</masking>
<masking>executable</masking>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="file">
<control type="button" format="file">
Line 502: Line 521:
<constraints>
<constraints>
<writable>false</writable>
<writable>false</writable>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
Line 517: Line 537:
<level>0</level>
<level>0</level>
<default/>
<default/>
<constraints>
<allowempty>true</allowempty>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
<heading>32026</heading>
<heading>32026</heading>
Line 536: Line 559:
</sources>
</sources>
<writable>false</writable>
<writable>false</writable>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
Line 556: Line 580:
</sources>
</sources>
<writable>false</writable>
<writable>false</writable>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
Line 576: Line 601:
</sources>
</sources>
<writable>false</writable>
<writable>false</writable>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
Line 596: Line 622:
</sources>
</sources>
<writable>false</writable>
<writable>false</writable>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
Line 616: Line 643:
</sources>
</sources>
<writable>false</writable>
<writable>false</writable>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
Line 636: Line 664:
</sources>
</sources>
<writable>false</writable>
<writable>false</writable>
<allowempty>true</allowempty>
</constraints>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
Line 652: Line 681:
<level>0</level>
<level>0</level>
<data>RunScript(script.globalsearch)</data>
<data>RunScript(script.globalsearch)</data>
<constraints>
<allowempty>true</allowempty>
</constraints>
<control type="button" format="action">
<control type="button" format="action">
<close>true</close>
<close>true</close>
Line 663: Line 689:


<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang="xml" enclose="div">
<setting type="action" id="test34" label="32034" action="RunScript(weather.yahoo)" default=""/>
<setting type="action" id="test34" label="32034" action="RunScript(weather.yahoo,Location1)" default=""/>
</syntaxhighlight>
</syntaxhighlight>
{{hidden|style = width: 60%;|headerstyle = background: #cccccc;|contentstyle = text-align: left; border: 0px solid #AAAAAA;|New Setting Format |<syntaxhighlight lang="xml" enclose="div">
{{hidden|style = width: 60%;|headerstyle = background: #cccccc;|contentstyle = text-align: left; border: 0px solid #AAAAAA;|New Setting Format |<syntaxhighlight lang="xml" enclose="div">
<setting id="test34" type="string" label="32034" help="">
<setting id="test34" type="string" label="32034" help="">
<level>0</level>
<level>0</level>
<default/>
<constraints>
<constraints>
<allowempty>true</allowempty>
<allowempty>true</allowempty>
Line 677: Line 704:
</syntaxhighlight>}}
</syntaxhighlight>}}


You can use the variables <code>$ID</code> and <code>$CWD</code> in your actions. <code>$ID</code> will be replaced by your add-on ID and <code>$CWD</code> with your add-on path:
{{hidden|style = width: 60%;|headerstyle = background: #cccccc;|contentstyle = text-align: left; border: 0px solid #AAAAAA;|New Setting Format - Add-on ID |<syntaxhighlight lang="xml" enclose="div">
<setting>
<control type="button" format="action">
<data>RunPlugin(plugin://$ID/foo)</data>
</control>
</setting>
</syntaxhighlight>}}


==type="fileenum"==
==type="fileenum"==
Line 688: Line 725:
<level>0</level>
<level>0</level>
<default>/home/ronie/.kodi/addons/script.settings-convert/resources</default>
<default>/home/ronie/.kodi/addons/script.settings-convert/resources</default>
<constraints>
<allowempty>true</allowempty>
</constraints>
<control type="button" format="file">
<control type="button" format="file">
<heading>32035</heading>
<heading>32035</heading>
Line 705: Line 739:
<level>0</level>
<level>0</level>
<default>/home/ronie/.kodi/addons/script.settings-convert/resources</default>
<default>/home/ronie/.kodi/addons/script.settings-convert/resources</default>
<constraints>
<allowempty>true</allowempty>
</constraints>
<control type="button" format="path">
<control type="button" format="path">
<heading>32036</heading>
<heading>32036</heading>
Line 723: Line 754:
<default>/home/ronie/.kodi/addons/script.settings-convert/resources</default>
<default>/home/ronie/.kodi/addons/script.settings-convert/resources</default>
<constraints>
<constraints>
<allowempty>true</allowempty>
<masking>*.txt</masking>
<masking>*.txt</masking>
</constraints>
</constraints>
Line 731: Line 761:
</setting>
</setting>
</syntaxhighlight>}}
</syntaxhighlight>}}
==type="colorbutton"==
colorbutton type settings allow a user to open a color picker dialog to select a color from Kodi's default color list.
When the color has been selected, you can preview the colour and the hex code.
{{note|Available from Kodi v20}}
<syntaxhighlight lang="xml" enclose="div">
<setting id="test36.color" type="string" label="32035" help="">
<level>0</level>
<default>FF000000</default> <!-- Black -->
<control type="colorbutton" />
</setting>
</syntaxhighlight>


=Subsetting=
=Subsetting=
Line 743: Line 787:
<syntaxhighlight lang="xml" enclose="div"><visible>false</visible></syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div"><visible>false</visible></syntaxhighlight>


if a settings should be conditionallly visible, add a dependency tag to your setting
if a settings should be conditionallly visible, add a dependencies section to your setting
<syntaxhighlight lang="xml" enclose="div"><dependency type="visible" setting=""></dependency></syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="visible" setting=""></dependency>
</dependencies></syntaxhighlight>


==enable==
if a setting should always be disabled, you can add this to the setting
<syntaxhighlight lang="xml" enclose="div"><enable>false</enable></syntaxhighlight>
if a settings should be conditionally enabled, add a dependencies section to your setting
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" setting=""></dependency>
</dependencies>
</syntaxhighlight>


==enable==
== infobool ==
if a settings should be conditionallly enabled, add a dependency tag to your setting
enabling based on a boolean condition
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" setting=""></dependency></syntaxhighlight>


<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" on="property" name="infobool">system.platform.android</dependency>
</dependencies>
</syntaxhighlight>


== eq / lt / gt ==
== eq / lt / gt ==
Line 757: Line 818:


compare to a bool value of another setting
compare to a bool value of another setting
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" setting="test01">true</dependency></syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" setting="test01">true</dependency>
</dependencies>
</syntaxhighlight>


compare to a int value of another setting
compare to a int value of another setting
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" setting="test01">5</dependency></syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" setting="test01">5</dependency>
</dependencies>
</syntaxhighlight>


compare to a string value of another setting
compare to a string value of another setting
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" setting="test01">something</dependency></syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" setting="test01">something</dependency>
</dependencies>
</syntaxhighlight>


'''!eq'''
'''!eq'''
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" operator="!is" setting="test01">true</dependency></syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" operator="!is" setting="test01">0</dependency></syntaxhighlight>
<dependencies>
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" operator="!is" setting="test01"></dependency></syntaxhighlight>
<dependency type="enable" operator="!is" setting="test01">true</dependency>
</dependencies>
</syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" operator="!is" setting="test01">0</dependency>
</dependencies>
</syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" operator="!is" setting="test01"></dependency>
</dependencies>
</syntaxhighlight>


'''lt'''
'''lt'''
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" operator="lt" setting="test01">5</dependency></syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" operator="lt" setting="test01">5</dependency>
</dependencies>
</syntaxhighlight>


'''gt'''
'''gt'''
<syntaxhighlight lang="xml" enclose="div"><dependency type="enable" operator="gt" setting="test01">0</dependency></syntaxhighlight>
<syntaxhighlight lang="xml" enclose="div">
<dependencies>
<dependency type="enable" operator="gt" setting="test01">0</dependency>
</dependencies>
</syntaxhighlight>


== and / or==
== and / or==
multiple dependencies can be defined as such
multiple dependencies can be defined as such
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang="xml" enclose="div">
<dependency type="enable">
<dependencies>
<and>
<dependency type="enable">
<condition setting=""></condition>
<and>
<condition setting=""></condition>
<condition setting=""></condition>
</and>
<condition setting=""></condition>
</dependency>
</and>
</dependency>
</dependencies>
</syntaxhighlight>
</syntaxhighlight>


<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang="xml" enclose="div">
<dependency type="enable">
<dependencies>
<or>
<dependency type="enable">
<condition setting=""></condition>
<or>
<condition setting=""></condition>
<condition setting=""></condition>
</or>
<condition setting=""></condition>
</dependency>
</or>
</dependency>
</dependencies>
</syntaxhighlight>
</syntaxhighlight>



Revision as of 08:12, 23 October 2021

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

Converting addon settings

Preface

As of Kodi 18 Leia it is possible to write your addon settings in the same setting format as Kodi uses. Due to many initial issues, it is not recommended to convert your settings if your addon is in the Leia addon repo.

In Kodi 19 Matrix, those bugs have been fixed, so we recommend to convert your addon settings if you plan to submit your addon to the Matrix addon repo (or higher).

Structure

The structure of your settings.xml file should look like this

<?xml version="1.0" ?>
<settings version="1">
	<section id="my.addon.id">
		<category id="general" label="" help="">
			<group id="1" label="">
				<setting id="" type="" label="" help="">
					<control type="" format=""/>
				</setting>
			</group>
		</category>
	</section>
</settings>
  • The <settings> tag must have a version="1" attribute (or the <section> tag will not be supported)
  • your addon settings file can only have one <section> tag. the id should be the id of your addon. (the use of multiple sections is reserved for kodi's main settings.xml file)
  • you can use multiple <category> tags, just like in the old addon settings format. the id of a category needs to be a string.
  • the <group> tag is a replacement for the old sep and lsep types, you can define multiple groups in order to group a number of settings.

Level

Similar to Kodi settings, addons can now define a setting level for every setting.
This will show or hide certain settings based on the settings level the user has selected (Basic, Standard, Advanced, Expert).

<setting id="" type="" label="" help="">
	<level>0</level>
</setting>

The various levels are defined as such:

  • 0 - Basic
  • 1 - Standard
  • 2 - Advanced
  • 3 - Expert
  • 4 - Internal (will never be shown in the GUI)

Setting types

type="text"

<setting type="text" id="test01" label="32001" default=""/>


<setting type="text" id="test02" label="32002" default="" option="hidden"/>


<setting type="text" id="test03" label="32003" default="" option="urlencoded"/>


type="ipaddress"

<setting type="ipaddress" id="test04" label="32004"/>


type="number"

<setting type="number" id="test05" label="32005"/>

type="date"

<setting type="date" id="test06" label="32006" default="2015-03-12"/>


type="time"

<setting type="time" id="test07" label="32007" default="13:13"/>


type="bool"

<setting type="bool" id="test08" label="32008" default="false"/>


type="select"

<setting type="select" id="test09" label="32009" lvalues="11|12|13|14"/>


<setting type="select" id="test10" label="32010" values="aa|bb|cc|dd"/>

type="addon"

<setting type="addon" id="test11" label="32011" default="" addontype="xbmc.metadata.scraper.movies"/>


<setting type="addon" id="test12" label="32012" default="" addontype="xbmc.metadata.scraper.movies" multiselect="true"/>


type="enum"

<setting type="enum" id="test13" label="32013" lvalues="11|12|13|14"/>


<setting type="enum" id="test14" label="32014" values="aa|bb|cc|dd"/>

type="labelenum"

in case you use lvalues in a labelenum control, the saved value will now be the string id, instead of the localized string. please adapt your python code for this.

<setting type="labelenum" id="test15" label="32015" lvalues="11|12|13|14"/>


<setting type="labelenum" id="test16" label="32016" values="bb|aa|dd|cc" sort="yes"/>

note: for labelenum settings, the label attribute for the options is optional. if you use it, it can either be a hardcoded string (label="foobar") or a localized id (label="32085").

type="slider"

<setting type="slider" id="test17" label="32017" default="20" range="5,5,100" option="int"/>


<setting type="slider" id="test18" label="32018" default="0.5" range="0.0,0.1,1.0" option="float"/>


<setting type="slider" id="test19" label="32019" default="20" range="0,1,100" option="percent"/>


type="file"

<setting type="file" id="test20" label="32020" default=""/>


type="audio"

<setting type="audio" id="test21" label="32021" default=""/>


type="video"

<setting type="video" id="test22" label="32022" default=""/>


type="image"

<setting type="image" id="test23" label="32023" default=""/>


type="executable"

<setting type="executable" id="test24" label="32024" default=""/>


type="folder"

<setting type="folder" id="test25" label="32025" default=""/>


<setting type="folder" id="test26" label="32026" default="" option="writeable"/>


<setting type="folder" id="test27" label="32027" default="" source="videos"/>


<setting type="folder" id="test28" label="32028" default="" source="music"/>


<setting type="folder" id="test29" label="32029" default="" source="pictures"/>


<setting type="folder" id="test30" label="32030" default="" source="programs"/>


<setting type="folder" id="test31" label="32031" default="" source="files"/>


<setting type="folder" id="test32" label="32032" default="" source="local"/>


type="action"

<setting type="action" id="test33" label="32033" action="RunScript(script.globalsearch)" option="close"/>


<setting type="action" id="test34" label="32034" action="RunScript(weather.yahoo,Location1)" default=""/>


You can use the variables $ID and $CWD in your actions. $ID will be replaced by your add-on ID and $CWD with your add-on path:

type="fileenum"

fileenum type settings (which was basically a spincontrol listing all items) are no longer supported. these settings can be converted into a file or folder browser.

<setting type="fileenum" id="test35" label="32035" values="resources"/>


<setting type="fileenum" id="test36" label="32036" values="resources" mask="/"/>


<setting type="fileenum" id="test37" label="32037" values="resources" mask="*.txt"/>

type="colorbutton"

colorbutton type settings allow a user to open a color picker dialog to select a color from Kodi's default color list. When the color has been selected, you can preview the colour and the hex code.

Note: Available from Kodi v20

<setting id="test36.color" type="string" label="32035" help="">
	<level>0</level>
	<default>FF000000</default> <!-- Black -->
	<control type="colorbutton" />
</setting>

Subsetting

if you wish to define a subsetting, you can use the parent attribute with the id of the parent setting as the value.

<setting id="test37" type="path" label="32037" help="" parent="test36">


Conditions

visible

if a setting should always be hidden, you can add this to the setting

<visible>false</visible>

if a settings should be conditionallly visible, add a dependencies section to your setting

<dependencies>
	<dependency type="visible" setting=""></dependency>
</dependencies>

enable

if a setting should always be disabled, you can add this to the setting

<enable>false</enable>

if a settings should be conditionally enabled, add a dependencies section to your setting

<dependencies>
	<dependency type="enable" setting=""></dependency>
</dependencies>

infobool

enabling based on a boolean condition

<dependencies>
	<dependency type="enable" on="property" name="infobool">system.platform.android</dependency>
</dependencies>

eq / lt / gt

eq

compare to a bool value of another setting

<dependencies>
	<dependency type="enable" setting="test01">true</dependency>
</dependencies>

compare to a int value of another setting

<dependencies>
	<dependency type="enable" setting="test01">5</dependency>
</dependencies>

compare to a string value of another setting

<dependencies>
	<dependency type="enable" setting="test01">something</dependency>
</dependencies>

!eq

<dependencies>
	<dependency type="enable" operator="!is" setting="test01">true</dependency>
</dependencies>
<dependencies>
	<dependency type="enable" operator="!is" setting="test01">0</dependency>
</dependencies>
<dependencies>
	<dependency type="enable" operator="!is" setting="test01"></dependency>
</dependencies>

lt

<dependencies>
	<dependency type="enable" operator="lt" setting="test01">5</dependency>
</dependencies>

gt

<dependencies>
	<dependency type="enable" operator="gt" setting="test01">0</dependency>
</dependencies>

and / or

multiple dependencies can be defined as such

<dependencies>
	<dependency type="enable">
		<and>
			<condition setting=""></condition>
			<condition setting=""></condition>
		</and>
	</dependency>
</dependencies>
<dependencies>
	<dependency type="enable">
		<or>
			<condition setting=""></condition>
			<condition setting=""></condition>
		</or>
	</dependency>
</dependencies>