1
<section id="prefs-system" xmlns:xi="http://www.w3.org/2001/XInclude">
2
<title>Preferences System</title>
4
<section><title>Preferences Dialog</title>
6
<para>Every applet can provide a dialog where users can change the
8
This dialog usually consists of several pages for different categories,
9
and is defined in the <filename>.display</filename> file inside the
10
<link linkend="prefs-tag-prefs"><command><prefs></command></link>
13
<para>Each of the pages lists a number of configuration elements, such as
14
entry fields, spin buttons, file selectors, font selectors, etc.</para>
19
<imagedata fileref="gfx/prefs" format="PNG"/>
28
<section><title>Bindings</title>
30
<para>Every configuration element is directly bound to a readable and
31
writable object in the scripting environment. This can be a control property
32
as well as a display element's property, or just a variable in the scripts.
35
<para>The bound object is where you can read the configuration setting from.
36
The direct binding can be seen in the following example.</para>
38
<programlisting><![CDATA[
41
<label id="mylabel" value="Change me!" font="Serif 1cm"/>
46
<string label="Label Text:" bind="Dsp.mylabel.value"/>
53
<para>After opening the preferences dialog, you can change the value of the
54
label by editing the string configuration element. If you restart the
55
display or <application>gDesklets</application>, you will see that the
56
current label text has been saved.</para>
58
<para>That way it is possible to save the configuration of any object across
65
<section><title>Default Value</title>
67
<para>The default value for any configuration setting is the initial value of
68
the object to which it is bound. The settings are read in after the
69
initialization of the display. So, if values were saved, the bound objects
70
will be set to them immediately after the initialization phase.</para>
76
<section><title>Callback Function <emph>[new in 0.34]</emph></title>
78
<para>Sometimes, it is neccessary to react to configuration changes in a
79
special way. For example, an URI should be checked for validity before it
80
is actually being used. The
81
<link linkend="prefs-tag-prefs"><command><prefs></command></link> tag,
82
as well as all other preferences tags, provides a callback hook for that
85
<para>It may also be beneficial to change preferences when others change.
86
This can be done with the <literal>Prefs</literal> namespace.</para>
88
<programlisting><![CDATA[
89
<prefs callback="prefs_cb">
93
<boolean id="ex_bool" label="Checkbox!" bind="ex_bool_is_set" callback="check_ex_bool"/>
95
<enum id="e" label="some enum" bind="foo"/>
103
Prefs.e.items = [(label, value), (label, value), (label, value)]
104
Prefs.ex_bool.value = False
110
<para>The callback function specified in the hook will be called whenever
111
a configuration setting changes its value. The callback function is called
112
with two arguments; the name of the bound object, and the new value.</para>
added
removed
doc/book/prefs-system.xml
