~ubuntu-branches/ubuntu/precise/gconf/precise-201203060106
» Revision
67
: doc/gconf/tmpl/gconf.sgml
« back to all changes in this revision
Viewing changes to doc/gconf/tmpl/gconf.sgml
- browse files at revision 67
- compare with another revision
- download diff
- download tarball
- view history from revision 67
- Committer: Bazaar Package Importer
- Author(s): Sebastien Bacher
- Date: 2011-06-20 15:34:28 UTC
- mfrom: (7.3.5 sid)
- Revision ID: james.westby@ubuntu.com-20110620153428-987fqlh34dlhnhta
Tags: 2.32.4-1ubuntu1
* Rebase on the current Debian revision.
* debian/control.in, debian/rules: build with GTK3
* debian/control.in, debian/rules: build with GTK3
- files removed:
- doc/gconf/gconf.types
- files modified:
- .pc/04_manpage.patch/doc/gconftool-2.1
added
removed
doc/gconf/tmpl/gconf.sgml
1
<!-- ##### SECTION Title ##### -->
2
GConf Core Interfaces
3
4
<!-- ##### SECTION Short_Description ##### -->
5
6
Basic functions to initialize GConf and get/set values
7
8
<!-- ##### SECTION Long_Description ##### -->
9
<para>
10
These functions initialize GConf, and communicate with the
11
<application>gconfd</application> server via a
12
#GConfEngine object. You can install a notification
13
request on the server, get values, set values, list directories, and associate
14
schema names with keys.
15
</para>
16
17
<para>
18
Most of this interface is replicated in the #GObject wrapper
19
(#GConfClient object); an alternative to the value-setting functions
20
is the #GConfChangeSet interface.
21
</para>
22
23
<!-- ##### SECTION See_Also ##### -->
24
<para>
25
26
</para>
27
28
<!-- ##### SECTION Stability_Level ##### -->
29
30
31
<!-- ##### SECTION Image ##### -->
32
33
34
<!-- ##### FUNCTION gconf_init ##### -->
35
<para>
36
Initializes the GConf library. Creates a connection to a CORBA ORB, and
37
initializes OAF (the object activation framework) if it isn't already
38
initialized.
39
</para>
40
41
@argc:
42
@argv:
43
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
44
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> otherwise.
45
46
47
<!-- ##### FUNCTION gconf_preinit ##### -->
48
<para>
49
50
</para>
51
52
@app:
53
@mod_info:
54
55
56
<!-- ##### FUNCTION gconf_postinit ##### -->
57
<para>
58
59
</para>
60
61
@app:
62
@mod_info:
63
64
65
<!-- ##### FUNCTION gconf_is_initialized ##### -->
66
<para>
67
Asks whether the library has been initialized.
68
</para>
69
70
@void:
71
@Returns: <symbol>TRUE</symbol> if the library has been initialized.
72
73
74
<!-- ##### USER_FUNCTION GConfNotifyFunc ##### -->
75
<para>
76
A callback function invoked when a key's value changes. The @cnxn_id parameter
77
will be the connection ID returned from gconf_engine_notify_add(). @key will be the
78
full path of the changed key, @value will be the new value if the key is set.
79
If the key is unset, @value will be the default value if one exists, or
80
<symbol>NULL</symbol> otherwise. @is_default indicates whether a value is a
81
default setting or a user setting. If @value is <symbol>NULL</symbol>,
82
@is_default will be <symbol>TRUE</symbol>. @user_data is the data passed to
83
gconf_engine_notify_add().
84
</para>
85
86
@conf: the #GConfEngine passed to gconf_engine_notify_add().
87
@cnxn_id: the ID returned from gconf_engine_notify_add().
88
@entry:
89
@user_data: the user data passed to gconf_engine_notify_add().
90
<!-- # Unused Parameters # -->
91
@key: the full path of the changed key.
92
@value: the new value, or <symbol>NULL</symbol> if the key was unset.
93
@is_default: if <symbol>TRUE</symbol>, the key is unset but this is the default value for it.
94
95
96
<!-- ##### FUNCTION gconf_engine_notify_add ##### -->
97
<para>
98
99
</para>
100
101
@conf:
102
@namespace_section:
103
@func:
104
@user_data:
105
@err:
106
@Returns:
107
108
109
<!-- ##### FUNCTION gconf_engine_notify_remove ##### -->
110
<para>
111
Removes a notification request.
112
</para>
113
114
@conf: the #GConfEngine you were monitoring for changes.
115
@cnxn: The ID returned by gconf_engine_notify_add().
116
117
118
<!-- ##### FUNCTION gconf_engine_get ##### -->
119
<para>
120
Returns the #GConfValue stored at @key, or <symbol>NULL</symbol> if no value is
121
set. You must call gconf_value_free() to free the returned value. If you know
122
the expected type of the value, you probably want to use the type-specific
123
convenience wrappers (gconf_engine_get_int(), etc.) because they will do the
124
type-checking for you and return the appropriate type. Automatically returns the
125
default value for a key, if the key is unset and a default exists.
126
</para>
127
128
@conf: a #GConfEngine to get the value from.
129
@key: the key to get.
130
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
131
@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset and no default exists.
132
133
134
<!-- ##### FUNCTION gconf_engine_get_without_default ##### -->
135
<para>
136
Identical to gconf_engine_get (), except that it will return <symbol>NULL</symbol> in
137
place of the default value if the key is unset. Note that gconf_engine_get () can also
138
return <symbol>NULL</symbol> if no default exists or an error occurs.
139
</para>
140
141
@conf: a #GConfEngine to get the value from.
142
@key: the key to get.
143
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
144
@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset.
145
146
147
<!-- ##### FUNCTION gconf_engine_get_entry ##### -->
148
<para>
149
Obtain the full #GConfEntry for a value.
150
</para>
151
152
@conf: a #GConfEngine.
153
@key: the key to get.
154
@locale: preferred locale (as in the locale-related environment variables).
155
@use_schema_default: a #gboolean value indicating whether the default value associated with schema
156
should be used.
157
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
158
@Returns: a #GConfEntry.
159
160
161
<!-- ##### FUNCTION gconf_engine_get_with_locale ##### -->
162
<para>
163
Requests the value appropriate for a particular locale. Right now,
164
only values of type %GCONF_VALUE_SCHEMA are localized; the locale is
165
meaningless for other value types. Also, gconf_engine_get () automatically
166
requests the value in the user's current locale. So this function is
167
only useful if you want a schema for some locale other than the user's
168
current locale. Except for the additional argument, this function is
169
identical to gconf_engine_get () in all respects.
170
</para>
171
172
@conf: a #GConfEngine to get the value from.
173
@key: the key to get.
174
@locale: preferred locale (as in the locale-related environment variables).
175
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
176
@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset.
177
178
179
<!-- ##### FUNCTION gconf_engine_get_default_from_schema ##### -->
180
<para>
181
Returns the default value stored in the key's schema, if the key has a schema
182
associated and the schema exists and the schema contains a default value. Note
183
that gconf_engine_get (), gconf_engine_get_string(), and so on already return the default value
184
if no other value is found, so normally you do not need this function. This
185
function is just for convenience; you could also get the #GConfMetaInfo for the
186
key, read the schema name from there, then look up the schema by name and
187
extract the default value.
188
</para>
189
190
@conf: a #GConfEngine to get the value from.
191
@key: the key to get the default value for.
192
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
193
@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset.
194
195
196
<!-- ##### FUNCTION gconf_engine_set ##### -->
197
<para>
198
Sets the value of @key to @value. Does not modify the passed-in
199
#GConfValue, you must free it yourself. You may prefer a type-specific
200
convenience wrapper, such as gconf_engine_set_int().
201
</para>
202
203
<para>
204
An error of note is %GCONF_OVERRIDDEN, indicating that the system
205
administrator has "forced" a value for this key. If no writable
206
configuration sources exist, it is not an error, but GConf will just
207
forget all your values; this allows users to have a configuration-free
208
setup without a constant barrage of error messages.
209
</para>
210
211
@conf: a #GConfEngine to set the value in.
212
@key: the key to set.
213
@value: the new value of @key.
214
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
215
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
216
217
218
<!-- ##### FUNCTION gconf_engine_unset ##### -->
219
<para>
220
Unsets the value of @key; if @key is already unset, has no effect. An
221
error of note is %GCONF_OVERRIDDEN, indicating that the system
222
administrator has "forced" a value for this key.
223
</para>
224
225
@conf: a #GConfEngine to affect.
226
@key: the key to unset.
227
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
228
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
229
230
231
<!-- ##### FUNCTION gconf_engine_associate_schema ##### -->
232
<para>
233
Directs GConf to find the schema for @key at location
234
@schema_key. That is, the value stored at @schema_key should have type
235
#GCONF_VALUE_SCHEMA, and be descriptive of @key. Normally you don't
236
call this function from C code; you can ship a special file with your
237
application and ask <application>gconftool</application> to install
238
schema associations into the database during "make install."
239
</para>
240
241
@conf: a #GConfEngine to affect.
242
@key: the key to associate the schema with.
243
@schema_key: the key where the schema will be stored.
244
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
245
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
246
247
248
<!-- ##### FUNCTION gconf_engine_all_entries ##### -->
249
<para>
250
251
</para>
252
253
@conf:
254
@dir:
255
@err:
256
@Returns:
257
258
259
<!-- ##### FUNCTION gconf_engine_all_dirs ##### -->
260
<para>
261
262
</para>
263
264
@conf:
265
@dir:
266
@err:
267
@Returns:
268
269
270
<!-- ##### FUNCTION gconf_engine_suggest_sync ##### -->
271
<para>
272
Suggests to <application>gconfd</application> that you've just finished
273
a block of changes, and it would be an optimal time to sync to
274
permanent storage. This is only a suggestion; and
275
<application>gconfd</application> will eventually sync even if you
276
don't call gconf_engine_suggest_sync(). This function is just a "hint"
277
provided to <application>gconfd</application> to maximize efficiency
278
and minimize data loss.
279
</para>
280
281
@conf: the #GConfEngine to suggest syncing to.
282
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
283
284
285
<!-- ##### FUNCTION gconf_engine_dir_exists ##### -->
286
<para>
287
Queries whether the directory @dir exists in the GConf
288
database. Returns <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
289
</para>
290
291
@conf: a #GConfEngine.
292
@dir: Directory to check for.
293
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
294
@Returns: <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
295
296
297
<!-- ##### FUNCTION gconf_engine_remove_dir ##### -->
298
<para>
299
This function first checks the validity of the gconf key. In case of a local #GConfEngine it removes
300
the directory from the source backend calling gconf_sources_remove_dir (). Otherwise it obtains the
301
configuration database using gconf_engine_get_database () and removes the directory from the database
302
calling ConfigDatabase_remove_dir ().
303
</para>
304
305
@conf: a #GConfEngine.
306
@dir: the name of the directory to be removed.
307
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
308
309
310
<!-- ##### FUNCTION gconf_engine_key_is_writable ##### -->
311
<para>
312
Checks whether the key is writable.
313
</para>
314
315
@conf: a #GConfEngine.
316
@key: the value to be changed.
317
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
318
@Returns: <symbol>TRUE</symbol> if the key is writable, <symbol>FALSE</symbol> if the key is read only.
319
320
321
<!-- ##### FUNCTION gconf_valid_key ##### -->
322
<para>
323
Asks whether a key is syntactically correct, that is, it ensures that
324
the key consists of slash-separated strings and contains only legal
325
characters. Normally you shouldn't need to call this function; the
326
GConf functions all check this for you and return an error if the key
327
is invalid. However, it may be useful to validate input to an entry
328
field or the like. If you pass a non-<symbol>NULL</symbol> address as
329
the @why_invalid argument, an allocated string is returned explaining
330
why the key is invalid, if it is. If the key is valid the @why_invalid
331
argument is unused.
332
</para>
333
334
@key: key to check.
335
@why_invalid: return location for an explanation of the problem, if any. g_free() the returned string.
336
@Returns: <symbol>TRUE</symbol> if the key is valid, or <symbol>FALSE</symbol> if not.
337
338
339
<!-- ##### FUNCTION gconf_key_is_below ##### -->
340
<para>
341
Asks whether the key @below would be found below the key @above, were
342
they both to exist in the database. For example, <symbol>/foo</symbol>
343
is always found below <symbol>/</symbol> and above
344
<symbol>/foo/bar</symbol>. This probably isn't useful but GConf uses
345
it internally so here it is if you need it.
346
</para>
347
348
@above: the key on the "left hand side" of the predicate.
349
@below: the key on the "right hand side."
350
@Returns: <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
351
352
353
<!-- ##### FUNCTION gconf_concat_dir_and_key ##### -->
354
<para>
355
Concatenates the dir and key passed removing the unnecessary '/' characters
356
and returns the new string.
357
</para>
358
359
@dir: the directory.
360
@key: the key.
361
@Returns: the newly concatenated string.
362
363
364
<!-- ##### FUNCTION gconf_unique_key ##### -->
365
<para>
366
Generates a new and unique key using serial number, process id, current time and a
367
random number generated.
368
</para>
369
370
@void:
371
@Returns: a newly created key, a #gchar value.
372
373
374
<!-- ##### FUNCTION gconf_escape_key ##### -->
375
<para>
376
377
</para>
378
379
@arbitrary_text:
380
@len:
381
@Returns:
382
383
384
<!-- ##### FUNCTION gconf_unescape_key ##### -->
385
<para>
386
387
</para>
388
389
@escaped_key:
390
@len:
391
@Returns:
392
393
394
<!-- ##### FUNCTION gconf_engine_get_float ##### -->
395
<para>
396
Requests the floating point number (%GCONF_VALUE_FLOAT) stored at
397
@key. Automatically performs type-checking, so if a non-float is
398
stored at @key, an error is returned. On error, or if @key is unset,
399
0.0 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, or 0.0 if no value is obtained.
406
407
408
<!-- ##### FUNCTION gconf_engine_get_int ##### -->
409
<para>
410
Requests the integer (%GCONF_VALUE_INT) stored at
411
@key. Automatically performs type-checking, so if a non-integer is
412
stored at @key, an error is returned. On error, or if @key is unset,
413
0 is returned.
414
</para>
415
416
@conf: a #GConfEngine.
417
@key: key you want the value of.
418
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
419
@Returns: the value of @key, or 0 if no value is obtained.
420
421
422
<!-- ##### FUNCTION gconf_engine_get_string ##### -->
423
<para>
424
Requests the string (%GCONF_VALUE_STRING) stored at
425
@key. Automatically performs type-checking, so if a non-string is
426
stored at @key, an error is returned. On error, or if @key is unset,
427
<symbol>NULL</symbol> is returned.
428
</para>
429
430
@conf: a #GConfEngine.
431
@key: key you want the value of.
432
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
433
@Returns: allocated string (value of @key), or <symbol>NULL</symbol> if no value is obtained.
434
435
436
<!-- ##### FUNCTION gconf_engine_get_bool ##### -->
437
<para>
438
Requests the boolean value (%GCONF_VALUE_BOOL) stored at
439
@key. Automatically performs type-checking, so if a non-bool is
440
stored at @key, an error is returned. On error, or if @key is unset,
441
<symbol>FALSE</symbol> is returned.
442
</para>
443
444
@conf: a #GConfEngine.
445
@key: key you want the value of.
446
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
447
@Returns: the value of @key, or <symbol>FALSE</symbol> if no value is obtained.
448
449
450
<!-- ##### FUNCTION gconf_engine_get_schema ##### -->
451
<para>
452
453
</para>
454
455
@conf:
456
@key:
457
@err:
458
@Returns:
459
460
461
<!-- ##### FUNCTION gconf_engine_get_list ##### -->
462
<para>
463
464
</para>
465
466
@conf:
467
@key:
468
@list_type:
469
@err:
470
@Returns:
471
472
473
<!-- ##### FUNCTION gconf_engine_get_pair ##### -->
474
<para>
475
Requests the pair (%GCONF_VALUE_PAIR) stored at @key. Automatically
476
performs type-checking, so if a non-pair is stored at @key, or the
477
pair does not have the right @car_type and @cdr_type, an error is
478
returned. Remember that the <firstterm>car</firstterm> of a pair is
479
its first value, and the <firstterm>cdr</firstterm> is its second
480
value, in the Lisp tradition.
481
</para>
482
483
<para>
484
<emphasis>Remember that GConf pairs can only store primitive types:
485
%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
486
%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis>
487
</para>
488
489
<para>
490
gconf_engine_get_pair() stores the two fields of the pair in the locations
491
pointed to by @car_retloc and @cdr_retloc. The type of these pointers
492
depends on the corresponding @car_type and @cdr_type:
493
494
<informaltable pgwide="1" frame="none">
495
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
496
<tbody>
497
498
<row>
499
<entry>%GCONF_VALUE_INT</entry>
500
<entry>pointer to #gint</entry>
501
</row>
502
503
<row>
504
<entry>%GCONF_VALUE_BOOL</entry>
505
<entry>pointer to #gboolean</entry>
506
</row>
507
508
<row>
509
<entry>%GCONF_VALUE_FLOAT</entry>
510
<entry>pointer to #gdouble</entry>
511
</row>
512
513
<row>
514
<entry>%GCONF_VALUE_STRING</entry>
515
<entry>pointer to #gchar*</entry>
516
</row>
517
518
<row>
519
<entry>%GCONF_VALUE_SCHEMA</entry>
520
<entry>pointer to #GConfSchema*</entry>
521
</row>
522
523
</tbody></tgroup></informaltable>
524
525
In the %GCONF_VALUE_STRING case, you must g_free() the string(s)
526
stored in the return location(s). In the %GCONF_VALUE_SCHEMA case you
527
must gconf_schema_free() the returned schema. If there's an error
528
or the value is unset, @car_retloc and @cdr_retloc are left unchanged.
529
</para>
530
531
<para>
532
gconf_engine_get_pair() returns <symbol>TRUE</symbol> on success.
533
</para>
534
535
<para>
536
An example of gconf_engine_get_pair() in action:
537
<programlisting>
538
gdouble car = 10.0;
539
gchar* cdr = NULL;
540
GError* error = NULL;
541
542
if (!gconf_engine_get_pair(conf, "/foo",
543
GCONF_VALUE_FLOAT,
544
GCONF_VALUE_STRING,
545
&car, &cdr, &error))
546
{
547
/* Note: car/cdr should be untouched, because an error occurred */
548
g_assert(error != NULL);
549
fprintf(stderr, "Error: %s\n", error->message);
550
g_error_free(error);
551
error = NULL;
552
}
553
else
554
{
555
/* Note: car/cdr may be untouched even though there was no error,
556
if no value was set for "/foo"
557
*/
558
printf("Found pair (%g,%s)\n", car, cdr);
559
if (cdr != NULL)
560
g_free(cdr);
561
}
562
</programlisting>
563
</para>
564
565
@conf: a #GConfEngine.
566
@key: key you want the value of.
567
@car_type: desired type of the pair's first field (car).
568
@cdr_type: desired type of the pair's second field (cdr).
569
@car_retloc: address of a return location for the car.
570
@cdr_retloc: address of a return location for the cdr.
571
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
572
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
573
574
575
<!-- ##### FUNCTION gconf_engine_set_float ##### -->
576
<para>
577
Change the value of @key to @val. Automatically creates the @key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a float (GCONF_VALUE_FLOAT), gconf_engine_set_float() will fail.
578
</para>
579
580
@conf: a #GConfEngine.
581
@key: key you want to set the value of.
582
@val: new value of @key.
583
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
584
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
585
586
587
<!-- ##### FUNCTION gconf_engine_set_int ##### -->
588
<para>
589
Change the value of @key to @val. Automatically creates the @key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store an integer (GCONF_VALUE_INT), gconf_engine_set_int() will fail.
590
</para>
591
592
@conf: a #GConfEngine.
593
@key: key you want to set the value of.
594
@val: new value of @key.
595
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
596
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
597
598
599
<!-- ##### FUNCTION gconf_engine_set_string ##### -->
600
<para>
601
Change the value of @key to @val. Automatically creates the @key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a string (GCONF_VALUE_STRING), gconf_engine_set_string() will fail.
602
</para>
603
604
@conf: a #GConfEngine.
605
@key: key you want to set the value of.
606
@val: new value of @key.
607
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
608
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
609
610
611
<!-- ##### FUNCTION gconf_engine_set_bool ##### -->
612
<para>
613
Change the value of @key to @val. Automatically creates the @key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but but doesn't store a boolean (GCONF_VALUE_BOOL), gconf_engine_set_bool() will fail.
614
</para>
615
616
@conf: a #GConfEngine.
617
@key: key you want to set the value of.
618
@val: new value of @key.
619
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
620
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
621
622
623
<!-- ##### FUNCTION gconf_engine_set_schema ##### -->
624
<para>
625
Change the value of @key to @val. Automatically creates the @key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists but doesn't store a schema value (GCONF_VALUE_SCHEMA), gconf_engine_set_schema() will fail.
626
</para>
627
628
@conf: a #GConfEngine.
629
@key: key you want to set the value of.
630
@val: new value of @key.
631
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
632
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
633
634
635
<!-- ##### FUNCTION gconf_engine_set_list ##### -->
636
<para>
637
Change the value of @key to @list of type @list_type. Automatically creates the @key if it didn't exist before
638
(ie it was unset or it only had a default value). If the key already exists but doesn't store a list value
639
(GCONF_VALUE_LIST), gconf_engine_set_list() will fail.
640
</para>
641
642
@conf: a #GConfEngine.
643
@key: key you want to set the value of.
644
@list_type: type of each list element.
645
@list: new value of @key.
646
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
647
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
648
649
650
<!-- ##### FUNCTION gconf_engine_set_pair ##### -->
651
<para>
652
Change the value of @key to a pair of first type @car_type and second type @cdr_type . Automatically creates the
653
@key if it didn't exist before (ie it was unset or it only had a default value). If the key already exists
654
but doesn't store a schema value (GCONF_VALUE_SCHEMA), gconf_engine_set_schema() will fail.
655
</para>
656
657
@conf: a #GConfEngine.
658
@key: key you want to set the value of.
659
@car_type: type of the pair's first field (car).
660
@cdr_type: type of the pair's second field (cdr).
661
@address_of_car: address of the car.
662
@address_of_cdr: address of the cdr.
663
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
664
@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
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
718
<!-- ##### FUNCTION gconf_clear_cache ##### -->
719
<para>
720
In case of a local #GConfEngine, this function calls gconf_sources_clear_cache () to clear the
721
cache from the source. Otherwise it obtains the configuration database using gconf_engine_get_database ()
722
and clears the configuration database cache using ConfigDatabase_clear_cache ().
723
</para>
724
725
@conf: a #GConfEngine.
726
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
727
728
729
<!-- ##### FUNCTION gconf_synchronous_sync ##### -->
730
<para>
731
In case of a local #GConfEngine, this function syncs up all the gconf sources calling
732
gconf_synchronous_sync (). Otherwise it obtains the configuration database using
733
gconf_engine_get_database () and syncs up the database calling ConfigDatabase_synchronous_sync ().
734
</para>
735
736
@conf: a #GConfEngine.
737
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
738
739
740
<!-- ##### FUNCTION gconf_engine_get_full ##### -->
741
<para>
742
Returns the #GConfValue of a key and the associated #GConfEntry fields depending on the parameters passed.
743
</para>
744
745
@conf: a #GConfEngine.
746
@key: the key whose value is to be obtained.
747
@locale: the preferred locale (as in the locale related environment variables) or<symbol>NULL</symbol> if no locale is to be
748
passed.
749
@use_schema_default: a #gboolean value, indicating whether schema information is to be used as the default
750
value.
751
@is_default_p: a #gpointer if the is_default field of the #GConfEntry is required, <symbol>NULL</symbol>
752
otherwise.
753
@is_writable_p: a #gpointer if the is_writable field of the #GConfEntry is required, <symbol>NULL</symbol>
754
otherwise.
755
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
756
@Returns: the #GConfValue.
757
758
Loggerhead is a web-based interface for Breezy
Version: 2.0.1