gconf.sgml 47.9 KB
Newer Older
Mark McLoughlin's avatar
Mark McLoughlin committed
1
2
3
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
5
6
7
8
9
10
11
12
13
14
15
<!ENTITY GConfClient SYSTEM "xml/gconf-client.xml">
<!ENTITY gconf-gconf-backend SYSTEM "xml/gconf-backend.xml">
<!ENTITY gconf-gconf-engine SYSTEM "xml/gconf-engine.xml">
<!ENTITY gconf-gconf-error SYSTEM "xml/gconf-error.xml">
<!ENTITY gconf-gconf-internals SYSTEM "xml/gconf-internals.xml">
<!ENTITY gconf-gconf-listeners SYSTEM "xml/gconf-listeners.xml">
<!ENTITY gconf-gconf-schema SYSTEM "xml/gconf-schema.xml">
<!ENTITY gconf-gconf-sources SYSTEM "xml/gconf-sources.xml">
<!ENTITY gconf-gconf-value SYSTEM "xml/gconf-value.xml">
<!ENTITY gconf-gconf SYSTEM "xml/gconf.xml">
<!ENTITY gconf-gconf-locale SYSTEM "xml/gconf-locale.xml">
<!ENTITY gconf-gconf-changeset SYSTEM "xml/gconf-changeset.xml">
16
]>
17
18
<book id="index">
  <bookinfo>
19
20
21
22
    <authorgroup>
      <author>
	<firstname>Havoc</firstname>
	<surname>Pennington</surname>
23
24
25
26
27
28
29
30
	<affiliation>
	  <orgname>Red Hat Advanced Development Labs</orgname>
	</affiliation>
	<authorblurb>
	  <para>
	    <email>hp@redhat.com</email>
	  </para>
	</authorblurb>
31
32
33
34
35
36
37
38
      </author>
    </authorgroup>
    <copyright>
      <year>1999</year>
      <holder>Havoc Pennington</holder>
    </copyright>

    <!-- GConf -->
39
    <title>GConf Manual</title>
40
41
    <abstract>
      <para>
42
43
44
45
46
47
        GConf is a system for storing configuration information, that is,
        key-value pairs. GConf provides a notification service so applications
        can be notified when a key's value is changed.  GConf also allows for
        pluggable storage mechanisms (text files, databases, etc.); allows
        administrators to install default values; and allows application authors
        to document their configuration keys for the benefit of administrators.
48
49
50
      </para>
      
    </abstract>
51
52
53
54
55
56
57
58
59
60
61
62


    <legalnotice>
      <para>
	This document may be distributed subject to the terms and
        conditions set forth in the Open Publication License, v1.0 or
        later (the latest version is presently available at <ulink
        url=" http://www.opencontent.org/openpub/"
        type="http">http://www.opencontent.org/openpub/</ulink> )
      </para>
    </legalnotice>

63
  </bookinfo>
64
65
  
  <!-- Introduction to GConf -->
66
  <chapter>
67
    <title>Introduction to GConf</title>
Havoc Pennington's avatar
Havoc Pennington committed
68
69
70
71
72

    <para>
      This chapter introduces GConf, including the basic terms and
      concepts. After reading it, if you're a GNOME programmer looking
      to dive in quickly, you might skip to <xref
73
      linkend="gconfclient-example"/>. If you want to have
Havoc Pennington's avatar
Havoc Pennington committed
74
75
76
      comprehensive knowledge of GConf, you might want to read the
      whole manual.
    </para>
77
78
    
    <!-- Motivation -->
79
    <sect1>
80
81
82
83
84
85
86
87
88
      <title>Motivation</title>
      
      <para>   
        GConf is intended to store key-value pairs, where keys are
        located in an infinite tree-structured namespace (similar to the
        UNIX filesystem). It offers several useful features:
        <itemizedlist mark="bullet">
          <listitem>
            <para>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
89
90
91
92
93
94
              Users can select a variety of data storage backends, such as XML
              text files, ACAP, or databases (LDAP, DB, etc.). This makes it
              easy to adapt GConf to local needs. It also avoids the age-old
              "text files vs. binary registry" debate. (Note: the current GConf
              only has an XML backend implemented, other backends are easy to
              write though.)
95
96
97
98
99
100
101
102
            </para>
          </listitem>
          <listitem>
            <para>
              GConf offers a notification service, so applications can 
              ask to be notified when the value of a key changes. 
              This allows settings to be applied to groups of
              applications, without restarting them and without 
Havoc Pennington's avatar
Havoc Pennington committed
103
104
              ugly hacks. It also allows a clean model-view
              architecture for applications.              
105
106
107
            </para>
          </listitem>
          <listitem>
Havoc Pennington's avatar
Havoc Pennington committed
108
109
110
111
112
113
114
            <para>
              Each user has a "GConf search path" which is a list of 
              configuration sources to scan for each value. 
              For example, the configuration engine might look for 
              values first in the local machine's database and 
              then in a network-wide database.
            </para>
115
116
          </listitem>
          <listitem>
Havoc Pennington's avatar
Havoc Pennington committed
117
118
119
120
            <para>
              GConf is implemented as a per-user daemon, which makes 
              locking a non-issue and allows aggressive caching.
            </para>
121
          </listitem>
Havoc Pennington's avatar
Havoc Pennington committed
122
123
124
125
126
127
128
129
130
          <listitem>
            <para>
              The client API is simple and very abstract, which allows us to
              change its implementation at a later time without a big headache.
              Because a good implementation is a complex problem, this is
              important.
            </para>
          </listitem>

131
132
        </itemizedlist>
      </para>
Havoc Pennington's avatar
Havoc Pennington committed
133

134
      <para>
135
136
137
        GConf was inspired by Wichert Akkerman's configuration
        system specification, originally developed for the Debian
        project. Other sources of ideas include the Windows registry,
Havoc Pennington's avatar
Havoc Pennington committed
138
        the ACAP specification, and Emacs customize mode (try typing
139
140
141
        <literal>M-x customize-browse</literal> in Emacs). Windows XP's
        registry has some features such as documentation that GConf has
        as well - maybe they copied GConf - hey, it's possible. ;-)
142
143
      </para>

144
    </sect1>
Havoc Pennington's avatar
Havoc Pennington committed
145
146

    <!-- Terms and Concepts -->
147
    <sect1>
Havoc Pennington's avatar
Havoc Pennington committed
148
149
150
      <title>Terms and Concepts</title>

      <para>
151
        This section introduces the basic GConf structure and terminology.
Havoc Pennington's avatar
Havoc Pennington committed
152
153
      </para>

154
      <sect2>
155
156
157
158
159
160
161
162
163
        <title>Namespace</title>          
        <para>
          The GConf namespace is almost exactly like the UNIX filesystem; that
          is, a tree structured directory hierarchy. Each name is either a
          "file" (a configuration key storing a value) or a "directory" (a list
          of child configuration key names). A name is specified with a
          slash-separated path. A full path is referred to as a
          <firstterm>key</firstterm>.  Characters in a path should be
          alphanumeric or underscore. Path components may not start with a
164
          period. You should follow the conventions outlined in 
165
         <xref linkend="conventions"/> when choosing what names to use
166
          for your keys.
167
        </para>
168
      </sect2>
169

Havoc Pennington's avatar
Havoc Pennington committed
170
      <!-- Data Types -->
171
      <sect2>
Havoc Pennington's avatar
Havoc Pennington committed
172
173
        <title>GConf Data Types</title>

174
175
176
177
        <para>
          GConf can only store a small, fixed set of data types. This keeps the
          database implementation simple and efficient. GConf should
          <emphasis>not</emphasis> be used to store data files or any other
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
178
179
180
181
182
183
          large amount of information; <emphasis>it is designed for simple
          configuration data only</emphasis>. There are any number of better
          solutions available for storing documents and other large data
          chunks. You might want to store a filename, URL, or Bonobo moniker in
          GConf pointing to a larger piece of data, if you need the GConf
          notification facilities.
184
185
186
187
188
        </para>

        <para>
          Here are the GConf datatypes:
          <variablelist>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
189

190
191
192
193
194
195
196
            <varlistentry>
              <term>Integer</term>
              <listitem><para>
                  Integer values are simple C-style integers, that is, they are 
                  limited to 32 bits and can be positive or negative.
                </para></listitem>
            </varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
197

198
            <varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
199
200
201
202
              <term>String</term> <listitem><para> String values can contain any
              text you like, but not binary data (such as the NULL character).
              GConf should handle any string the C library string functions can
              handle.  </para></listitem>
203
            </varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
204

205
            <varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
206
207
208
209
              <term>Float</term> <listitem><para> Float values are floating
                  point numbers.  Given differences between machine architectures
                  and C libraries, there is no guaranteed degree of precision, other
                  than "a reasonable degree."
210
211
                </para></listitem>
            </varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
212

213
214
215
216
217
218
            <varlistentry>
              <term>Bool</term> 
              <listitem><para>
                  Boolean values are true or false.
                </para></listitem>
            </varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
219

220
221
222
223
224
225
226
227
            <varlistentry>
              <term>Schema</term>
              <listitem><para>
                  Schemas store a <structname>GConfSchema</structname> 
                  data type, which contains meta-information about a key, such 
                  as documentation and its type. 
                </para></listitem>
            </varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
228

229
            <varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
230
231
232
233
234
              <term>List</term> 
              <listitem><para> List values store a group of
                  values. All values in a list must have the same primitive
                  type. Heterogeneous lists are not allowed. Lists of lists and
                  lists of pairs are not allowed.
235
236
                </para></listitem>
            </varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
237

238
239
            <varlistentry>
              <term>Pair</term> 
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
240
241
242
              <listitem><para> Pairs store two primitive
                  values. The two values do not necessarily have the same
                  type. Pairs can not contain pairs or lists, only primitive types.
243
244
                </para></listitem>
            </varlistentry>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
245

246
247
          </variablelist>
        </para>
Havoc Pennington's avatar
Havoc Pennington committed
248

249
      </sect2>
250
251
      
      <!-- Sources -->
252
      <sect2>
253
254
        <title>Configuration Sources</title>

255
256
257
        <para> Users can specify <firstterm>configuration sources</firstterm>
          which will be used by the <application>gconfd</application> per-user
          configuration server.  <application>gconfd</application> loads the
258
259
          file <filename>/etc/gconf/2/path</filename> (or
          <filename>${sysconfdir}/gconf/${version}/path</filename>) on startup; this file
260
261
262
263
264
265
266
267
268
          contains a list of <firstterm>configuration source
          addresses</firstterm>.  A source address is similar to a URL; it
          contains a "protocol" name (in this case, the name of the backend to
          use), followed by a colon, standard flags separated by commands,
          another colon, and then backend-specific information. For example, the
          address <filename> xml:readonly:/home/hp/.gconf.xml</filename> refers
          to an XML backend file tree rooted at
          <filename>/home/hp/.gconf.xml</filename> that should be "mounted
          readonly" so that no data is written to it.
269
270
271
        </para>

        <para>
272
          <filename>/etc/gconf/2/path</filename> stores a list of
273
274
275
276
277
          addresses, which form a <firstterm>configuration source
          path</firstterm>. When looking up a value, GConf will begin
          with the first source in the path, and continue checking
          each source until the value is found or there are no more
          sources.  When setting a value, GConf will use the first
278
279
280
281
282
283
284
285
          <emphasis>writable</emphasis> source.  Administrators can
          impose <emphasis>mandatory</emphasis> settings on their users
          by placing only read-only configuration sources in the path, 
          or by placing a read-only source at the front of the path 
          and setting specific values in that source.
          Administrators can provide <emphasis>default</emphasis> values
          by placing a systemwide source at the end of the configuration
          source path.
286
287
288
        </para>
        
        <para>
289
290
291
          The source configuration file can contain "include" statements and
          some magic variables; you can use this to include a .gconf.path file
          from the user's home directory. Variables are placed in
292
          <symbol>$()</symbol>.  Four variables are built-in to GConf:
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
293
          <symbol>$(HOME)</symbol> is the user's home directory, and
294
295
          <symbol>$(USERCONFIGDIR)</symbol> is the user's configuration directory, and
          <symbol>$(DEFAULTUSERSOURCE)</symbol> is the default user source location, and
296
297
298
299
          <symbol>$(USER)</symbol> is the username. You can also access any
          environment variable by prepending <symbol>ENV_</symbol> to the
          variable name. For example, <symbol>$(ENV_FOO)</symbol> will be
          replaced by the <symbol>FOO</symbol> environment variable.
300
301
302
        </para>

        <para>
303
304
305
          So once everything is working a
          <filename>/etc/gconf/path</filename> file might look like
          this:
306
307
          <programlisting>
            # GConf configuration path file with an include statement
308
            xml:readonly:/etc/gconf.xml.mandatory
309
            include "$(USERCONFIGDIR)/gconf.path"
310
            xml:readonly:/etc/gconf.xml.defaults
311
            # imaginary, no LDAP backend exists right now
312
            ldap::/foo/bar/whatever/ldap/address
313
314
315
          </programlisting>
        </para>

316
317
318
319
320
321
322
        <para>
          Note that particular backend modules may have their own special
          configuration. For example, you may need to configure the details of
          an LDAP backend.
        </para>

      </sect2>
Havoc Pennington's avatar
Havoc Pennington committed
323

324
      <!-- Schemas -->
Havoc Pennington's avatar
Havoc Pennington committed
325
      <sect2 id="concepts-schemas">
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
        <title>Schemas</title>

        <para>
          A <firstterm>schema</firstterm> describes some configuration
          key. Its primary purpose is to provide documentation about
          the key to system administrators manipulating the GConf
          database. Secondarily, schemas contain a good default value
          for the key; GConf will automatically return this value when
          a key is unset. Schemas also include the name of the
          application that created a key (useful when trying to clean
          old junk out of the database, for example).
        </para>

        <para>
          Schemas are normally installed from special schema
          description files; the <application>gconftool</application>
          program knows how to read these and install the schemas into
          the GConf database. Normally, schemas are not installed by
          application code, though the interface for doing so is a
          public part of the GConf API.
        </para>

      </sect2>

350
    </sect1>
Havoc Pennington's avatar
Havoc Pennington committed
351

352
  </chapter>
Havoc Pennington's avatar
Havoc Pennington committed
353
354

  <!-- Client Library -->
355
  <chapter>
Havoc Pennington's avatar
Havoc Pennington committed
356
357
358
359
360
361
362
363
364
365
    <title>C Language Client Library</title>
    
    <para>
      The GConf client library is used by applications
      to store or retrieve configuration data. This library presents 
      the lowest-level (but still fairly convenient) mode of access
      to the GConf database; the GConf database does not speak a
      public protocol and can not be accessed directly. 
    </para>

366
    <para>
367
368
      Note that this is only a brief tutorial-style introduction to
      the client library; have a look at <xref
369
      linkend="gconf-reference"/> for a complete reference.
370
371
    </para>

Havoc Pennington's avatar
Havoc Pennington committed
372
    <!-- Error Handling -->
373
    <sect1>
Havoc Pennington's avatar
Havoc Pennington committed
374
      <title>Error Handling</title>
375
      
Havoc Pennington's avatar
Havoc Pennington committed
376
377
      <para>
        Error handling isn't exciting but it's unfortunately
378
379
380
        necessary. GConf uses the standard <symbol>GError</symbol>
        feature from GLib; if you have never read the documentation 
        on <symbol>GError</symbol>, you should do so right away.
Havoc Pennington's avatar
Havoc Pennington committed
381
382
383
      </para>

      <para>
384
385
386
        When using GConfClient routines, it's OK to pass NULL for the
        error argument most of the time; it has a default error handler
        that will be run.
Havoc Pennington's avatar
Havoc Pennington committed
387
388
389
      </para>

      <para>
390
        The available error codes are:
Havoc Pennington's avatar
Havoc Pennington committed
391
        <variablelist>
392
          <varlistentry><term>GCONF_SUCCESS</term>
Havoc Pennington's avatar
Havoc Pennington committed
393
394
395
396
397
398
            <listitem>
              <para>
                Indicates that there was no error.
              </para>
            </listitem>
          </varlistentry>
399
          <varlistentry><term>GCONF_FAILED</term>
Havoc Pennington's avatar
Havoc Pennington committed
400
401
402
403
404
405
406
407
408
            <listitem>
              <para>
                Indicates that the operation fatally failed for 
                some fairly unpredictable and idiosyncratic reason
                not covered by the more specific error values.
                The error message will give details.
              </para>
            </listitem>
          </varlistentry>
409
          <varlistentry><term>GCONF_NO_SERVER</term>
Havoc Pennington's avatar
Havoc Pennington committed
410
411
            <listitem>
              <para>
412
                The <application>gconfd</application> configuration server
Havoc Pennington's avatar
Havoc Pennington committed
413
414
415
                could not be contacted, and we couldn't or didn't
                respawn it for whatever reason. The error message 
                may give more details. This probably means either a
416
                bug in <application>gconfd</application> or a hosed local
Havoc Pennington's avatar
Havoc Pennington committed
417
418
419
420
                configuration.
              </para>
            </listitem>
          </varlistentry>
421
          <varlistentry><term>GCONF_NO_PERMISSION</term>
Havoc Pennington's avatar
Havoc Pennington committed
422
423
424
425
426
427
428
429
430
            <listitem>
              <para>
                User was denied permission to access some resource
                at some point; perhaps a file in a file-based
                configuration backend, perhaps some authentication 
                tokens are wrong. The error message will give more details.
              </para>
            </listitem>
          </varlistentry>
431
          <varlistentry><term>GCONF_BAD_ADDRESS</term>
Havoc Pennington's avatar
Havoc Pennington committed
432
433
434
435
436
437
            <listitem>
              <para>
                A configuration source address was invalid.
              </para>
            </listitem>
          </varlistentry>
438
          <varlistentry><term>GCONF_BAD_KEY</term>
Havoc Pennington's avatar
Havoc Pennington committed
439
440
441
442
443
444
            <listitem>
              <para>
                A configuration key was invalid.
              </para>
            </listitem>
          </varlistentry>
445
          <varlistentry><term>GCONF_PARSE_ERROR</term>
Havoc Pennington's avatar
Havoc Pennington committed
446
447
448
449
450
451
452
453
454
            <listitem>
              <para>
                Something had to be parsed, and it couldn't
                be. Typically, a string representation of a config 
                value found in a config file or obtained from the 
                user. Error message will often have more details.
              </para>
            </listitem>
          </varlistentry>
455
          <varlistentry><term>GCONF_CORRUPT</term>
Havoc Pennington's avatar
Havoc Pennington committed
456
457
458
459
460
461
462
463
464
            <listitem>
              <para>
                Typically means that the text files or binary database
                used by some backend have gotten hosed. Most backends
                will try to self-repair, within reason. If they can't
                they will bail with this error.
              </para>
            </listitem>
          </varlistentry>
465
          <varlistentry><term>GCONF_TYPE_MISMATCH</term>
Havoc Pennington's avatar
Havoc Pennington committed
466
467
468
469
            <listitem>
              <para>
                Some routines in the GConf libraries impose type
                constraints; if these are violated you get this error.
470
                For example, <function>gconf_engine_get_int()</function>
Havoc Pennington's avatar
Havoc Pennington committed
471
472
473
474
475
                returns this error if the value found is actually a 
                string.
              </para>
            </listitem>
          </varlistentry>
476
          <varlistentry><term>GCONF_IS_DIR</term>
Havoc Pennington's avatar
Havoc Pennington committed
477
478
479
480
481
482
483
484
485
            <listitem>
              <para>
                This error is returned if you try to perform a key 
                operation on a name that turns out to be a directory.
                Some backends don't check for this error, they just 
                report that the key isn't set...
              </para>
            </listitem>
          </varlistentry>
486
          <varlistentry><term>GCONF_IS_KEY</term>
Havoc Pennington's avatar
Havoc Pennington committed
487
488
489
490
491
492
493
494
            <listitem>
              <para>
                This error is returned if you try to perform a
                directory operation on a name that turns out to be 
                a key. Some backends don't check for this error...
              </para>
            </listitem>
          </varlistentry>
495
          <varlistentry><term>GCONF_OVERRIDDEN</term>
496
497
498
499
            <listitem>
              <para>
                This means that you tried to set a value, and a
                read-only configuration source found before the first
Havoc Pennington's avatar
Havoc Pennington committed
500
                user-writable source in the path has already set the
501
502
503
504
505
506
507
                value. That is, setting the value would have no 
                effect because the read-only source's setting would
                override the new value. You should report to the user
                that their setting will not take effect.
              </para>
            </listitem>
          </varlistentry>
Havoc Pennington's avatar
Havoc Pennington committed
508
509
510
        </variablelist>
      </para>

511
    </sect1>
512

Havoc Pennington's avatar
Havoc Pennington committed
513

514
    <!-- GConfEngine object -->
515
    <sect1>
516
      <title>The <structname>GConfEngine</structname> object</title>
Havoc Pennington's avatar
Havoc Pennington committed
517
518

      <para>
519
520
        <structname>GConfClient</structname> should be used instead of 
        <structname>GConfEngine</structname> in most applications.
521
        See <xref linkend="gconf-client"/>. Because libgnome uses
Havoc Pennington's avatar
Havoc Pennington committed
522
523
524
525
526
        <structname>GConfClient</structname>, apps using libgnome 
        <emphasis>MUST</emphasis> use
        <structname>GConfClient</structname>.
        <structname>GConfClient</structname> gets confused if you poke 
        at the <structname>GConfEngine</structname> it "wraps."
527
528
      </para>

529
      <para>
Havoc Pennington's avatar
Havoc Pennington committed
530
        A <structname>GConfEngine</structname> object represents your
531
532
533
        connection to a configuration database. Normally the database
        you're connecting to is the user's default database, defined
        by all the sources in their configuration source
534
535
        path. <function>gconf_engine_get_default()</function> returns
        a handle to this default
536
        database. <function>gconf_engine_get_default_with_address()</function>
537
538
        returns a handle to a single configuration source; normally,
        applications will not use this function&mdash;it's intended
539
        for system configuration tools and the like.
540
      </para>
Havoc Pennington's avatar
Havoc Pennington committed
541
542
543

      <note>
      <para>
544
        Nearly always, you should use
Havoc Pennington's avatar
Havoc Pennington committed
545
546
        <structname>GConfClient</structname> instead of
        <structname>GConfEngine</structname>.
547
548
549
        <structname>GConfClient</structname> has a default handler for
        errors, and keeps a client-side cache of configuration values
        to avoid remote queries.
Havoc Pennington's avatar
Havoc Pennington committed
550
551
552
      </para>
      </note>

553
554
555
      <para>
        <funcsynopsis>
          <funcsynopsisinfo>#include &lt;gconf/gconf.h&gt;</funcsynopsisinfo>
Havoc Pennington's avatar
Havoc Pennington committed
556
          <funcdef>GConfEngine*
557
            <function>gconf_engine_get_default</function>
558
          </funcdef>
559
          <void/>
560
561
562
        </funcsynopsis>        
        <funcsynopsis>
          <funcsynopsisinfo>#include &lt;gconf/gconf.h&gt;</funcsynopsisinfo>
Havoc Pennington's avatar
Havoc Pennington committed
563
          <funcdef>GConfEngine*
564
            <function>gconf_engine_get_default_with_address</function>
565
566
567
568
569
570
          </funcdef>
          <paramdef>const gchar* <parameter>address</parameter></paramdef>
        </funcsynopsis>
      </para>

      <para>
Havoc Pennington's avatar
Havoc Pennington committed
571
        The <structname>GConfEngine</structname> object is reference
572
573
        counted; it begins with a count of 1, and is destroyed when
        the count reaches 0. In other words, the creator of the
Havoc Pennington's avatar
Havoc Pennington committed
574
575
        <structname>GConfEngine</structname> "owns" a reference to the 
        <structname>GConfEngine</structname> as soon as it's created, and
576
577
        should call <function>gconf_engine_unref()</function> to make it 
        go away. <function>gconf_engine_ref()</function> creates a new
Havoc Pennington's avatar
Havoc Pennington committed
578
        reference to the <structname>GConfEngine</structname>.
579
580
581
        <funcsynopsis>
          <funcsynopsisinfo>#include &lt;gconf/gconf.h&gt;</funcsynopsisinfo>
          <funcdef>void
582
            <function>gconf_engine_ref</function>
583
          </funcdef>
Havoc Pennington's avatar
Havoc Pennington committed
584
          <paramdef>GConfEngine* <parameter>conf</parameter></paramdef>
585
586
587
588
589
        </funcsynopsis>

        <funcsynopsis>
          <funcsynopsisinfo>#include &lt;gconf/gconf.h&gt;</funcsynopsisinfo>
          <funcdef>void
590
            <function>gconf_engine_unref</function>
591
          </funcdef>
Havoc Pennington's avatar
Havoc Pennington committed
592
          <paramdef>GConfEngine* <parameter>conf</parameter></paramdef>
593
594
595
        </funcsynopsis>
      </para>

596
    </sect1>
597

Havoc Pennington's avatar
Havoc Pennington committed
598
    <!-- GConfValue -->
599
    <sect1>
Havoc Pennington's avatar
Havoc Pennington committed
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
      <title>The <structname>GConfValue</structname> Datatype</title>
      
      <para>
        The <structname>GConfValue</structname> struct represents 
        a value that can be obtained from or stored in the
        configuration database. It is simply a type marker 
        and a union of several value types, with constructor,
        destructor, "setter" and "getter" functions. When possible 
        the GConf library allows you to deal with simple C types
        instead of a <structname>GConfValue</structname>, but 
        sometimes there is simply no way to know the type of an 
        object in advance. The <filename>libgnome/gnome-config.h</filename>
        interface simply returns strings in this case, for the
        programmer to parse manually; this was phenomenally broken and
        GConf fixes it with <structname>GConfValue</structname>.        
      </para>

617
      <sect2>
618
619
620
621
622
623
624
625
626
627
628
629
        <title>Accessing <structname>GConfValue</structname></title>
        <para>
          To read a <structname>GConfValue</structname>, you first 
          determine its type and then read the value using one 
          of its accessor macros. The following useless code should 
          demonstrate this:
          <programlisting>            
void
print_value(GConfValue* value)
{    
  switch (value->type)
    {
630
    case GCONF_VALUE_STRING:
631
      printf("%s\n", gconf_value_get_string(value));
632
      break;
633
    case GCONF_VALUE_INT:
634
      printf("%d\n", gconf_value_get_int(value));
635
      break;
636
    case GCONF_VALUE_FLOAT:
637
      printf("%g\n", gconf_value_get_float(value));
638
      break;
639
    case GCONF_VALUE_BOOL:
640
      printf("%s", gconf_value_get_bool(value) ? "true" : "false");
641
      break;
642
    case GCONF_VALUE_SCHEMA:
643
      {
644
        GConfSchema* schema = gconf_value_get_schema(value);
645
646
647
648

        /* printing a schema would be complicated, you get the idea */
      }
      break;
649
    case GCONF_VALUE_LIST:
650
      {
651
        GSList* iter = gconf_value_get_list(value);
652
653
654
655
656
657
658
659
660
661
662

        while (iter != NULL)
          {
            GConfValue* element = iter->data;
            
            print_value(element);
            
            iter = g_slist_next(iter);
          }
      }
      break;
663
    case GCONF_VALUE_PAIR:
664
665
      print_value(gconf_value_get_car(value));
      print_value(gconf_value_get_cdr(value));
666
      break;
667
    case GCONF_VALUE_INVALID:
668
669
670
671
672
      /* This is used internally by GConf, you can also
         use it yourself to indicate errors and such. It
         won't be returned from GConf functions though. */
      printf("invalid value");
      break;
Havoc Pennington's avatar
Havoc Pennington committed
673
      
674
675
676
677
678
679
680
681
682
    default:
      g_assert_not_reached();
      break;
    }
}
          </programlisting>
        </para>

        <para>
683
684
685
          A special note about values of type <symbol>GCONF_VALUE_LIST</symbol>:
          the list contains <structname>GConfValue</structname> objects, and all
          objects in the list must have the same type. You can get the type of
686
          the list with the <function>gconf_value_get_list_type()</function> macro.
687
688
        </para>

689
      </sect2>
690

691
      <sect2>
692
693
694
        <title>Creating/destroying a <structname>GConfValue</structname></title>
        <para>
          Often you obtain a <structname>GConfValue</structname> from 
695
          a GConf routine such as <function>gconf_engine_get ()</function>,
696
          but you can also create them yourself with
697
698
          <function>gconf_value_new()</function>.
          <function>gconf_value_new()</function> takes a single
699
          argument, the type of the newly-created value. Value types
700
701
702
703
          can't be changed after creating the value.
          <funcsynopsis>
            <funcsynopsisinfo>#include &lt;gconf/gconf-value.h&gt;</funcsynopsisinfo>
            <funcdef>GConfValue*
704
              <function>gconf_value_new</function>
705
706
707
708
709
710
711
712
713
            </funcdef>
            <paramdef>GConfValueType <parameter>type</parameter></paramdef>
          </funcsynopsis>
          Note that <filename>gconf/gconf-value.h</filename> is
          automatically included by <filename>gconf/gconf.h</filename>.          
        </para>

        <warning><title>You must initialize your values</title>
          <para>
714
715
716
717
718
            Newly-constructed values are invalid; if you use the accessor macros
            before you set the contents of the value, the results are
            undefined. Use <function>gconf_value_set_int()</function>,
            <function>gconf_value_set_string()</function>, and so on to
            initialize the value.
719
720
721
722
723
          </para>
        </warning>

        <para>
          You can destroy a <structname>GConfValue</structname> with 
724
          <function>gconf_value_free()</function>, and copy one
725
          with <function>gconf_value_copy()</function>. The copy is a
726
727
728
729
730
          deep copy, that is, child values contained in lists or 
          pairs are also copied.
          <funcsynopsis>
            <funcsynopsisinfo>#include &lt;gconf/gconf-value.h&gt;</funcsynopsisinfo>
            <funcdef>GConfValue*
731
              <function>gconf_value_copy</function>
732
733
734
            </funcdef>
            <paramdef>GConfValue* <parameter>src</parameter></paramdef>
            <funcdef>void
735
              <function>gconf_value_free</function>
736
737
738
739
            </funcdef>
            <paramdef>GConfValue* <parameter>value</parameter></paramdef>
          </funcsynopsis>
        </para>
740
      </sect2>
Havoc Pennington's avatar
Havoc Pennington committed
741

742
    </sect1>
Havoc Pennington's avatar
Havoc Pennington committed
743
744

    <!-- Reading configuration values -->
745
746
    <sect1>
      <title>Reading/Writing Configuration Values</title>
Havoc Pennington's avatar
Havoc Pennington committed
747

748
749
750
751
      <sect2>
        <title>Reading</title>
        <para>
          The "raw" function for obtaining the value stored at a given key in the
752
753
          configuration database is <function>gconf_engine_get ()</function>.
          <function>gconf_engine_get ()</function> returns a
754
755
          <structname>GConfValue</structname> if the key was set, or
          <symbol>NULL</symbol> if the key was unset or an error occurred. If an
756
          error occurred a <structname>GError</structname> is returned in the
757
758
759
760
761
762
          location given as the final argument.
        </para>
        
        <para>
          There are also convenience functions that automatically convert
          <structname>GConfValue</structname> to primitive C types. These include
763
764
          <function>gconf_engine_get_int()</function>,
          <function>gconf_engine_get_bool()</function>, and so on.
765
766
767
768
769
770
771
772
773
774
        </para>

      </sect2>

      <sect2>
        <title>Writing</title>
        <para>
          
        </para>
      </sect2>
775

776
777
    </sect1>
  </chapter>
778

779
  <!-- GObject wrapper -->
780
781
  <chapter id="gconf-client">
    <title><structname>GConfClient</structname> higher-level API</title>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
782
783
    
    <para>
Havoc Pennington's avatar
Havoc Pennington committed
784
      <structname>GConfClient</structname> is a
785
786
787
788
789
790
791
792
      <structname>GObject</structname> subclass that should be used
      instead of <structname>GConfEngine</structname> in most
      applications. <structname>GConfClient</structname> tries to
      minimize the need to make remote calls to the GConf daemon by
      keeping more information on the client side. It also has a
      default error handler that comes into play if you pass NULL 
      for the <literal>GError**</literal> argument to any 
      <structname>GConfClient</structname> methods.
Havoc Pennington's avatar
Havoc Pennington committed
793
794
795
796
    </para>

    <sect1 id="gconfclient-example">
      <title>A Complete Example</title>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
797
      
798
      <para>
799
800
        The example is in examples/basic-gconf-app.c in the GConf
        tarball, but hasn't made it into this document yet.
801
      </para>
Havoc Pennington's avatar
Havoc Pennington committed
802
803
804
805
806
807
808
809
810
811
812
813
814
      

    </sect1>

  </chapter>

  <chapter id="conventions">
    <title>GConf Conventions</title>

    <para>
      This chapter describes <emphasis>conventions</emphasis> that
      GConf clients should obey, though the library does not enforce
      them.
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
815
816
    </para>

Havoc Pennington's avatar
Havoc Pennington committed
817
818
819
    <sect1>
      <title>Namespace division</title>

820
      <para>
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
        When choosing GConf keys, you should follow these conventions.
      </para>

      <para>
        <itemizedlist mark="bullet">

          <listitem>
            <para>
              Schemas should go under the <literal>/schemas</literal>
              toplevel directory. Under <literal>/schemas</literal>,
              the normal GConf namespace should be mirrored. So, if you have a
              key <literal>/foo/bar/baz</literal>, the schema for that key should
              be at <literal>/schemas/foo/bar/baz</literal>. If you apply the same
              schema to multiple keys, then obviously the schema name will have
              to differ from the key names; but you should mirror as much of the
              key names as possible. For example, <literal>/foo/bar/baz</literal>
              and <literal>/foo/bar/boo</literal> might have the schema
              <literal>/schemas/foo/bar/baz_and_boo</literal>.
            </para>
          </listitem>


          <listitem>
            <para>
              The GNOME libraries may store preferences for GNOME apps
              under the
              <literal>/apps/gnome-settings/<replaceable>appname</replaceable></literal>
              directory.
              <literal><replaceable>appname</replaceable></literal> will be
              replaced with the name of your app, as passed in to
              <function>gnome_init()</function> (perhaps canonicalized to be a
              legal GConf key). You should not put your own
              settings in this directory, because you may get notifications when
              gnome-libs keys change and gnome-libs may get notifications when
              your keys change. This would be confusing.
            </para>
          </listitem>

          <listitem>
            <para>
              Preferences for applications should go under an
              <literal>/apps/<replaceable>appname</replaceable></literal>
              directory. Try to make
              <literal><replaceable>appname</replaceable></literal> match the
              one passed to <function>gnome_init()</function>, also used in the
              <literal>/apps/gnome-settings/<replaceable>appname</replaceable></literal>
              directory.  Vendors are encouraged to include their vendor name in
              <replaceable>appname</replaceable>, to avoid namespace clashes.
            </para>
          </listitem>

          <listitem>
            <para>
              Preferences for the desktop environment should go under
              <literal>/desktop</literal>. None should be immediately
              under <literal>/desktop</literal>, however. GNOME-specific
              preferences should be under <literal>/desktop/gnome</literal>.
              Settings standardized among multiple desktops should go under
              <literal>/desktop/standard</literal>. Other specific desktops should
              select a directory to use (<literal>/desktop/kde</literal>,
              <literal>/desktop/xfce</literal>, etc.)
            </para>
          </listitem>

          <listitem>
            <para>
              System-level preferences (such as the host name, though
              I'm sure that specific example will never be in GConf) should go
              under <literal>/system</literal>. None should be
              immediately under <literal>/system</literal>, however; select a
              descriptive subdirectory.
            </para>
          </listitem>

          <listitem>
            <para>
              In general, keys under <literal>/system</literal> and
              <literal>/desktop</literal> are for use by multiple applications,
              and keys under
              <literal>/apps/<replaceable>appname</replaceable></literal> are
              for use by a single application.
            </para>
          </listitem>

          <listitem>
            <para>
              If you have a "weird" key that doesn't fit into any of the above
              categories, please mail me (<email>hp@redhat.com</email>) and ask
              for a new directory to be invented. Alternatively, place your key
              under the <literal>/extra</literal> toplevel directory.
            </para>
          </listitem>

        </itemizedlist>
      </para>
Havoc Pennington's avatar
Havoc Pennington committed
916
917
918

    </sect1>

919
920
  </chapter>

921
  <!-- gconftool -->
Havoc Pennington's avatar
Havoc Pennington committed
922
  <chapter id="gconftool">
923
924
925
926
927
928
929
930
931
    <title><application>gconftool</application> Utility Program</title>

    <para>
      <application>gconftool</application> is used to control GConf
      from the command line. 
    </para>

  </chapter>

Havoc Pennington's avatar
Havoc Pennington committed
932
933
934
935
936
937
938
939
  <!-- Schema Files -->
  <chapter>
    <title>Schema Files</title>

    <para>
      This chapter covers the mechanics of writing and installing the
      GConf schema files. Schema files describe your configuration
      data and provide default values for it. See <xref
940
      linkend="concepts-schemas"/> for an explanation of schemas.  The
Havoc Pennington's avatar
Havoc Pennington committed
941
942
      schema file is not understood by the GConf client library;
      rather, <application>gconftool</application> (see <xref
943
      linkend="gconftool"/>) knows how to parse it, and then uses the GConf
Havoc Pennington's avatar
Havoc Pennington committed
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
      client library to install the information in the GConf database.
    </para>

    <sect1>
      <title>Schema File Format</title>
      <para>
        Here is a sample schema file for a hypothetical application, 
        <application>basic-gconf-app</application>, one of the
        examples that comes with the GConf distribution.
        <example>
          <title>Sample schema file</title>
          <programlisting>
&lt;gconfschemafile&gt;
    &lt;schemalist&gt;
      &lt;schema&gt;
      &lt;key&gt;/schemas/apps/basic-gconf-app/fooandbar&lt;/key&gt;
      &lt;applyto&gt;/apps/basic-gconf-app/foo&lt;/applyto&gt;
        &lt;applyto&gt;/apps/basic-gconf-app/bar&lt;/applyto&gt;
      &lt;owner&gt;basic-gconf-app&lt;/owner&gt;
      &lt;type&gt;string&lt;/type&gt;
      &lt;locale name="C"&gt;
        &lt;default&gt;Blah blah blurgh&lt;/default&gt;
        &lt;short&gt;short description in C locale&lt;/short&gt;
        &lt;long&gt;long description of foo and bar in C locale&lt;/long&gt;
      &lt;/locale&gt;
      &lt;locale name="no"&gt;
        &lt;default&gt;some thing in norwegian&lt;/default&gt;
        &lt;short&gt;short description in Norway&lt;/short&gt;
        &lt;long&gt;Long description in Norway. long long long. this is a long sentence.&lt;/long&gt;
      &lt;/locale&gt;
    &lt;/schema&gt;
      &lt;schema&gt;
      &lt;key&gt;/schemas/apps/basic-gconf-app/baz&lt;/key&gt;
      &lt;applyto&gt;/apps/basic-gconf-app/baz&lt;/applyto&gt;
      &lt;owner&gt;basic-gconf-app&lt;/owner&gt;
      &lt;type&gt;string&lt;/type&gt;
      &lt;locale name="C"&gt;
        &lt;default&gt;Zzzzzzzzzz&lt;/default&gt;
        &lt;short&gt;short description in C locale&lt;/short&gt;
        &lt;long&gt;long description of baz in C locale&lt;/long&gt;
      &lt;/locale&gt;
      &lt;locale name="no"&gt;
        &lt;default&gt;some thing in norwegian&lt;/default&gt;
        &lt;short&gt;short description in Norway&lt;/short&gt;
        &lt;long&gt;Long description in Norway. long long long. this is a long sentence.&lt;/long&gt;
      &lt;/locale&gt;
    &lt;/schema&gt;
      &lt;schema&gt;
      &lt;key&gt;/schemas/apps/basic-gconf-app/blah&lt;/key&gt;
      &lt;applyto&gt;/apps/basic-gconf-app/blah&lt;/applyto&gt;
      &lt;owner&gt;basic-gconf-app&lt;/owner&gt;
      &lt;type&gt;string&lt;/type&gt;
      &lt;locale name="C"&gt;
        &lt;default&gt;bllllllaaaaaaaaaaaaaaaaarrrrrrggggggghhhhh&lt;/default&gt;
        &lt;short&gt;short description in C locale&lt;/short&gt;
        &lt;long&gt;long description of blah in C locale&lt;/long&gt;
      &lt;/locale&gt;
      &lt;locale name="no"&gt;
        &lt;default&gt;some thing in norwegian&lt;/default&gt;
        &lt;short&gt;short description in Norway&lt;/short&gt;
        &lt;long&gt;Long description in Norway. long long long. this is a long sentence.&lt;/long&gt;
      &lt;/locale&gt;
    &lt;/schema&gt;
  &lt;/schemalist&gt;  
&lt;/gconfschemafile&gt;
          </programlisting>
        </example>
      </para>
      
      <para>
        The file format is straightforward. The root node must be
        called <literal>&lt;gconfschemafile&gt;</literal>. This
        element contains one or more <literal>&lt;schemalist&gt;</literal>
        elements; I can't think of a reason to use multiple
        <literal>&lt;schemalist&gt;</literal> elements, but you can if 
        you want, and <application>gconftool</application> will load
        each one. The <literal>&lt;schemalist&gt;</literal> in turn 
        contains one or more <literal>&lt;schema&gt;</literal>
        elements. Each of these describes a single schema.        
      </para>

      <warning>
        <para>
          <application>gconftool</application> is not very tolerant
          about whitespace right now; in particular it won't strip
          whitespace from around key names, type names, etc. This is
          broken and will be fixed, just watch out for now.
        </para>
      </warning>

      <para>
        Here are the fields of the <literal>&lt;schema&gt;</literal>
        element:

1038
1039
<informaltable pgwide="1" frame="none">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
Havoc Pennington's avatar
Havoc Pennington committed
1040
1041
1042
1043
1044
<tbody>

<row>
<entry>&lt;key&gt;</entry>
<entry>The key <emphasis>where the schema will be stored</emphasis>;
1045
                  see <xref linkend="conventions"/> for naming
Havoc Pennington's avatar
Havoc Pennington committed
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
                  conventions. There may be only one key per schema.
</entry>

</row>

<row>
<entry>&lt;applyto&gt;</entry>

<entry>A key <emphasis>the schema will be applied to</emphasis>; that
                  is, this schema <emphasis>describes</emphasis> this
1056
                  key.  See <xref linkend="conventions"/> for naming
Havoc Pennington's avatar
Havoc Pennington committed
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
                  conventions. There may be multiple &lt;applyto&gt;
                  elements.</entry>

</row>

<row>
<entry>&lt;owner&gt;</entry>

<entry>Name of the application that uses this schema; may be the
                  command line name, or a human-readable name. However
                  you should use the same value for &lt;owner&gt; for
                  all schemas your app installs. The primary purpose
                  of this field is to enable sysadmins to locate the
                  keys belonging to a given application.                  
                </entry>

</row>

<row>
<entry>&lt;type&gt;</entry>

<entry>The type of values described by this schema. i.e. keys 
the schema is applied to should store values of this type.
Allowed values are: <literal>string</literal>, <literal>int</literal>,
<literal>bool</literal>, <literal>float</literal>,
                  <literal>list</literal>, <literal>pair</literal>
                </entry>

</row>

<row>
<entry>&lt;default&gt;</entry>

<entry>The <literal>&lt;default&gt;</literal> element may 
appear below <literal>&lt;schema&gt;</literal> (a default for all
                  locales, often suitable for numeric values), 
<emphasis>OR</emphasis> below a <literal>&lt;locale&gt;</literal>
element, if the default should be localized. It simply contains the
                  default value for the keys the schema is applied to.
                  
                </entry>

</row>


<row>
<entry>&lt;locale&gt;</entry>

                <entry>
                  The <literal>&lt;locale&gt;</literal> element 
                  contains locale-specific data, including the
                  human-readable short and long descriptions, 
                  and optionally the default value
                  (<literal>&lt;default&gt;</literal> may also be
                  placed directly underneath the
                  <literal>&lt;schema&gt;</literal> element).
                  There should be one
                  <literal>&lt;locale&gt;</literal> element for each
                  locale, with a <literal>name</literal> attribute 
                  specifying the locale name.
                </entry>

</row>


</tbody></tgroup></informaltable>        

        A <literal>&lt;locale&gt;</literal> element can contain 
a locale-specific <literal>&lt;default&gt;</literal>, and may also 
contain short and long descriptions as follows:
1127
1128
<informaltable pgwide="1" frame="none">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
Havoc Pennington's avatar
Havoc Pennington committed
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
<tbody>

<row>
<entry>&lt;short&gt;</entry>
<entry>A short description of the purpose of this key, around 
40 characters long (about half a line).
</entry>

</row>

<row>
<entry>&lt;long&gt;</entry>
<entry>A long description of the configuration key, around a paragraph
                  or two. Should describe the possible values of the 
key and their effect on the application.
</entry>

</row>

</tbody></tgroup></informaltable> 

      </para>

    </sect1>

    <sect1>
      <title>Installing Schemas</title>

      <para>
        There are several things that need to happen at "<literal>make
        install</literal>" time. 
        <itemizedlist mark="bullet">
          <listitem>
            <para>
              The schemas should be installed into a GConf
1164
1165
1166
1167
              configuration source; either the default source, or a
              source specified by the user with a
              <filename>configure</filename> option called
              <literal>--enable-gconf-source</literal>. 
Havoc Pennington's avatar
Havoc Pennington committed
1168
1169
1170
1171
            </para>
          </listitem>
          <listitem>
            <para>
1172
1173
              The schema files should be installed to
              <filename>$(sysconfdir)/gconf/schemas/</filename>,
Havoc Pennington's avatar
Havoc Pennington committed
1174
1175
1176
1177
1178
1179
1180
1181
              making it easy for sysadmins to browse them or 
              bulk-reinstall them into a new configuration source.
            </para>
          </listitem>
        </itemizedlist>
      </para>

      <para>
1182
1183
1184
1185
1186
1187
1188
1189
1190
	The <symbol>AM_GCONF_SOURCE_2</symbol> 
	macro will get the default location to install
	the schema. It will also add a 
	<literal>--enable-gconf-source</literal>
	option and it will look in 
	<filename>$(sysconfdir)/gconf/schema-install-source</filename> 
	for a path.
	The <symbol>GCONF_SCHEMA_CONFIG_SOURCE</symbol> variable 
	will be defined.
1191
1192
      </para>
      <para>
1193
1194
1195
1196
1197
	To get schemas installed properly add the macro to 
	<filename>configure.in</filename>
	<programlisting>
	  AM_GCONF_SOURCE_2
	</programlisting>  
1198
1199
      </para>
      <para>
1200
1201
1202
1203
1204
1205
	And put something like this in <filename>Makefile.am</filename>
	<programlisting>
	  install-schemas:
	      GCONF_CONFIG_SOURCE=$(GCONF_SCHEMA_CONFIG_SOURCE) \
	      gconftool --makefile-install-rule my.schemas
	</programlisting>
Havoc Pennington's avatar
Havoc Pennington committed
1206
1207
1208
1209
1210
1211
1212
      </para>
    </sect1>

    <sect1> 
      <title>Schema File DTD</title>
      
      <para>
1213
        The following DTD was contributed by Mirko Streckenbach.
Havoc Pennington's avatar
Havoc Pennington committed
1214
1215
1216
1217
      </para>

      <para>
        <programlisting>
1218
1219
1220
1221
&lt;!ELEMENT gconfschemafile (schemalist)&gt;

&lt;!ELEMENT schemalist (schema)*&gt;

1222
&lt;!ELEMENT schema  (key,applyto*,owner?,type,(list_type|car_type|cdr_type)?,default?,locale*)&gt;
1223
1224
1225
1226
1227
1228
1229
1230
1231

&lt;!ELEMENT key     (#PCDATA)&gt;

&lt;!ELEMENT applyto (#PCDATA)&gt;

&lt;!ELEMENT owner   (#PCDATA)&gt;

&lt;!ELEMENT type    (#PCDATA)&gt;

1232
1233
1234
1235
1236
1237
&lt;!ELEMENT list_type (#PCDATA)&gt;

&lt;!ELEMENT car_type (#PCDATA)&gt;

&lt;!ELEMENT cdr_type (#PCDATA)&gt;

1238
1239
&lt;!ELEMENT default (#PCDATA)&gt;

1240
1241
1242
1243
1244
&lt;!ELEMENT locale  (default?,short?,long?)&gt;
&lt;!ATTLIST locale  name CDATA #REQUIRED&gt;

&lt;!ELEMENT short   (#PCDATA)&gt;
&lt;!ELEMENT long    (#PCDATA)&gt;
Havoc Pennington's avatar
Havoc Pennington committed
1245
        </programlisting>
1246
      </para>   
Havoc Pennington's avatar
Havoc Pennington committed
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
    </sect1>

  </chapter>

  <!-- Checklist/Summary -->
  <chapter>
    <title>Checklist/Summary</title>

    <para>
      This chapter summarizes the things to consider and actions to 
      take when adding GConf support to an application.
    </para>

    <para>
      
    </para>

  </chapter>

1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
  <!-- GConf reference -->
  <chapter id="gconf-reference">
    <title>GConf Reference Documentation</title>

    &gconf-gconf-engine;
    &gconf-gconf;
    &gconf-gconf-error;
    &gconf-gconf-value;
    &gconf-gconf-schema;
    &gconf-gconf-changeset;

  </chapter>

Havoc Pennington's avatar
Havoc Pennington committed
1279
1280
  <!-- GConfClient reference -->
  <chapter id="gconf-client-reference">
1281
    <title><structname>GObject</structname> Wrapper Reference (<structname>GConfClient</structname>)</title>
Havoc Pennington's avatar
Havoc Pennington committed
1282
1283
1284
1285
1286

    &GConfClient;

  </chapter>

1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
  <!-- GConf Internals Reference -->
  <chapter id="gconf-internals-reference">
    <title>GConf Internal Reference</title>

    &gconf-gconf-backend;
    &gconf-gconf-internals;
    &gconf-gconf-listeners;
    &gconf-gconf-locale;
    &gconf-gconf-sources;
    
  </chapter>
Havoc Pennington's avatar
tweaks    
Havoc Pennington committed
1298

1299
</book>
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
<!-- Keep this comment at the end of the file
Local variables:
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
sgml-auto-insert-required-elements:t
sgml-balanced-tag-edit:t
sgml-normalize-trims:t
sgml-set-face:t
sgml-parent-document:nil
End:
-->