![]() |
![]() |
![]() |
![]() |
The configuration fileThe configuration file — Brief tutorial on writing a configuration file for a plugin |
The configuration file of a plugin is just a GSettings schema with extra tags. This document explains all the extra tags used and sometimes required by LiveWallpaper.
Since LiveWallpaper 0.4 it is possible to use the schema id you want, you just have to set the Schema-id key in the .plugin file. If you don't want to use a custom schema id, you can use the default one: net.launchpad.livewallpaper.plugins.PLUGIN_NAME
The file has to be named
,
where $Module
.xml$Module
is the same name as in the .plugin file.
Example 1. Minimal configuration file
1 2 3 4 5 6 7 |
<?xml version="1.0" encoding="UTF-8"?> <schemalist> <!-- Place your enums here --> <schema id='net.launchpad.livewallpaper.plugins.$Module' path='/net/launchpad/livewallpaper/plugins/'> <!-- Place your keys here --> </schema> </schemalist> |
The configurator reads the keys from top to bottom. So the keys on top of the schema file will also be the first in the configurator. It makes possible to group your keys by categories. LiveWallpaper provides three tags to organize your keys, the <lw:tab> tag, the <lw:frame> tag, and the <lw:separator /> tag.
The <lw:tab> tag tells the configurator to create a new tab that contains all the following keys until the next </lw:tab> tag. Tabs permit you to split your keys by categories (eg: Appearance, Miscellaneous...). The keys located out of a tab won't be shown.
The <lw:frame> tag permits to group tags inside one frame. It works like tabs.
These two tags take one parameter which is the label of the tab in the configurator.
To separate keys in a tab you can use the <lw:separator /> tag. A separator separate two keys with an horizontal line. This tag takes no parameter.
1 2 3 4 5 6 7 |
<lw:tab name="A tab"> <lw:frame name="A frame"> <-- Some keys... --> <lw:separator /> <-- Some keys... --> </lw:frame> </lw:tab> |
Every key consists of the following things:
The configurator supports enums, and the types "b", "y", "n", "q", "i", "u", "x", "t", "d", "s", and can recognize "(dd)" and "as" if specialized with lw:type. More information related to GVariantTypes can be found in the GLib reference manual.
Enumerations allow the user to choose a value from a list of valid choices.
An enumeration consists of an id and a list of nick-value-pairs. The id usually starts with the schema id followed by a dot and the name of the enumeration. The nick of each nick-value-pair will be shown in the configurator in a ComboBox. The value will be internally used to identify the selected option. You can use the value you want, in any order, but you cannot use a value twice per enum.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<?xml version="1.0" encoding="UTF-8"?> <schemalist> <enum id="net.lauchpad.livewallpaper.plugins.$Module.ENUM_NAME"> <value nick="value1" value="2" /> <value nick="value2" value="4" /> <value nick="value3" value="5" /> </enum> <schema id="net.launchpad.livewallpaper.plugins.$Module" path="/net/launchpad/livewallpaper/plugins/"> <key name="enum-key" enum="ENUM.ID"> <default>"value2"</default> <summary>An enum key</summary> <description>Description of this enum key</description> </key> </schema> </schemalist> |
A good place to define your enums is between the schemalist and the schema tag (See Example 1 at the top of the page).
An enumerated key is like any other key, but instead of a data type it needs an enum id. For the default value you have to use the nick of the list element you want as default.
You can use lw_settings_bind_enum()
if you want to bind an enumerated key to a property of a GObject.
To specify the concrete type of a key, you can use the tag lw:type with one of the following values :
LiveWallpaper provides some functions to get colors from GSettings. The easiest way
is to use lw_settings_bind_color()
.
Example 2. A string key which will become a RGBA color container
1 2 3 4 5 6 |
<key type="s" name="color"> <lw:type>color</lw:type> <default>rgba (80, 37, 52, 255)</default> <summary>Color</summary> <description>A RGBA color key</description> </key> |
Example 3. A string array key which will contain a folders list
1 2 3 4 5 6 |
<key type="as" name="folders"> <lw:type>folders</lw:type> <default>["/first/folder", "/second/folder"]</default> <summary>Folders</summary> <description>Use these folders for something</description> </key> |
There are four possible tags to adjust a numeric value:
range: This tag provided by GSettings allows you to set a minimum and a maximum value for your numeric keys.
lw:range: This tag do the same as the previous one for numeric keys, but is also effective on ranges (type '(bb)'). If your key is not a range, you should use range because lw:range is effective only in the configurator and not in gsettings/dconf utilities.
1 |
<range min="0" max="64" /> |
lw:wrap: This tag permits to make the configurator tell Gtk to wrap a numeric value around to the opposite limit when the upper or lower limit of the range is exceeded.
1 |
<wrap /> |
lw:increment: This will set the increment step. The key value will be incremented/decremented by this value if the user makes a <button1> click on the more or the less button of this key in the configurator. This is a special tag only understood by LiveWallpaper, so make sure to put it in a comment.
1 |
<lw:increment>5</lw:increment> |
lw:digits: This will set the number of decimals that will be displayed in the configurator. It will also set the increment to the lowest possible value. This is a special tag so make sure to put it in a comment.
1 |
<lw:digits>2</lw:digits> |
This will set the number of decimals to 2 and the increment step to 0.01.
Example 4. A double precision key with all its possible options
1 2 3 4 5 6 7 8 |
<key type="d" name="double"> <range min="0" max="64" /> <lw:increment>5</lw:increment> <lw:digits>2</lw:digits> <default>8</default> <summary>Double value</summary> <description>An double precision key</description> </key> |
The file(s) and folder(s) selectors can receive a filefilter so that the selected files match with a given pattern or mime-type. You can set several patterns and/or mime-types, and use the built-in pixbuf filter, and name your filter.
Example 5. A string key which will contain the path to a file with filters.
1 2 3 4 5 6 7 |
<key type="s" name="file"> <lw:type>file</lw:type> <lw:filefilter name="My filter" pixbuf="true">text/html;*.vala</lw:filefilter> <default>"/path/to/somewhere.vala"> <summary>File</summary> <description>The path to a file</description> </key> |
In some case you could want the configurator never to show a key. To do this, you should place the hidden key out of a <lw:tab> tag.
Sometimes you might want to show a key/frame/tab only if... To do so you can add the <lw:DisplayIf [attr="val"]/> tag. You cannot write anything you want as condition. The allowed expressions are
computer="[Laptop/Desktop]": Checks whether the computer is a laptop/desktop
lwmin="str": Checks whether the LiveWallpaper version is higher than the one passed in value
lwmax="str": Checks whether the LiveWallpaper version is lower than the one passed in value
Like the tags, the expressions are case sensitive too.
If you need another conditions, please report a bug so that we can consider your mind.