« back to all changes in this revision
Viewing changes to doc/gconf/tmpl/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/tmpl/gconf.sgml
1
<!-- ##### SECTION Title ##### -->
2
3
GConf Core Interfaces
4
5
<!-- ##### SECTION Short_Description ##### -->
6
7
Basic functions to initialize GConf and get/set values
8
9
<!-- ##### SECTION Long_Description ##### -->
10
<para>
11
These functions initialize GConf, and communicate with the
12
<application>gconfd</application> server via a
13
#GConfEngine object. You can install a notification
14
request on the server, get values, set values, list directories, and associate
15
schema names with keys.
16
</para>
17
18
<para>
19
Most of this interface is replicated in the #GtkObject wrapper
20
(#GConfClient object); an alternative to the value-setting functions
21
is the #GConfChangeSet interface.
22
</para>
23
24
<!-- ##### SECTION See_Also ##### -->
25
<para>
26
27
</para>
28
29
<!-- ##### FUNCTION gconf_init ##### -->
30
<para>
31
Initializes the GConf library. Creates a connection to a CORBA ORB, and
32
initializes OAF (the object activation framework) if it isn't already
33
initialized.
34
</para>
35
36
@argc:
37
@argv:
38
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
39
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> otherwise.
40
41
42
<!-- ##### FUNCTION gconf_preinit ##### -->
43
<para>
44
45
</para>
46
47
@app:
48
@mod_info:
49
50
51
<!-- ##### FUNCTION gconf_postinit ##### -->
52
<para>
53
54
</para>
55
56
@app:
57
@mod_info:
58
59
60
<!-- ##### FUNCTION gconf_is_initialized ##### -->
61
<para>
62
Asks whether the library has been initialized.
63
</para>
64
65
@Returns: <symbol>TRUE</symbol> if the library has been initialized.
66
67
68
<!-- ##### USER_FUNCTION GConfNotifyFunc ##### -->
69
<para>
70
A callback function invoked when a key's value changes. The @cnxn_id parameter
71
will be the connection ID returned from gconf_engine_notify_add(). @key will be the
72
full path of the changed key, @value will be the new value if the key is set.
73
If the key is unset, @value will be the default value if one exists, or
74
<symbol>NULL</symbol> otherwise. @is_default indicates whether a value is a
75
default setting or a user setting. If @value is <symbol>NULL</symbol>,
76
@is_default will be <symbol>TRUE</symbol>. @user_data is the data passed to
77
gconf_engine_notify_add().
78
</para>
79
80
@conf: the #GConfEngine passed to gconf_engine_notify_add().
81
@cnxn_id: the ID returned from gconf_engine_notify_add().
82
@entry:
83
@user_data: the user data passed to gconf_engine_notify_add().
84
<!-- # Unused Parameters # -->
85
@key: the full path of the changed key.
86
@value: the new value, or <symbol>NULL</symbol> if the key was unset.
87
@is_default: if <symbol>TRUE</symbol>, the key is unset but this is the default value for it.
88
89
90
<!-- ##### FUNCTION gconf_engine_notify_add ##### -->
91
<para>
92
Registers a notification request with the <application>gconfd</application>
93
server. The server will notify the client when any key at or below
94
@namespace_section is set or unset. Try to watch the smallest possible part of
95
the namespace; otherwise you will slow down the server and your application with
96
unnecessary notifications. Note that you should prefer gconf_client_notify_add()
97
if you're using the #GtkObject wrapper library, because
98
gconf_client_notify_add() does not require a client-server conversation for
99
every callback. gconf_engine_notify_add() requests a different server notification for
100
every callback. The function returns an ID you can use to remove the
101
notification request; 0 is an invalid ID, and is returned if an error occurs.
102
</para>
103
104
@conf: a #GConfEngine to monitor for changes.
105
@namespace_section: the directory or key to watch; you will be notified of changes at or below this point.
106
@func: the callback to invoke when a notification is received from the server.
107
@user_data: the data to pass to the callback.
108
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
109
@Returns: an ID for the notification request, or 0 on error.
110
111
112
<!-- ##### FUNCTION gconf_engine_notify_remove ##### -->
113
<para>
114
Removes a notification request.
115
</para>
116
117
@conf: the #GConfEngine you were monitoring for changes.
118
@cnxn: The ID returned by gconf_engine_notify_add().
119
120
121
<!-- ##### FUNCTION gconf_engine_get ##### -->
122
<para>
123
Returns the #GConfValue stored at @key, or <symbol>NULL</symbol> if no value is
124
set. You must call gconf_value_free() to free the returned value. If you know
125
the expected type of the value, you probably want to use the type-specific
126
convenience wrappers (gconf_engine_get_int(), etc.) because they will do the
127
type-checking for you and return the appropriate type. Automatically returns the
128
default value for a key, if the key is unset and a default exists.
129
</para>
130
131
@conf: a #GConfEngine to get the value from.
132
@key: the key to get.
133
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
134
@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset and no default exists.
135
136
137
<!-- ##### FUNCTION gconf_engine_get_with_locale ##### -->
138
<para>
139
Requests the value appropriate for a particular locale. Right now,
140
only values of type %GCONF_VALUE_SCHEMA are localized; the locale is
141
meaningless for other value types. Also, gconf_engine_get () automatically
142
requests the value in the user's current locale. So this function is
143
only useful if you want a schema for some locale other than the user's
144
current locale. Except for the additional argument, this function is
145
identical to gconf_engine_get () in all respects.
146
</para>
147
148
@conf: a #GConfEngine to get the value from.
149
@key: the key to get.
150
@locale: preferred locale (as in the locale-related environment variables).
151
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
152
@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset.
153
154
155
<!-- ##### FUNCTION gconf_engine_get_without_default ##### -->
156
<para>
157
Identical to gconf_engine_get (), except that it will return <symbol>NULL</symbol> in
158
place of the default value if the key is unset. Note that gconf_engine_get () can also
159
return <symbol>NULL</symbol> if no default exists or an error occurs.
160
</para>
161
162
@conf: a #GConfEngine to get the value from.
163
@key: the key to get.
164
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
165
@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset.
166
167
168
<!-- ##### FUNCTION gconf_engine_get_entry ##### -->
169
<para>
170
Obtain the full #GConfEntry for a value.
171
</para>
172
173
@conf:
174
@key:
175
@locale:
176
@use_schema_default:
177
@err:
178
@Returns:
179
180
181
<!-- ##### FUNCTION gconf_engine_get_default_from_schema ##### -->
182
<para>
183
Returns the default value stored in the key's schema, if the key has a schema
184
associated and the schema exists and the schema contains a default value. Note
185
that gconf_engine_get (), gconf_engine_get_string(), and so on already return the default value
186
if no other value is found, so normally you do not need this function. This
187
function is just for convenience; you could also get the #GConfMetaInfo for the
188
key, read the schema name from there, then look up the schema by name and
189
extract the default value.
190
</para>
191
192
@conf: a #GConfEngine to get the value from.
193
@key: the key to get the default value for.
194
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
195
@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset.
196
197
198
<!-- ##### FUNCTION gconf_engine_set ##### -->
199
<para>
200
Sets the value of @key to @value. Does not modify the passed-in
201
#GConfValue, you must free it yourself. You may prefer a type-specific
202
convenience wrapper, such as gconf_engine_set_int().
203
</para>
204
205
<para>
206
An error of note is %GCONF_OVERRIDDEN, indicating that the system
207
administrator has "forced" a value for this key. If no writable
208
configuration sources exist, it is not an error, but GConf will just
209
forget all your values; this allows users to have a configuration-free
210
setup without a constant barrage of error messages.
211
</para>
212
213
@conf: a #GConfEngine to set the value in.
214
@key: the key to set.
215
@value: the new value of @key.
216
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
217
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
218
219
220
<!-- ##### FUNCTION gconf_engine_unset ##### -->
221
<para>
222
Unsets the value of @key; if @key is already unset, has no effect. An
223
error of note is %GCONF_OVERRIDDEN, indicating that the system
224
administrator has "forced" a value for this key.
225
</para>
226
227
@conf: a #GConfEngine to affect.
228
@key: the key to unset.
229
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
230
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
231
232
233
<!-- ##### FUNCTION gconf_engine_associate_schema ##### -->
234
<para>
235
Directs GConf to find the schema for @key at location
236
@schema_key. That is, the value stored at @schema_key should have type
237
#GCONF_VALUE_SCHEMA, and be descriptive of @key. Normally you don't
238
call this function from C code; you can ship a special file with your
239
application and ask <application>gconftool</application> to install
240
schema associations into the database during "make install."
241
</para>
242
243
@conf: a #GConfEngine to affect.
244
@key: the key to associate the schema with.
245
@schema_key: the key where the schema will be stored.
246
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
247
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
248
249
250
<!-- ##### FUNCTION gconf_engine_all_entries ##### -->
251
<para>
252
Lists the key-value pairs in @dir. Does not list subdirectories; for
253
that use gconf_engine_all_dirs(). The returned list contains #GConfEntry
254
objects. A #GConfEntry contains a <emphasis>relative</emphasis> key
255
and a value. The list is not recursive, it contains only the immediate
256
children of @dir. To free the returned list, gconf_entry_free()
257
each list element, then g_slist_free() the list itself.
258
</para>
259
260
@conf: a #GConfEngine.
261
@dir: Directory to list.
262
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
263
@Returns: List of #GConfEntry.
264
265
266
<!-- ##### FUNCTION gconf_engine_all_dirs ##### -->
267
<para>
268
Lists the subdirectories in @dir. The returned list contains allocated
269
strings; you should g_free() each string in the list, then
270
g_slist_free() the list itself.
271
</para>
272
273
@conf: a #GConfEngine.
274
@dir: Directory to get subdirectories from.
275
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
276
@Returns: List of allocated subdirectory names.
277
278
279
<!-- ##### FUNCTION gconf_engine_suggest_sync ##### -->
280
<para>
281
Suggests to <application>gconfd</application> that you've just finished
282
a block of changes, and it would be an optimal time to sync to
283
permanent storage. This is only a suggestion; and
284
<application>gconfd</application> will eventually sync even if you
285
don't call gconf_engine_suggest_sync(). This function is just a "hint"
286
provided to <application>gconfd</application> to maximize efficiency
287
and minimize data loss.
288
</para>
289
290
@conf: the #GConfEngine to suggest syncing to.
291
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
292
293
294
<!-- ##### FUNCTION gconf_engine_dir_exists ##### -->
295
<para>
296
Queries whether the directory @dir exists in the GConf
297
database. Returns <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
298
</para>
299
300
@conf: a #GConfEngine.
301
@dir: Directory to check for.
302
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
303
@Returns: <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
304
305
306
<!-- ##### FUNCTION gconf_valid_key ##### -->
307
<para>
308
Asks whether a key is syntactically correct, that is, it ensures that
309
the key consists of slash-separated strings and contains only legal
310
characters. Normally you shouldn't need to call this function; the
311
GConf functions all check this for you and return an error if the key
312
is invalid. However, it may be useful to validate input to an entry
313
field or the like. If you pass a non-<symbol>NULL</symbol> address as
314
the @why_invalid argument, an allocated string is returned explaining
315
why the key is invalid, if it is. If the key is valid the @why_invalid
316
argument is unused.
317
</para>
318
319
@key: key to check.
320
@why_invalid: return location for an explanation of the problem, if any. g_free() the returned string.
321
@Returns: <symbol>TRUE</symbol> if the key is valid, or <symbol>FALSE</symbol> if not.
322
323
324
<!-- ##### FUNCTION gconf_key_is_below ##### -->
325
<para>
326
Asks whether the key @below would be found below the key @above, were
327
they both to exist in the database. For example, <symbol>/foo</symbol>
328
is always found below <symbol>/</symbol> and above
329
<symbol>/foo/bar</symbol>. This probably isn't useful but GConf uses
330
it internally so here it is if you need it.
331
</para>
332
333
@above: the key on the "left hand side" of the predicate.
334
@below: the key on the "right hand side."
335
@Returns: <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
336
337
338
<!-- ##### FUNCTION gconf_engine_get_float ##### -->
339
<para>
340
Requests the floating point number (%GCONF_VALUE_FLOAT) stored at
341
@key. Automatically performs type-checking, so if a non-float is
342
stored at @key, an error is returned. On error, or if @key is unset,
343
0.0 is returned.
344
</para>
345
346
@conf: a #GConfEngine.
347
@key: key you want the value of.
348
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
349
@Returns: the value of @key, or 0.0 if no value is obtained.
350
351
352
<!-- ##### FUNCTION gconf_engine_get_int ##### -->
353
<para>
354
Requests the integer (%GCONF_VALUE_INT) stored at
355
@key. Automatically performs type-checking, so if a non-integer is
356
stored at @key, an error is returned. On error, or if @key is unset,
357
0 is returned.
358
</para>
359
360
@conf: a #GConfEngine.
361
@key: key you want the value of.
362
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
363
@Returns: the value of @key, or 0 if no value is obtained.
364
365
366
<!-- ##### FUNCTION gconf_engine_get_string ##### -->
367
<para>
368
Requests the string (%GCONF_VALUE_STRING) stored at
369
@key. Automatically performs type-checking, so if a non-string is
370
stored at @key, an error is returned. On error, or if @key is unset,
371
<symbol>NULL</symbol> is returned.
372
</para>
373
374
@conf: a #GConfEngine.
375
@key: key you want the value of.
376
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
377
@Returns: allocated string (value of @key), or <symbol>NULL</symbol> if no value is obtained.
378
379
380
<!-- ##### FUNCTION gconf_engine_get_bool ##### -->
381
<para>
382
Requests the boolean value (%GCONF_VALUE_BOOL) stored at
383
@key. Automatically performs type-checking, so if a non-bool is
384
stored at @key, an error is returned. On error, or if @key is unset,
385
<symbol>FALSE</symbol> is returned.
386
</para>
387
388
@conf: a #GConfEngine.
389
@key: key you want the value of.
390
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
391
@Returns: the value of @key, or <symbol>FALSE</symbol> if no value is obtained.
392
393
394
<!-- ##### FUNCTION gconf_engine_get_schema ##### -->
395
<para>
396
Requests the schema (%GCONF_VALUE_SCHEMA) stored at @key.
397
Automatically performs type-checking, so if a non-schema is stored at
398
@key, an error is returned. If no value is set or an error occurs,
399
<symbol>NULL</symbol> is returned.
400
</para>
401
402
@conf: a #GConfEngine.
403
@key: key you want the value of.
404
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
405
@Returns: the value of @key as an allocated #GConfSchema, or <symbol>NULL</symbol> if no value was obtained.
406
407
408
<!-- ##### FUNCTION gconf_engine_get_list ##### -->
409
<para>
410
Requests the list (%GCONF_VALUE_LIST) stored at @key. Automatically
411
performs type-checking, so if a non-list is stored at @key, or the
412
list does not contain elements of type @list_type, an error is
413
returned. If no value is set or an error occurs, <symbol>NULL</symbol>
414
is returned. Note that <symbol>NULL</symbol> is also the empty list,
415
so if you need to distinguish the empty list from an unset value, you
416
must use gconf_engine_get () to obtain a raw #GConfValue.
417
</para>
418
419
<para>
420
<emphasis>Remember that GConf lists can only store primitive types:
421
%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
422
%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember
423
that lists must be uniform, you may not mix types in the same list.
424
</para>
425
426
<para>
427
The type of the list elements depends on @list_type. A #GConfValue
428
with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue
429
objects. gconf_engine_get_list() automatically converts to primitive C
430
types. Thus, the list->data fields in the returned list
431
contain:
432
433
<informaltable pgwide=1 frame="none">
434
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
435
<tbody>
436
437
<row>
438
<entry>%GCONF_VALUE_INT</entry>
439
<entry>The integer itself, converted with GINT_TO_POINTER()</entry>
440
</row>
441
442
<row>
443
<entry>%GCONF_VALUE_BOOL</entry>
444
<entry>The bool itself, converted with GINT_TO_POINTER()</entry>
445
</row>
446
447
<row>
448
<entry>%GCONF_VALUE_FLOAT</entry>
449
<entry>A pointer to #gdouble, which should be freed with g_free()</entry>
450
</row>
451
452
<row>
453
<entry>%GCONF_VALUE_STRING</entry>
454
<entry>A pointer to #gchar, which should be freed with g_free()</entry>
455
</row>
456
457
<row>
458
<entry>%GCONF_VALUE_SCHEMA</entry>
459
<entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry>
460
</row>
461
462
</tbody></tgroup></informaltable>
463
464
In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must
465
g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must
466
gconf_schema_free() each element. In all cases you must free the
467
list itself with g_slist_free().
468
</para>
469
470
@conf: a #GConfEngine.
471
@key: key you want the value of.
472
@list_type: type of each list element.
473
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
474
@Returns: an allocated list, with elements as described above.
475
476
477
<!-- ##### FUNCTION gconf_engine_get_pair ##### -->
478
<para>
479
Requests the pair (%GCONF_VALUE_PAIR) stored at @key. Automatically
480
performs type-checking, so if a non-pair is stored at @key, or the
481
pair does not have the right @car_type and @cdr_type, an error is
482
returned. Remember that the <firstterm>car</firstterm> of a pair is
483
its first value, and the <firstterm>cdr</firstterm> is its second
484
value, in the Lisp tradition.
485
</para>
486
487
<para>
488
<emphasis>Remember that GConf pairs can only store primitive types:
489
%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
490
%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis>
491
</para>
492
493
<para>
494
gconf_engine_get_pair() stores the two fields of the pair in the locations
495
pointed to by @car_retloc and @cdr_retloc. The type of these pointers
496
depends on the corresponding @car_type and @cdr_type:
497
498
<informaltable pgwide=1 frame="none">
499
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
500
<tbody>
501
502
<row>
503
<entry>%GCONF_VALUE_INT</entry>
504
<entry>pointer to #gint</entry>
505
</row>
506
507
<row>
508
<entry>%GCONF_VALUE_BOOL</entry>
509
<entry>pointer to #gboolean</entry>
510
</row>
511
512
<row>
513
<entry>%GCONF_VALUE_FLOAT</entry>
514
<entry>pointer to #gdouble</entry>
515
</row>
516
517
<row>
518
<entry>%GCONF_VALUE_STRING</entry>
519
<entry>pointer to #gchar*</entry>
520
</row>
521
522
<row>
523
<entry>%GCONF_VALUE_SCHEMA</entry>
524
<entry>pointer to #GConfSchema*</entry>
525
</row>
526
527
</tbody></tgroup></informaltable>
528
529
In the %GCONF_VALUE_STRING case, you must g_free() the string(s)
530
stored in the return location(s). In the %GCONF_VALUE_SCHEMA case you
531
must gconf_schema_free() the returned schema. If there's an error
532
or the value is unset, @car_retloc and @cdr_retloc are left unchanged.
533
</para>
534
535
<para>
536
gconf_engine_get_pair() returns <symbol>TRUE</symbol> on success.
537
</para>
538
539
<para>
540
An example of gconf_engine_get_pair() in action:
541
<programlisting>
542
gdouble car = 10.0;
543
gchar* cdr = NULL;
544
GError* error = NULL;
545
546
if (!gconf_engine_get_pair(conf, "/foo",
547
GCONF_VALUE_FLOAT,
548
GCONF_VALUE_STRING,
549
&car, &cdr, &error))
550
{
551
/* Note: car/cdr should be untouched, because an error occurred */
552
g_assert(error != NULL);
553
fprintf(stderr, "Error: %s\n", error->message);
554
g_error_free(error);
555
error = NULL;
556
}
557
else
558
{
559
/* Note: car/cdr may be untouched even though there was no error,
560
if no value was set for "/foo"
561
*/
562
printf("Found pair (%g,%s)\n", car, cdr);
563
if (cdr != NULL)
564
g_free(cdr);
565
}
566
</programlisting>
567
</para>
568
569
@conf: a #GConfEngine.
570
@key: key you want the value of.
571
@car_type: desired type of the pair's first field (car).
572
@cdr_type: desired type of the pair's second field (cdr).
573
@car_retloc: address of a return location for the car.
574
@cdr_retloc: address of a return location for the cdr.
575
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
576
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
577
578
579
<!-- ##### FUNCTION gconf_engine_set_float ##### -->
580
<para>
581
582
</para>
583
584
@conf: a #GConfEngine.
585
@key:
586
@val:
587
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
588
@Returns:
589
590
591
<!-- ##### FUNCTION gconf_engine_set_int ##### -->
592
<para>
593
594
</para>
595
596
@conf: a #GConfEngine.
597
@key:
598
@val:
599
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
600
@Returns:
601
602
603
<!-- ##### FUNCTION gconf_engine_set_string ##### -->
604
<para>
605
606
</para>
607
608
@conf: a #GConfEngine.
609
@key:
610
@val:
611
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
612
@Returns:
613
614
615
<!-- ##### FUNCTION gconf_engine_set_bool ##### -->
616
<para>
617
618
</para>
619
620
@conf: a #GConfEngine.
621
@key:
622
@val:
623
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
624
@Returns:
625
626
627
<!-- ##### FUNCTION gconf_engine_set_schema ##### -->
628
<para>
629
630
</para>
631
632
@conf: a #GConfEngine.
633
@key:
634
@val:
635
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
636
@Returns:
637
638
639
<!-- ##### FUNCTION gconf_engine_set_list ##### -->
640
<para>
641
642
</para>
643
644
@conf: a #GConfEngine.
645
@key:
646
@list_type:
647
@list:
648
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
649
@Returns:
650
651
652
<!-- ##### FUNCTION gconf_engine_set_pair ##### -->
653
<para>
654
655
</para>
656
657
@conf: a #GConfEngine.
658
@key:
659
@car_type:
660
@cdr_type:
661
@address_of_car:
662
@address_of_cdr:
663
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
664
@Returns:
665
666
667
<!-- ##### STRUCT GConfEnumStringPair ##### -->
668
<para>
669
670
</para>
671
672
@enum_value:
673
@str:
674
675
<!-- ##### FUNCTION gconf_string_to_enum ##### -->
676
<para>
677
It's best to store enumeration values as strings rather than integers. This is
678
robust against changes in the enumeration, and also human-readable.
679
This function makes it more convenient to store enums as strings.
680
</para>
681
682
<para>
683
The first argument is a lookup table, typically declared statically as follows:
684
<programlisting>
685
static GConfEnumStringPair foo_enum_lookup_table[] = {
686
{ FOO_BLAH, "Blah" },
687
{ FOO_BAR, "Bar" },
688
{ 0, NULL }
689
};
690
</programlisting>
691
Note that the last element of the table is <literal>{ 0, NULL }</literal>.
692
Typically the strings you use should be semi-human-readable, for GTK+ and GNOME
693
stripping off the library prefix and converting to StudlyCaps is the recommended
694
convention.
695
</para>
696
697
<para>
698
The function returns <symbol>TRUE</symbol> if a match for the string is found,
699
and if a match is found the enum value is placed in @enum_value_retloc.
700
</para>
701
702
@lookup_table: a lookup table mapping enum values to strings.
703
@str: the string to convert to an enum value.
704
@enum_value_retloc: the address of an enum variable.
705
@Returns: <symbol>TRUE</symbol> if a match was found.
706
707
708
<!-- ##### FUNCTION gconf_enum_to_string ##### -->
709
<para>
710
See gconf_string_to_enum() for background information on this function.
711
</para>
712
713
@lookup_table: a lookup table mapping enum values to strings.
714
@enum_value: the enumeration value to convert to a string.
715
@Returns: a pointer to the proper string in the lookup table, or <symbol>NULL</symbol> if no match was found.
716
717
Loggerhead is a web-based interface for Breezy
Version: 2.0.1