The configuration file

The configuration file — Brief tutorial on writing a configuration file for a plugin

The configuration file

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.

Schema id

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


Filename and installation path

The file has to be named $Module.xml, where $Module is the same name as in the .plugin file.

Example 1. Minimal configuration file

<?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>

Tabs and separators

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.

<lw:tab name="A tab">
	<lw:frame name="A frame">
		<-- Some keys... -->
		<lw:separator />
		<-- Some keys... -->
	</lw:frame>
</lw:tab>

Keys

Every key consists of the following things:

  • type: The data type of the key. This document explains the most common data types in the following sections.
  • name: An internal name for the key. You use this name to get the value of the key or to bind it to a property of a GObject.
  • summary: A summary of the key that will be shown in the configurator.
  • description: A description of the key. It will be shown as tooltip in the configurator.

Types

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

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.

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

Specialized types

  • Sometimes, a specific widget can be used to control the data entered by the user and help him to fill the inputs with a correct value, so that select a file or a color doesn't requires to type it manually.
  • Union types and arrays are not understood by the configurator as it doesn't know how to display them by default.

To specify the concrete type of a key, you can use the tag lw:type with one of the following values :

  • range: Shows a range selector. [base type : (dd)]
  • file: Shows a file selector [base type : s]
  • folder: Shows a folder selector [base type : s]
  • folders: Shows a list with two buttons to add or remove directories. [base type : as]
  • files: Shows a list with two buttons to add or remove files. [base type : as]
  • font: Shows a font selector [base type : s]
  • color: Shows a RGBA color chooser. [base type : s]

    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

<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

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

Labels

Special tag that permits to add a text in the configurator.
<lw:label>
    Hello World
</lw:label>
                    

Constraints and behavior modifiers

For numeric values (except booleans, including lw:range)

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.

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

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

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

    <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

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

For file(s) and folder(s) selectors

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.

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

Tab/Frames/Keys/Labels visibility

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.