« back to all changes in this revision
Viewing changes to doc/gconf/gconf.sgml
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Takuo KITAME
- Date: 2002-03-17 01:51:39 UTC
- Revision ID: james.westby@ubuntu.com-20020317015139-z4f8fdg1hoe049g0
Tags: upstream-1.0.9
Import upstream version 1.0.9
- files added:
- backends
- doc
- doc/gconf
- doc/gconf/tmpl
- examples
- gconf
- po
- standard-schemas
- tests
- wrappers
- wrappers/gtk
added
removed
doc/gconf/gconf.sgml
1
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
2
<!entity GConfClient SYSTEM "sgml/gconf-client.sgml">
3
<!entity gconf-gconf-backend SYSTEM "sgml/gconf-backend.sgml">
4
<!entity gconf-gconf-engine SYSTEM "sgml/gconf-engine.sgml">
5
<!entity gconf-gconf-error SYSTEM "sgml/gconf-error.sgml">
6
<!entity gconf-gconf-internals SYSTEM "sgml/gconf-internals.sgml">
7
<!entity gconf-gconf-listeners SYSTEM "sgml/gconf-listeners.sgml">
8
<!entity gconf-gconf-schema SYSTEM "sgml/gconf-schema.sgml">
9
<!entity gconf-gconf-sources SYSTEM "sgml/gconf-sources.sgml">
10
<!entity gconf-gconf-value SYSTEM "sgml/gconf-value.sgml">
11
<!entity gconf-gconf SYSTEM "sgml/gconf.sgml">
12
<!entity gconf-gconf-locale SYSTEM "sgml/gconf-locale.sgml">
13
<!entity gconf-gconf-changeset SYSTEM "sgml/gconf-changeset.sgml">
14
]>
15
<book id="index">
16
<bookinfo>
17
<authorgroup>
18
<author>
19
<firstname>Havoc</firstname>
20
<surname>Pennington</surname>
21
<affiliation>
22
<orgname>Red Hat Advanced Development Labs</orgname>
23
</affiliation>
24
<authorblurb>
25
<para>
26
<email>hp@redhat.com</email>
27
</para>
28
</authorblurb>
29
</author>
30
</authorgroup>
31
<copyright>
32
<year>1999</year>
33
<holder>Havoc Pennington</holder>
34
</copyright>
35
36
<!-- GConf -->
37
<title>GConf Manual</title>
38
<abstract>
39
<para>
40
GConf is a system for storing configuration information, that is,
41
key-value pairs. GConf provides a notification service so applications
42
can be notified when a key's value is changed. GConf also allows for
43
pluggable storage mechanisms (text files, databases, etc.); allows
44
administrators to install default values; and allows application authors
45
to document their configuration keys for the benefit of administrators.
46
</para>
47
48
</abstract>
49
50
51
<legalnotice>
52
<para>
53
This document may be distributed subject to the terms and
54
conditions set forth in the Open Publication License, v1.0 or
55
later (the latest version is presently available at <ulink
56
url=" http://www.opencontent.org/openpub/"
57
type="http">http://www.opencontent.org/openpub/</ulink> )
58
</para>
59
</legalnotice>
60
61
</bookinfo>
62
63
<!-- Introduction to GConf -->
64
<chapter>
65
<title>Introduction to GConf</title>
66
67
<para>
68
This chapter introduces GConf, including the basic terms and
69
concepts. After reading it, if you're a GNOME programmer looking
70
to dive in quickly, you might skip to <xref
71
linkend="gconfclient-example">. If you want to have
72
comprehensive knowledge of GConf, you might want to read the
73
whole manual.
74
</para>
75
76
<!-- Motivation -->
77
<sect1>
78
<title>Motivation</title>
79
80
<para>
81
GConf is intended to store key-value pairs, where keys are
82
located in an infinite tree-structured namespace (similar to the
83
UNIX filesystem). It offers several useful features:
84
<itemizedlist mark="bullet">
85
<listitem>
86
<para>
87
Users can select a variety of data storage backends, such as XML
88
text files, ACAP, or databases (LDAP, DB, etc.). This makes it
89
easy to adapt GConf to local needs. It also avoids the age-old
90
"text files vs. binary registry" debate. (Note: the current GConf
91
only has an XML backend implemented, other backends are easy to
92
write though.)
93
</para>
94
</listitem>
95
<listitem>
96
<para>
97
GConf offers a notification service, so applications can
98
ask to be notified when the value of a key changes.
99
This allows settings to be applied to groups of
100
applications, without restarting them and without
101
ugly hacks. It also allows a clean model-view
102
architecture for applications.
103
</para>
104
</listitem>
105
<listitem>
106
<para>
107
Each user has a "GConf search path" which is a list of
108
configuration sources to scan for each value.
109
For example, the configuration engine might look for
110
values first in the local machine's database and
111
then in a network-wide database.
112
</para>
113
</listitem>
114
<listitem>
115
<para>
116
GConf is implemented as a per-user daemon, which makes
117
locking a non-issue and allows aggressive caching.
118
</para>
119
</listitem>
120
<listitem>
121
<para>
122
The client API is simple and very abstract, which allows us to
123
change its implementation at a later time without a big headache.
124
Because a good implementation is a complex problem, this is
125
important.
126
</para>
127
</listitem>
128
129
</itemizedlist>
130
</para>
131
132
<para>
133
GConf was inspired by Wichert Akkerman's configuration system
134
specification, originally developed for the Debian project. See <ulink
135
url="http://www.debian.org/~wakkerma/config6"
136
type="http">http://www.debian.org/~wakkerma/config6</ulink> for his
137
specification. Other sources of ideas include the Windows registry,
138
the ACAP specification, and Emacs customize mode (try typing
139
<literal>M-x customize-browse</literal> in Emacs).
140
</para>
141
142
</sect1>
143
144
<!-- Terms and Concepts -->
145
<sect1>
146
<title>Terms and Concepts</title>
147
148
<para>
149
This section introduces the basic GConf structure and terminology.
150
</para>
151
152
<sect2>
153
<title>Namespace</title>
154
<para>
155
The GConf namespace is almost exactly like the UNIX filesystem; that
156
is, a tree structured directory hierarchy. Each name is either a
157
"file" (a configuration key storing a value) or a "directory" (a list
158
of child configuration key names). A name is specified with a
159
slash-separated path. A full path is referred to as a
160
<firstterm>key</firstterm>. Characters in a path should be
161
alphanumeric or underscore. Path components may not start with a
162
period.
163
</para>
164
</sect2>
165
166
<!-- Data Types -->
167
<sect2>
168
<title>GConf Data Types</title>
169
170
<para>
171
GConf can only store a small, fixed set of data types. This keeps the
172
database implementation simple and efficient. GConf should
173
<emphasis>not</emphasis> be used to store data files or any other
174
large amount of information; <emphasis>it is designed for simple
175
configuration data only</emphasis>. There are any number of better
176
solutions available for storing documents and other large data
177
chunks. You might want to store a filename, URL, or Bonobo moniker in
178
GConf pointing to a larger piece of data, if you need the GConf
179
notification facilities.
180
</para>
181
182
<para>
183
Here are the GConf datatypes:
184
<variablelist>
185
186
<varlistentry>
187
<term>Integer</term>
188
<listitem><para>
189
Integer values are simple C-style integers, that is, they are
190
limited to 32 bits and can be positive or negative.
191
</para></listitem>
192
</varlistentry>
193
194
<varlistentry>
195
<term>String</term> <listitem><para> String values can contain any
196
text you like, but not binary data (such as the NULL character).
197
GConf should handle any string the C library string functions can
198
handle. </para></listitem>
199
</varlistentry>
200
201
<varlistentry>
202
<term>Float</term> <listitem><para> Float values are floating
203
point numbers. Given differences between machine architectures
204
and C libraries, there is no guaranteed degree of precision, other
205
than "a reasonable degree."
206
</para></listitem>
207
</varlistentry>
208
209
<varlistentry>
210
<term>Bool</term>
211
<listitem><para>
212
Boolean values are true or false.
213
</para></listitem>
214
</varlistentry>
215
216
<varlistentry>
217
<term>Schema</term>
218
<listitem><para>
219
Schemas store a <structname>GConfSchema</structname>
220
data type, which contains meta-information about a key, such
221
as documentation and its type.
222
</para></listitem>
223
</varlistentry>
224
225
<varlistentry>
226
<term>List</term>
227
<listitem><para> List values store a group of
228
values. All values in a list must have the same primitive
229
type. Heterogeneous lists are not allowed. Lists of lists and
230
lists of pairs are not allowed.
231
</para></listitem>
232
</varlistentry>
233
234
<varlistentry>
235
<term>Pair</term>
236
<listitem><para> Pairs store two primitive
237
values. The two values do not necessarily have the same
238
type. Pairs can not contain pairs or lists, only primitive types.
239
</para></listitem>
240
</varlistentry>
241
242
</variablelist>
243
</para>
244
245
</sect2>
246
247
<!-- Sources -->
248
<sect2>
249
<title>Configuration Sources</title>
250
251
<para> Users can specify <firstterm>configuration sources</firstterm>
252
which will be used by the <application>gconfd</application> per-user
253
configuration server. <application>gconfd</application> loads the
254
file <filename>/etc/gconf/path</filename> (or
255
<filename>${sysconfdir}/gconf/path</filename>) on startup; this file
256
contains a list of <firstterm>configuration source
257
addresses</firstterm>. A source address is similar to a URL; it
258
contains a "protocol" name (in this case, the name of the backend to
259
use), followed by a colon, standard flags separated by commands,
260
another colon, and then backend-specific information. For example, the
261
address <filename> xml:readonly:/home/hp/.gconf.xml</filename> refers
262
to an XML backend file tree rooted at
263
<filename>/home/hp/.gconf.xml</filename> that should be "mounted
264
readonly" so that no data is written to it.
265
</para>
266
267
<para>
268
<filename>/etc/gconf/path</filename> stores a list of
269
addresses, which form a <firstterm>configuration source
270
path</firstterm>. When looking up a value, GConf will begin
271
with the first source in the path, and continue checking
272
each source until the value is found or there are no more
273
sources. When setting a value, GConf will use the first
274
<emphasis>writable</emphasis> source. System
275
administrators can impose <emphasis>mandatory</emphasis>
276
settings on their users by placing a read-only source at the
277
front of the path (note that "mandatory" only means that
278
existing programs won't let them change the value, users
279
could hack their own copy of GConf that ignored system
280
settings). If a key has a value in a read-only source placed
281
before the first user-writable source, user applications
282
attempting to set that value will receive an error.
283
Administrators can provide <emphasis>default</emphasis>
284
values by placing a systemwide source at the end of the
285
configuration source path.
286
</para>
287
288
<para>
289
The source configuration file can contain "include" statements and
290
some magic variables; you can use this to include a .gconf.path file
291
from the user's home directory. Variables are placed in
292
<symbol>$()</symbol>. Two variables are built-in to GConf:
293
<symbol>$(HOME)</symbol> is the user's home directory, and
294
<symbol>$(USER)</symbol> is the username. You can also access any
295
environment variable by prepending <symbol>ENV_</symbol> to the
296
variable name. For example, <symbol>$(ENV_FOO)</symbol> will be
297
replaced by the <symbol>FOO</symbol> environment variable.
298
</para>
299
300
<para>
301
So once everything is working a
302
<filename>/etc/gconf/path</filename> file might look like
303
this:
304
<programlisting>
305
# GConf configuration path file with an include statement
306
xml:readonly:/etc/gconf.xml.mandatory
307
include "$(HOME)/.gconf.path"
308
xml:readonly:/etc/gconf.xml.defaults
309
# imaginary, no LDAP backend exists right now
310
ldap::/foo/bar/whatever/ldap/address
311
</programlisting>
312
</para>
313
314
<para>
315
Note that particular backend modules may have their own special
316
configuration. For example, you may need to configure the details of
317
an LDAP backend.
318
</para>
319
320
</sect2>
321
322
<!-- Schemas -->
323
<sect2 id="concepts-schemas">
324
<title>Schemas</title>
325
326
<para>
327
A <firstterm>schema</firstterm> describes some configuration
328
key. Its primary purpose is to provide documentation about
329
the key to system administrators manipulating the GConf
330
database. Secondarily, schemas contain a good default value
331
for the key; GConf will automatically return this value when
332
a key is unset. Schemas also include the name of the
333
application that created a key (useful when trying to clean
334
old junk out of the database, for example).
335
</para>
336
337
<para>
338
Schemas are normally installed from special schema
339
description files; the <application>gconftool</application>
340
program knows how to read these and install the schemas into
341
the GConf database. Normally, schemas are not installed by
342
application code, though the interface for doing so is a
343
public part of the GConf API.
344
</para>
345
346
</sect2>
347
348
</sect1>
349
350
</chapter>
351
352
<!-- Client Library -->
353
<chapter>
354
<title>C Language Client Library</title>
355
356
<para>
357
The GConf client library is used by applications
358
to store or retrieve configuration data. This library presents
359
the lowest-level (but still fairly convenient) mode of access
360
to the GConf database; the GConf database does not speak a
361
public protocol and can not be accessed directly.
362
</para>
363
364
<para>
365
Convenience wrappers for the GConf client library are possible.
366
Right now a nice wrapper based on the GTK+ object system exists;
367
see <xref linkend="gtk-wrapper">.
368
</para>
369
370
<para>
371
Note that this is only a brief tutorial-style introduction to
372
the client library; have a look at <xref
373
linkend="gconf-reference"> for a complete reference.
374
</para>
375
376
<!-- Error Handling -->
377
<sect1>
378
<title>Error Handling</title>
379
380
<para>
381
Error handling isn't exciting but it's unfortunately
382
necessary. Because even the initialization of the GConf
383
library can fail, we have to cover error handling first.
384
</para>
385
386
<para>
387
Errors are returned in a <structname>GError</structname> object.
388
<structname>GError</structname> has two public fields:
389
<structfield>str</structfield> is an error message, and
390
<structfield>num</structfield> is an <symbol>errno</symbol>-style
391
enumerated value with type <symbol>GConfError</symbol>, useful for
392
switching on an error and taking different actions depending on the
393
exact error that occurred.
394
</para>
395
396
<para>
397
GConf functions that potentially fail accept a
398
<symbol>GError**</symbol> argument, where they store a
399
<structname>GError</structname> object if the operation
400
fails. If no error occurs, the location pointed to by the
401
<symbol>GError**</symbol> is left unchanged. In all cases,
402
you can pass <symbol>NULL</symbol> as the
403
<symbol>GError**</symbol>, to ignore any errors. Needless
404
to say, normally you should report errors instead of ignoring
405
them.
406
</para>
407
408
<para>
409
If an error is returned, you must free it with
410
<function>g_error_free()</function>:
411
<funcsynopsis>
412
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
413
<funcdef>void
414
<function>g_error_free</function>
415
</funcdef>
416
<paramdef>GError* <parameter>error</parameter></paramdef>
417
</funcsynopsis>
418
</para>
419
420
<para>
421
Thus, a complete error-checking sequence might work like this:
422
<programlisting>
423
GError* err = NULL;
424
425
if (!gconf_init(&err))
426
{
427
fprintf(stderr, _("Failed to init GConf: %s\n"), err->message);
428
g_error_free(err);
429
err = NULL;
430
}
431
</programlisting>
432
Note that <function>gconf_init()</function> returns
433
<symbol>TRUE</symbol> on success and <symbol>FALSE</symbol> on failure,
434
other functions may have different ways of indicating
435
success/failure. Also note that the <symbol>err</symbol> variable is
436
initialized to <symbol>NULL</symbol>; this is
437
<emphasis>required</emphasis>.
438
</para>
439
440
<para>
441
Error checking is slightly inconvenient to use because we have to be
442
thread-safe; GConf originally had a system similar to
443
<symbol>errno</symbol>, but that doesn't work with threads. GConf still
444
isn't thread-safe, but the API isn't inherently unsafe.
445
</para>
446
447
<para>
448
The available values for <symbol>GConfError</symbol> are:
449
<variablelist>
450
<varlistentry><term>GCONF_SUCCESS</term>
451
<listitem>
452
<para>
453
Indicates that there was no error.
454
</para>
455
</listitem>
456
</varlistentry>
457
<varlistentry><term>GCONF_FAILED</term>
458
<listitem>
459
<para>
460
Indicates that the operation fatally failed for
461
some fairly unpredictable and idiosyncratic reason
462
not covered by the more specific error values.
463
The error message will give details.
464
</para>
465
</listitem>
466
</varlistentry>
467
<varlistentry><term>GCONF_NO_SERVER</term>
468
<listitem>
469
<para>
470
The <application>gconfd</application> configuration server
471
could not be contacted, and we couldn't or didn't
472
respawn it for whatever reason. The error message
473
may give more details. This probably means either a
474
bug in <application>gconfd</application> or a hosed local
475
configuration.
476
</para>
477
</listitem>
478
</varlistentry>
479
<varlistentry><term>GCONF_NO_PERMISSION</term>
480
<listitem>
481
<para>
482
User was denied permission to access some resource
483
at some point; perhaps a file in a file-based
484
configuration backend, perhaps some authentication
485
tokens are wrong. The error message will give more details.
486
</para>
487
</listitem>
488
</varlistentry>
489
<varlistentry><term>GCONF_BAD_ADDRESS</term>
490
<listitem>
491
<para>
492
A configuration source address was invalid.
493
</para>
494
</listitem>
495
</varlistentry>
496
<varlistentry><term>GCONF_BAD_KEY</term>
497
<listitem>
498
<para>
499
A configuration key was invalid.
500
</para>
501
</listitem>
502
</varlistentry>
503
<varlistentry><term>GCONF_PARSE_ERROR</term>
504
<listitem>
505
<para>
506
Something had to be parsed, and it couldn't
507
be. Typically, a string representation of a config
508
value found in a config file or obtained from the
509
user. Error message will often have more details.
510
</para>
511
</listitem>
512
</varlistentry>
513
<varlistentry><term>GCONF_CORRUPT</term>
514
<listitem>
515
<para>
516
Typically means that the text files or binary database
517
used by some backend have gotten hosed. Most backends
518
will try to self-repair, within reason. If they can't
519
they will bail with this error.
520
</para>
521
</listitem>
522
</varlistentry>
523
<varlistentry><term>GCONF_TYPE_MISMATCH</term>
524
<listitem>
525
<para>
526
Some routines in the GConf libraries impose type
527
constraints; if these are violated you get this error.
528
For example, <function>gconf_engine_get_int()</function>
529
returns this error if the value found is actually a
530
string.
531
</para>
532
</listitem>
533
</varlistentry>
534
<varlistentry><term>GCONF_IS_DIR</term>
535
<listitem>
536
<para>
537
This error is returned if you try to perform a key
538
operation on a name that turns out to be a directory.
539
Some backends don't check for this error, they just
540
report that the key isn't set...
541
</para>
542
</listitem>
543
</varlistentry>
544
<varlistentry><term>GCONF_IS_KEY</term>
545
<listitem>
546
<para>
547
This error is returned if you try to perform a
548
directory operation on a name that turns out to be
549
a key. Some backends don't check for this error...
550
</para>
551
</listitem>
552
</varlistentry>
553
<varlistentry><term>GCONF_OVERRIDDEN</term>
554
<listitem>
555
<para>
556
This means that you tried to set a value, and a
557
read-only configuration source found before the first
558
user-writable source in the path has already set the
559
value. That is, setting the value would have no
560
effect because the read-only source's setting would
561
override the new value. You should report to the user
562
that their setting will not take effect.
563
</para>
564
</listitem>
565
</varlistentry>
566
</variablelist>
567
</para>
568
569
<para>
570
<function>gconf_error_new()</function> is used inside the
571
library and inside the library backends. It is typically not
572
useful to clients. It simply creates a new error, from a
573
<symbol>GConfError</symbol> and a
574
<function>printf()</function>-style format and variable
575
argument list.
576
<funcsynopsis>
577
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
578
<funcdef>void
579
<function>gconf_error_new</function>
580
</funcdef>
581
<paramdef>GConfError <parameter>en</parameter></paramdef>
582
<paramdef>const gchar*
583
<parameter>format</parameter></paramdef>
584
<paramdef><parameter>...</parameter></paramdef>
585
</funcsynopsis>
586
</para>
587
588
</sect1>
589
590
591
<!-- Initialization -->
592
<sect1>
593
<title>Initialization</title>
594
595
<para>
596
The GConf client library must be initialized before use.
597
Initialization establishes a connection to the ORB (because
598
CORBA is currently used to implement GConf, though clients
599
never have to see this) and sets up some global data
600
structures. The arguments to <function>gconf_init()</function>
601
are an argc/argv pair to check for CORBA-related command line
602
options, and a location to place any error that
603
occurs. <function>gconf_init()</function> returns
604
<symbol>TRUE</symbol> on success.
605
</para>
606
607
<para>
608
You can check whether GConf is initialized with
609
<function>gconf_initialized()</function>.
610
</para>
611
612
</sect1>
613
614
<!-- GConfEngine object -->
615
<sect1>
616
<title>The <structname>GConfEngine</structname> object</title>
617
<para>
618
A <structname>GConfEngine</structname> object represents your
619
connection to a configuration database. Normally the database
620
you're connecting to is the user's default database, defined
621
by all the sources in their configuration source
622
path. <function>gconf_engine_get_default()</function> returns a handle to
623
this default
624
database. <function>gconf_engine_get_default_with_address()</function>
625
returns a handle to a single configuration source; normally,
626
applications will not use this function—it's intended
627
for system configuration tools and the like.
628
</para>
629
630
<note>
631
<para>
632
In a GNOME context, you should use
633
<structname>GConfClient</structname> instead of
634
<structname>GConfEngine</structname>.
635
</para>
636
</note>
637
638
<para>
639
<funcsynopsis>
640
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
641
<funcdef>GConfEngine*
642
<function>gconf_engine_get_default</function>
643
</funcdef>
644
<void>
645
</funcsynopsis>
646
<funcsynopsis>
647
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
648
<funcdef>GConfEngine*
649
<function>gconf_engine_get_default_with_address</function>
650
</funcdef>
651
<paramdef>const gchar* <parameter>address</parameter></paramdef>
652
</funcsynopsis>
653
</para>
654
655
<para>
656
The <structname>GConfEngine</structname> object is reference
657
counted; it begins with a count of 1, and is destroyed when
658
the count reaches 0. In other words, the creator of the
659
<structname>GConfEngine</structname> "owns" a reference to the
660
<structname>GConfEngine</structname> as soon as it's created, and
661
should call <function>gconf_engine_unref()</function> to make it
662
go away. <function>gconf_engine_ref()</function> creates a new
663
reference to the <structname>GConfEngine</structname>.
664
<funcsynopsis>
665
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
666
<funcdef>void
667
<function>gconf_engine_ref</function>
668
</funcdef>
669
<paramdef>GConfEngine* <parameter>conf</parameter></paramdef>
670
</funcsynopsis>
671
672
<funcsynopsis>
673
<funcsynopsisinfo>#include <gconf/gconf.h></funcsynopsisinfo>
674
<funcdef>void
675
<function>gconf_engine_unref</function>
676
</funcdef>
677
<paramdef>GConfEngine* <parameter>conf</parameter></paramdef>
678
</funcsynopsis>
679
</para>
680
681
</sect1>
682
683
<!-- GConfValue -->
684
<sect1>
685
<title>The <structname>GConfValue</structname> Datatype</title>
686
687
<para>
688
The <structname>GConfValue</structname> struct represents
689
a value that can be obtained from or stored in the
690
configuration database. It is simply a type marker
691
and a union of several value types, with constructor,
692
destructor, "setter" and "getter" functions. When possible
693
the GConf library allows you to deal with simple C types
694
instead of a <structname>GConfValue</structname>, but
695
sometimes there is simply no way to know the type of an
696
object in advance. The <filename>libgnome/gnome-config.h</filename>
697
interface simply returns strings in this case, for the
698
programmer to parse manually; this was phenomenally broken and
699
GConf fixes it with <structname>GConfValue</structname>.
700
</para>
701
702
<sect2>
703
<title>Accessing <structname>GConfValue</structname></title>
704
<para>
705
To read a <structname>GConfValue</structname>, you first
706
determine its type and then read the value using one
707
of its accessor macros. The following useless code should
708
demonstrate this:
709
<programlisting>
710
void
711
print_value(GConfValue* value)
712
{
713
switch (value->type)
714
{
715
case GCONF_VALUE_STRING:
716
printf("%s\n", gconf_value_get_string(value));
717
break;
718
case GCONF_VALUE_INT:
719
printf("%d\n", gconf_value_get_int(value));
720
break;
721
case GCONF_VALUE_FLOAT:
722
printf("%g\n", gconf_value_get_float(value));
723
break;
724
case GCONF_VALUE_BOOL:
725
printf("%s", gconf_value_get_bool(value) ? "true" : "false");
726
break;
727
case GCONF_VALUE_SCHEMA:
728
{
729
GConfSchema* schema = gconf_value_get_schema(value);
730
731
/* printing a schema would be complicated, you get the idea */
732
}
733
break;
734
case GCONF_VALUE_LIST:
735
{
736
GSList* iter = gconf_value_get_list(value);
737
738
while (iter != NULL)
739
{
740
GConfValue* element = iter->data;
741
742
print_value(element);
743
744
iter = g_slist_next(iter);
745
}
746
}
747
break;
748
case GCONF_VALUE_PAIR:
749
print_value(gconf_value_get_car(value));
750
print_value(gconf_value_get_cdr(value));
751
break;
752
case GCONF_VALUE_INVALID:
753
/* This is used internally by GConf, you can also
754
use it yourself to indicate errors and such. It
755
won't be returned from GConf functions though. */
756
printf("invalid value");
757
break;
758
759
default:
760
g_assert_not_reached();
761
break;
762
}
763
}
764
</programlisting>
765
</para>
766
767
<para>
768
A special note about values of type <symbol>GCONF_VALUE_LIST</symbol>:
769
the list contains <structname>GConfValue</structname> objects, and all
770
objects in the list must have the same type. You can get the type of
771
the list with the <function>gconf_value_get_list_type()</function> macro.
772
</para>
773
774
</sect2>
775
776
<sect2>
777
<title>Creating/destroying a <structname>GConfValue</structname></title>
778
<para>
779
Often you obtain a <structname>GConfValue</structname> from
780
a GConf routine such as <function>gconf_engine_get ()</function>,
781
but you can also create them yourself with
782
<function>gconf_value_new()</function>.
783
<function>gconf_value_new()</function> takes a single
784
argument, the type of the newly-created value. Value types
785
can't be changed after creating the value.
786
<funcsynopsis>
787
<funcsynopsisinfo>#include <gconf/gconf-value.h></funcsynopsisinfo>
788
<funcdef>GConfValue*
789
<function>gconf_value_new</function>
790
</funcdef>
791
<paramdef>GConfValueType <parameter>type</parameter></paramdef>
792
</funcsynopsis>
793
Note that <filename>gconf/gconf-value.h</filename> is
794
automatically included by <filename>gconf/gconf.h</filename>.
795
</para>
796
797
<warning><title>You must initialize your values</title>
798
<para>
799
Newly-constructed values are invalid; if you use the accessor macros
800
before you set the contents of the value, the results are
801
undefined. Use <function>gconf_value_set_int()</function>,
802
<function>gconf_value_set_string()</function>, and so on to
803
initialize the value.
804
</para>
805
</warning>
806
807
<para>
808
You can destroy a <structname>GConfValue</structname> with
809
<function>gconf_value_free()</function>, and copy one
810
with <function>gconf_value_copy()</function>. The copy is a
811
deep copy, that is, child values contained in lists or
812
pairs are also copied.
813
<funcsynopsis>
814
<funcsynopsisinfo>#include <gconf/gconf-value.h></funcsynopsisinfo>
815
<funcdef>GConfValue*
816
<function>gconf_value_copy</function>
817
</funcdef>
818
<paramdef>GConfValue* <parameter>src</parameter></paramdef>
819
<funcdef>void
820
<function>gconf_value_free</function>
821
</funcdef>
822
<paramdef>GConfValue* <parameter>value</parameter></paramdef>
823
</funcsynopsis>
824
</para>
825
</sect2>
826
827
</sect1>
828
829
<!-- Reading configuration values -->
830
<sect1>
831
<title>Reading/Writing Configuration Values</title>
832
833
<sect2>
834
<title>Reading</title>
835
<para>
836
The "raw" function for obtaining the value stored at a given key in the
837
configuration database is <function>gconf_engine_get ()</function>.
838
<function>gconf_engine_get ()</function> returns a
839
<structname>GConfValue</structname> if the key was set, or
840
<symbol>NULL</symbol> if the key was unset or an error occurred. If an
841
error occurred a <structname>GError</structname> is returned in the
842
location given as the final argument.
843
</para>
844
845
<para>
846
There are also convenience functions that automatically convert
847
<structname>GConfValue</structname> to primitive C types. These include
848
<function>gconf_engine_get_int()</function>,
849
<function>gconf_engine_get_bool()</function>, and so on.
850
</para>
851
852
</sect2>
853
854
<sect2>
855
<title>Writing</title>
856
<para>
857
858
</para>
859
</sect2>
860
861
</sect1>
862
</chapter>
863
864
<!-- GTK Object wrapper -->
865
<chapter id="gtk-wrapper">
866
<title><structname>GtkObject</structname> Convenience Wrapper</title>
867
868
<para>
869
<structname>GConfClient</structname> is a
870
<structname>GtkObject</structname> subclass that replaces
871
<structname>GConfEngine</structname> in GNOME programs.
872
</para>
873
874
<sect1 id="gconfclient-example">
875
<title>A Complete Example</title>
876
877
<para>
878
879
</para>
880
881
882
</sect1>
883
884
</chapter>
885
886
<chapter id="conventions">
887
<title>GConf Conventions</title>
888
889
<para>
890
This chapter describes <emphasis>conventions</emphasis> that
891
GConf clients should obey, though the library does not enforce
892
them.
893
</para>
894
895
<sect1>
896
<title>Namespace division</title>
897
898
<para>
899
When choosing GConf keys, you should follow these conventions.
900
</para>
901
902
<para>
903
<itemizedlist mark="bullet">
904
905
<listitem>
906
<para>
907
Schemas should go under the <literal>/schemas</literal>
908
toplevel directory. Under <literal>/schemas</literal>,
909
the normal GConf namespace should be mirrored. So, if you have a
910
key <literal>/foo/bar/baz</literal>, the schema for that key should
911
be at <literal>/schemas/foo/bar/baz</literal>. If you apply the same
912
schema to multiple keys, then obviously the schema name will have
913
to differ from the key names; but you should mirror as much of the
914
key names as possible. For example, <literal>/foo/bar/baz</literal>
915
and <literal>/foo/bar/boo</literal> might have the schema
916
<literal>/schemas/foo/bar/baz_and_boo</literal>.
917
</para>
918
</listitem>
919
920
921
<listitem>
922
<para>
923
The GNOME libraries may store preferences for GNOME apps
924
under the
925
<literal>/apps/gnome-settings/<replaceable>appname</replaceable></literal>
926
directory.
927
<literal><replaceable>appname</replaceable></literal> will be
928
replaced with the name of your app, as passed in to
929
<function>gnome_init()</function> (perhaps canonicalized to be a
930
legal GConf key). You should not put your own
931
settings in this directory, because you may get notifications when
932
gnome-libs keys change and gnome-libs may get notifications when
933
your keys change. This would be confusing.
934
</para>
935
</listitem>
936
937
<listitem>
938
<para>
939
Preferences for applications should go under an
940
<literal>/apps/<replaceable>appname</replaceable></literal>
941
directory. Try to make
942
<literal><replaceable>appname</replaceable></literal> match the
943
one passed to <function>gnome_init()</function>, also used in the
944
<literal>/apps/gnome-settings/<replaceable>appname</replaceable></literal>
945
directory. Vendors are encouraged to include their vendor name in
946
<replaceable>appname</replaceable>, to avoid namespace clashes.
947
</para>
948
</listitem>
949
950
<listitem>
951
<para>
952
Preferences for the desktop environment should go under
953
<literal>/desktop</literal>. None should be immediately
954
under <literal>/desktop</literal>, however. GNOME-specific
955
preferences should be under <literal>/desktop/gnome</literal>.
956
Settings standardized among multiple desktops should go under
957
<literal>/desktop/standard</literal>. Other specific desktops should
958
select a directory to use (<literal>/desktop/kde</literal>,
959
<literal>/desktop/xfce</literal>, etc.)
960
</para>
961
</listitem>
962
963
<listitem>
964
<para>
965
System-level preferences (such as the host name, though
966
I'm sure that specific example will never be in GConf) should go
967
under <literal>/system</literal>. None should be
968
immediately under <literal>/system</literal>, however; select a
969
descriptive subdirectory.
970
</para>
971
</listitem>
972
973
<listitem>
974
<para>
975
In general, keys under <literal>/system</literal> and
976
<literal>/desktop</literal> are for use by multiple applications,
977
and keys under
978
<literal>/apps/<replaceable>appname</replaceable></literal> are
979
for use by a single application.
980
</para>
981
</listitem>
982
983
<listitem>
984
<para>
985
If you have a "weird" key that doesn't fit into any of the above
986
categories, please mail me (<email>hp@redhat.com</email>) and ask
987
for a new directory to be invented. Alternatively, place your key
988
under the <literal>/extra</literal> toplevel directory.
989
</para>
990
</listitem>
991
992
</itemizedlist>
993
</para>
994
995
</sect1>
996
997
</chapter>
998
999
<!-- gconftool -->
1000
<chapter id="gconftool">
1001
<title><application>gconftool</application> Utility Program</title>
1002
1003
<para>
1004
<application>gconftool</application> is used to control GConf
1005
from the command line.
1006
</para>
1007
1008
</chapter>
1009
1010
<!-- Schema Files -->
1011
<chapter>
1012
<title>Schema Files</title>
1013
1014
<para>
1015
This chapter covers the mechanics of writing and installing the
1016
GConf schema files. Schema files describe your configuration
1017
data and provide default values for it. See <xref
1018
linkend="concepts-schemas"> for an explanation of schemas. The
1019
schema file is not understood by the GConf client library;
1020
rather, <application>gconftool</application> (see <xref
1021
linkend="gconftool">) knows how to parse it, and then uses the GConf
1022
client library to install the information in the GConf database.
1023
</para>
1024
1025
<sect1>
1026
<title>Schema File Format</title>
1027
<para>
1028
Here is a sample schema file for a hypothetical application,
1029
<application>basic-gconf-app</application>, one of the
1030
examples that comes with the GConf distribution.
1031
<example>
1032
<title>Sample schema file</title>
1033
<programlisting>
1034
<gconfschemafile>
1035
<schemalist>
1036
<schema>
1037
<key>/schemas/apps/basic-gconf-app/fooandbar</key>
1038
<applyto>/apps/basic-gconf-app/foo</applyto>
1039
<applyto>/apps/basic-gconf-app/bar</applyto>
1040
<owner>basic-gconf-app</owner>
1041
<type>string</type>
1042
<locale name="C">
1043
<default>Blah blah blurgh</default>
1044
<short>short description in C locale</short>
1045
<long>long description of foo and bar in C locale</long>
1046
</locale>
1047
<locale name="no">
1048
<default>some thing in norwegian</default>
1049
<short>short description in Norway</short>
1050
<long>Long description in Norway. long long long. this is a long sentence.</long>
1051
</locale>
1052
</schema>
1053
<schema>
1054
<key>/schemas/apps/basic-gconf-app/baz</key>
1055
<applyto>/apps/basic-gconf-app/baz</applyto>
1056
<owner>basic-gconf-app</owner>
1057
<type>string</type>
1058
<locale name="C">
1059
<default>Zzzzzzzzzz</default>
1060
<short>short description in C locale</short>
1061
<long>long description of baz in C locale</long>
1062
</locale>
1063
<locale name="no">
1064
<default>some thing in norwegian</default>
1065
<short>short description in Norway</short>
1066
<long>Long description in Norway. long long long. this is a long sentence.</long>
1067
</locale>
1068
</schema>
1069
<schema>
1070
<key>/schemas/apps/basic-gconf-app/blah</key>
1071
<applyto>/apps/basic-gconf-app/blah</applyto>
1072
<owner>basic-gconf-app</owner>
1073
<type>string</type>
1074
<locale name="C">
1075
<default>bllllllaaaaaaaaaaaaaaaaarrrrrrggggggghhhhh</default>
1076
<short>short description in C locale</short>
1077
<long>long description of blah in C locale</long>
1078
</locale>
1079
<locale name="no">
1080
<default>some thing in norwegian</default>
1081
<short>short description in Norway</short>
1082
<long>Long description in Norway. long long long. this is a long sentence.</long>
1083
</locale>
1084
</schema>
1085
</schemalist>
1086
</gconfschemafile>
1087
</programlisting>
1088
</example>
1089
</para>
1090
1091
<para>
1092
The file format is straightforward. The root node must be
1093
called <literal><gconfschemafile></literal>. This
1094
element contains one or more <literal><schemalist></literal>
1095
elements; I can't think of a reason to use multiple
1096
<literal><schemalist></literal> elements, but you can if
1097
you want, and <application>gconftool</application> will load
1098
each one. The <literal><schemalist></literal> in turn
1099
contains one or more <literal><schema></literal>
1100
elements. Each of these describes a single schema.
1101
</para>
1102
1103
<warning>
1104
<para>
1105
<application>gconftool</application> is not very tolerant
1106
about whitespace right now; in particular it won't strip
1107
whitespace from around key names, type names, etc. This is
1108
broken and will be fixed, just watch out for now.
1109
</para>
1110
</warning>
1111
1112
<para>
1113
Here are the fields of the <literal><schema></literal>
1114
element:
1115
1116
<informaltable pgwide=1 frame="none">
1117
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
1118
<tbody>
1119
1120
<row>
1121
<entry><key></entry>
1122
<entry>The key <emphasis>where the schema will be stored</emphasis>;
1123
see <xref linkend="conventions"> for naming
1124
conventions. There may be only one key per schema.
1125
</entry>
1126
1127
</row>
1128
1129
<row>
1130
<entry><applyto></entry>
1131
1132
<entry>A key <emphasis>the schema will be applied to</emphasis>; that
1133
is, this schema <emphasis>describes</emphasis> this
1134
key. See <xref linkend="conventions"> for naming
1135
conventions. There may be multiple <applyto>
1136
elements.</entry>
1137
1138
</row>
1139
1140
<row>
1141
<entry><owner></entry>
1142
1143
<entry>Name of the application that uses this schema; may be the
1144
command line name, or a human-readable name. However
1145
you should use the same value for <owner> for
1146
all schemas your app installs. The primary purpose
1147
of this field is to enable sysadmins to locate the
1148
keys belonging to a given application.
1149
</entry>
1150
1151
</row>
1152
1153
<row>
1154
<entry><type></entry>
1155
1156
<entry>The type of values described by this schema. i.e. keys
1157
the schema is applied to should store values of this type.
1158
Allowed values are: <literal>string</literal>, <literal>int</literal>,
1159
<literal>bool</literal>, <literal>float</literal>,
1160
<literal>list</literal>, <literal>pair</literal>
1161
</entry>
1162
1163
</row>
1164
1165
<row>
1166
<entry><default></entry>
1167
1168
<entry>The <literal><default></literal> element may
1169
appear below <literal><schema></literal> (a default for all
1170
locales, often suitable for numeric values),
1171
<emphasis>OR</emphasis> below a <literal><locale></literal>
1172
element, if the default should be localized. It simply contains the
1173
default value for the keys the schema is applied to.
1174
1175
</entry>
1176
1177
</row>
1178
1179
1180
<row>
1181
<entry><locale></entry>
1182
1183
<entry>
1184
The <literal><locale></literal> element
1185
contains locale-specific data, including the
1186
human-readable short and long descriptions,
1187
and optionally the default value
1188
(<literal><default></literal> may also be
1189
placed directly underneath the
1190
<literal><schema></literal> element).
1191
There should be one
1192
<literal><locale></literal> element for each
1193
locale, with a <literal>name</literal> attribute
1194
specifying the locale name.
1195
</entry>
1196
1197
</row>
1198
1199
1200
</tbody></tgroup></informaltable>
1201
1202
A <literal><locale></literal> element can contain
1203
a locale-specific <literal><default></literal>, and may also
1204
contain short and long descriptions as follows:
1205
<informaltable pgwide=1 frame="none">
1206
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
1207
<tbody>
1208
1209
<row>
1210
<entry><short></entry>
1211
<entry>A short description of the purpose of this key, around
1212
40 characters long (about half a line).
1213
</entry>
1214
1215
</row>
1216
1217
<row>
1218
<entry><long></entry>
1219
<entry>A long description of the configuration key, around a paragraph
1220
or two. Should describe the possible values of the
1221
key and their effect on the application.
1222
</entry>
1223
1224
</row>
1225
1226
</tbody></tgroup></informaltable>
1227
1228
</para>
1229
1230
</sect1>
1231
1232
<sect1>
1233
<title>Installing Schemas</title>
1234
1235
<para>
1236
There are several things that need to happen at "<literal>make
1237
install</literal>" time.
1238
<itemizedlist mark="bullet">
1239
<listitem>
1240
<para>
1241
The schemas should be installed into a GConf
1242
configuration source; either the default source, or a
1243
source specified by the user with a
1244
<filename>configure</filename> option called
1245
<literal>--enable-gconf-source</literal>.
1246
</para>
1247
</listitem>
1248
<listitem>
1249
<para>
1250
The schema files should be installed to
1251
<filename>$(sysconfdir)/gconf/schemas/</filename>,
1252
making it easy for sysadmins to browse them or
1253
bulk-reinstall them into a new configuration source.
1254
</para>
1255
</listitem>
1256
</itemizedlist>
1257
</para>
1258
1259
<para>
1260
The <symbol>AM_GCONF_SOURCE</symbol>
1261
macro will get the default location to install
1262
the schema. It will also add a
1263
<literal>--enable-gconf-source</literal>
1264
option and it will look in
1265
<filename>$(sysconfdir)/gconf/schema-install-source</filename>
1266
for a path.
1267
The <symbol>GCONF_SCHEMA_CONFIG_SOURCE</symbol> variable
1268
will be defined.
1269
</para>
1270
<para>
1271
To get schemas installed properly add the macro to
1272
<filename>configure.in</filename>
1273
<programlisting>
1274
AM_GCONF_SOURCE
1275
</programlisting>
1276
</para>
1277
<para>
1278
And put something like this in <filename>Makefile.am</filename>
1279
<programlisting>
1280
install-schemas:
1281
GCONF_CONFIG_SOURCE=$(GCONF_SCHEMA_CONFIG_SOURCE) \
1282
gconftool --makefile-install-rule my.schemas
1283
</programlisting>
1284
</para>
1285
</sect1>
1286
1287
<sect1>
1288
<title>Schema File DTD</title>
1289
1290
<para>
1291
The following DTD was contributed by Mirko Streckenbach.
1292
</para>
1293
1294
<para>
1295
<programlisting>
1296
<!ELEMENT gconfschemafile (schemalist)>
1297
1298
<!ELEMENT schemalist (schema)*>
1299
1300
<!ELEMENT schema (key,applyto*,owner?,type,locale*)>
1301
1302
<!ELEMENT key (#PCDATA)>
1303
1304
<!ELEMENT applyto (#PCDATA)>
1305
1306
<!ELEMENT owner (#PCDATA)>
1307
1308
<!ELEMENT type (#PCDATA)>
1309
1310
<!ELEMENT locale (default?,short?,long?)>
1311
<!ATTLIST locale name CDATA #REQUIRED>
1312
1313
<!ELEMENT short (#PCDATA)>
1314
<!ELEMENT long (#PCDATA)>
1315
<!ELEMENT default (#PCDATA)>
1316
</programlisting>
1317
</para>
1318
</sect1>
1319
1320
</chapter>
1321
1322
<!-- Checklist/Summary -->
1323
<chapter>
1324
<title>Checklist/Summary</title>
1325
1326
<para>
1327
This chapter summarizes the things to consider and actions to
1328
take when adding GConf support to an application.
1329
</para>
1330
1331
<para>
1332
1333
</para>
1334
1335
</chapter>
1336
1337
<!-- GConf reference -->
1338
<chapter id="gconf-reference">
1339
<title>GConf Reference Documentation</title>
1340
1341
&gconf-gconf-engine;
1342
&gconf-gconf;
1343
&gconf-gconf-error;
1344
&gconf-gconf-value;
1345
&gconf-gconf-schema;
1346
&gconf-gconf-changeset;
1347
1348
</chapter>
1349
1350
<!-- GConfClient reference -->
1351
<chapter id="gconf-client-reference">
1352
<title><structname>GtkObject</structname> Wrapper Reference (<structname>GConfClient</structname>)</title>
1353
1354
&GConfClient;
1355
1356
</chapter>
1357
1358
<!-- GConf Internals Reference -->
1359
<chapter id="gconf-internals-reference">
1360
<title>GConf Internal Reference</title>
1361
1362
&gconf-gconf-backend;
1363
&gconf-gconf-internals;
1364
&gconf-gconf-listeners;
1365
&gconf-gconf-locale;
1366
&gconf-gconf-sources;
1367
1368
</chapter>
1369
1370
</book>
1371
<!-- Keep this comment at the end of the file
1372
Local variables:
1373
sgml-omittag:t
1374
sgml-shorttag:t
1375
sgml-minimize-attributes:nil
1376
sgml-always-quote-attributes:t
1377
sgml-indent-step:2
1378
sgml-indent-data:t
1379
sgml-exposed-tags:nil
1380
sgml-local-catalogs:nil
1381
sgml-local-ecat-files:nil
1382
sgml-auto-insert-required-elements:t
1383
sgml-balanced-tag-edit:t
1384
sgml-normalize-trims:t
1385
sgml-set-face:t
1386
sgml-parent-document:nil
1387
End:
1388
-->
1389
Loggerhead is a web-based interface for Breezy
Version: 2.0.1