~ubuntu-branches/ubuntu/precise/gconf/precise-201203060106
» Revision
67
: doc/gconf/tmpl/gconf-value.sgml
« back to all changes in this revision
Viewing changes to doc/gconf/tmpl/gconf-value.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-value.sgml
1
<!-- ##### SECTION Title ##### -->
2
GConfValue, GConfEntry, GConfMetaInfo
3
4
<!-- ##### SECTION Short_Description ##### -->
5
6
A #GConfValue stores a dynamically-typed value. A #GConfEntry stores a
7
key-value pair. A #GConfMetaInfo stores metainformation about a key.
8
9
<!-- ##### SECTION Long_Description ##### -->
10
<para>
11
#GConfValue stores one of the value types GConf understands; GConf
12
uses #GConfValue to pass values around because it doesn't know the
13
type of its values at compile time.
14
</para>
15
16
<para>
17
A #GConfEntry pairs a relative key
18
name with a value, for example if the value "10" is stored at the key
19
"/foo/bar/baz", the #GConfEntry will store "baz" and "10".
20
</para>
21
22
<para>
23
A #GConfMetaInfo object holds metainformation about a key, such as
24
its last modification time and the name of the schema associated with
25
it. You should rarely if ever need to use #GConfMetaInfo.
26
(In fact you can't get the metainfo for a key using the current API.)
27
</para>
28
29
<!-- ##### SECTION See_Also ##### -->
30
<para>
31
32
</para>
33
34
<!-- ##### SECTION Stability_Level ##### -->
35
36
37
<!-- ##### SECTION Image ##### -->
38
39
40
<!-- ##### ENUM GConfValueType ##### -->
41
<para>
42
Used to indicate the type of a #GConfValue.
43
</para>
44
45
@GCONF_VALUE_INVALID: Never the type of a #GConfValue obtained from GConf functions; used to indicate errors and the like.
46
@GCONF_VALUE_STRING: String value (#gchar*).
47
@GCONF_VALUE_INT: Integer value (#gint).
48
@GCONF_VALUE_FLOAT: Floating point value (#gdouble).
49
@GCONF_VALUE_BOOL: Boolean value (#gboolean).
50
@GCONF_VALUE_SCHEMA: Schema value (#GConfSchema).
51
@GCONF_VALUE_LIST: List of #GConfValue; #GConfValue elements must have
52
a primitive type (i.e. they may not be lists or pairs), and all elements
53
of a list must have the same type.
54
@GCONF_VALUE_PAIR: Pair of #GConfValue; the first field (car) and the second
55
field (cdr) may have different types. The two elements of a pair must be primitive
56
types, not lists or pairs.
57
58
<!-- ##### STRUCT GConfValue ##### -->
59
<para>
60
Represents a dynamically-typed value. The @type field tells you the
61
type of the value; the other fields should be accessed with the
62
accessor functions and macros.
63
</para>
64
65
<para>
66
<emphasis>A #GConfValue should always
67
be initialized before use. That is, you should not use a #GConfValue
68
unless you have called one of the functions beginning with
69
"gconf_value_set_".</emphasis>. For lists, initialization has two
70
steps: first you must set the list element type, then you must set the
71
list value.
72
</para>
73
74
@type: The #GConfValueType of this #GConfValue. The only field of
75
#GConfValue you should access directly.
76
77
<!-- ##### MACRO GCONF_VALUE_TYPE_VALID ##### -->
78
<para>
79
80
</para>
81
82
@x:
83
84
85
<!-- ##### FUNCTION gconf_value_get_string ##### -->
86
<para>
87
Returns a <symbol>const gchar*</symbol> for a #GConfValue with type
88
%GCONF_VALUE_STRING. The returned string is <emphasis>not</emphasis> a
89
copy, don't try to free it. It is "owned" by the #GConfValue and will
90
be destroyed when the #GConfValue is destroyed.
91
</para>
92
93
<para>
94
If the #GConfValue is not initialized (i.e. no one has called
95
gconf_value_set_string()) then the string may be
96
<symbol>NULL</symbol>, but of course you should not try to use an
97
uninitialized #GConfValue.
98
</para>
99
100
@value: a #GConfValue.
101
@Returns: a const char*.
102
103
104
<!-- ##### FUNCTION gconf_value_get_int ##### -->
105
<para>
106
Returns a #gint for a #GConfValue with type %GCONF_VALUE_INT.
107
</para>
108
109
@value: a #GConfValue.
110
@Returns: a #gint.
111
112
113
<!-- ##### FUNCTION gconf_value_get_float ##### -->
114
<para>
115
Returns a #gdouble for a #GConfValue with type %GCONF_VALUE_FLOAT.
116
</para>
117
118
@value: a #GConfValue.
119
@Returns: a #gdouble.
120
121
122
<!-- ##### FUNCTION gconf_value_get_list_type ##### -->
123
<para>
124
Returns the type of the list elements in a #GConfValue with type
125
%GCONF_VALUE_LIST.
126
</para>
127
128
@value: a #GConfValue.
129
@Returns: the type of the list elements (a primitive type).
130
131
132
<!-- ##### FUNCTION gconf_value_get_list ##### -->
133
<para>
134
135
</para>
136
137
@value:
138
@Returns:
139
140
141
<!-- ##### FUNCTION gconf_value_get_car ##### -->
142
<para>
143
Returns the first member (car) of a #GConfValue with type
144
%GCONF_VALUE_PAIR. The car is another #GConfValue, with a primitive
145
type (bool, int, float, string, schema).
146
</para>
147
148
<para>
149
The returned value is not a copy; it is "owned" by the pair and will
150
be destroyed when the pair is destroyed.
151
</para>
152
153
@value: a #GConfValue.
154
@Returns: the first member of a pair, a primitive type.
155
156
157
<!-- ##### FUNCTION gconf_value_get_cdr ##### -->
158
<para>
159
Returns the second member (cdr) of a #GConfValue with type
160
%GCONF_VALUE_PAIR. The cdr is another #GConfValue, with a primitive
161
type (bool, int, float, string, schema).
162
</para>
163
164
<para>
165
The returned value is not a copy; it is "owned" by the pair and will
166
be destroyed when the pair is destroyed.
167
</para>
168
169
@value: a #GConfValue.
170
@Returns: the second member of a pair, a primitive type.
171
172
173
<!-- ##### FUNCTION gconf_value_get_bool ##### -->
174
<para>
175
Returns a #gboolean for a #GConfValue with type %GCONF_VALUE_BOOL.
176
</para>
177
178
@value: a #GConfValue.
179
@Returns: a #gboolean value.
180
181
182
<!-- ##### FUNCTION gconf_value_get_schema ##### -->
183
<para>
184
Returns a #GConfSchema for a #GConfValue with type
185
%GCONF_VALUE_SCHEMA. If the #GConfValue is uninitialized, it
186
may return <symbol>NULL</symbol>; but of course you should have
187
initialized the #GConfValue. The GConf library will not return values
188
with a <symbol>NULL</symbol> schema.
189
</para>
190
191
<para>
192
The returned value is not a copy; it is "owned" by the #GConfValue and will
193
be destroyed when the #GConfValue is destroyed.
194
</para>
195
196
@value: a #GConfValue.
197
@Returns: a #GConfSchema.
198
199
200
<!-- ##### FUNCTION gconf_value_new ##### -->
201
<para>
202
Creates a new #GConfValue with type @type. The type is immutable after
203
creation; values have a fixed type. You <emphasis>must</emphasis>
204
initialize the #GConfValue after creation; that is, you must set its
205
value with one of the "setter" functions.
206
</para>
207
208
@type: type of the new #GConfValue.
209
@Returns: newly-allocated #GConfValue.
210
211
212
<!-- ##### FUNCTION gconf_value_new_from_string ##### -->
213
<para>
214
Creates a new #GConfValue with type @type and value set to the string passed.
215
Based on the value of @type, this function does the appropriate conversion of the
216
string passed to the @type, does error checks to ensure the value is valid, and
217
then calls the appropriate gconf_set function depending on the @type to set the value.
218
</para>
219
220
@type: type of the new #GConfValue.
221
@str: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
222
@err: the value to be set.
223
@Returns: the value to be set.
224
225
226
<!-- ##### FUNCTION gconf_value_copy ##### -->
227
<para>
228
Copies a #GConfValue. The copy is a deep copy, that is, any allocated
229
memory inside the #GConfValue will also be copied.
230
</para>
231
232
@src: a #GConfValue to copy.
233
@Returns: a newly-allocated #GConfValue identical to @src.
234
235
236
<!-- ##### FUNCTION gconf_value_free ##### -->
237
<para>
238
Deallocates a #GConfValue. Also deallocates any allocated memory
239
inside the #GConfValue (such as lists, pair members, strings, and schemas).
240
</para>
241
242
@value: a #GConfValue to destroy.
243
244
245
<!-- ##### FUNCTION gconf_value_set_int ##### -->
246
<para>
247
Sets the value of a #GConfValue with type %GCONF_VALUE_INT.
248
</para>
249
250
@value: a #GConfValue of type %GCONF_VALUE_INT.
251
@the_int: the integer.
252
253
254
<!-- ##### FUNCTION gconf_value_set_string ##### -->
255
<para>
256
Sets the value of a #GConfValue with type
257
%GCONF_VALUE_STRING. @the_str is copied.
258
</para>
259
260
@value: a #GConfValue of type %GCONF_VALUE_STRING.
261
@the_str: the string.
262
263
264
<!-- ##### FUNCTION gconf_value_set_float ##### -->
265
<para>
266
Sets the value of a #GConfValue with type
267
%GCONF_VALUE_FLOAT.
268
</para>
269
270
@value: a #GConfValue of type %GCONF_VALUE_FLOAT.
271
@the_float: the floating point number.
272
273
274
<!-- ##### FUNCTION gconf_value_set_bool ##### -->
275
<para>
276
Sets the value of a #GConfValue with type
277
%GCONF_VALUE_BOOL.
278
</para>
279
280
@value: a #GConfValue of type %GCONF_VALUE_BOOL.
281
@the_bool: a boolean value (<symbol>TRUE</symbol> or <symbol>FALSE</symbol>).
282
283
284
<!-- ##### FUNCTION gconf_value_set_schema ##### -->
285
<para>
286
Sets the value of a #GConfValue with type %GCONF_VALUE_SCHEMA. The
287
#GConfSchema is copied. Alternatively you can use
288
gconf_value_set_schema_nocopy().
289
</para>
290
291
@value: a #GConfValue with type %GCONF_VALUE_SCHEMA.
292
@sc: the #GConfSchema.
293
294
295
<!-- ##### FUNCTION gconf_value_set_schema_nocopy ##### -->
296
<para>
297
Sets the value of a #GConfValue with type
298
%GCONF_VALUE_SCHEMA. The #GConfSchema is <emphasis>not</emphasis>
299
copied; the #GConfValue takes ownership of it, and it should only be
300
accessed via the gconf_value_get_schema() macro. This function is provided
301
as a more efficient version of gconf_value_set_schema().
302
</para>
303
304
@value: a #GConfValue with type %GCONF_VALUE_SCHEMA.
305
@sc: the #GConfSchema.
306
307
308
<!-- ##### FUNCTION gconf_value_set_car ##### -->
309
<para>
310
Sets the value of the first field (car) of a #GConfValue with type
311
%GCONF_VALUE_PAIR. The #GConfValue is copied. Alternatively, use
312
gconf_value_set_car_nocopy().
313
</para>
314
315
@value: a #GConfValue with type %GCONF_VALUE_PAIR.
316
@car: the #GConfValue to set as the car of the pair.
317
318
319
<!-- ##### FUNCTION gconf_value_set_car_nocopy ##### -->
320
<para>
321
Sets the value of the first field (car) of a #GConfValue with type
322
%GCONF_VALUE_PAIR. The #GConfValue is <emphasis>not</emphasis> copied;
323
the #GConfValue takes ownership of it. Alternatively, use
324
gconf_value_set_car().
325
</para>
326
327
@value: a #GConfValue with type %GCONF_VALUE_PAIR.
328
@car: the #GConfValue to set as the car of the pair.
329
330
331
<!-- ##### FUNCTION gconf_value_set_cdr ##### -->
332
<para>
333
Sets the value of the second field (cdr) of a #GConfValue with type
334
%GCONF_VALUE_PAIR. The #GConfValue is copied. Alternatively, use
335
gconf_value_set_cdr_nocopy().
336
</para>
337
338
@value: a #GConfValue with type %GCONF_VALUE_PAIR.
339
@cdr: the #GConfValue to set as the cdr of the pair.
340
341
342
<!-- ##### FUNCTION gconf_value_set_cdr_nocopy ##### -->
343
<para>
344
Sets the value of the second field (cdr) of a #GConfValue with type
345
%GCONF_VALUE_PAIR. The #GConfValue is <emphasis>not</emphasis> copied;
346
the #GConfValue takes ownership of it. Alternatively, use
347
gconf_value_set_cdr().
348
</para>
349
350
@value: a #GConfValue with type %GCONF_VALUE_PAIR.
351
@cdr: the #GConfValue to set as the cdr of the pair.
352
353
354
<!-- ##### FUNCTION gconf_value_set_list_type ##### -->
355
<para>
356
Sets the type of the elements in a #GConfValue of type
357
%GCONF_VALUE_LIST. All the elements in the list must have the same
358
type. You must set the list type before you can set the list value.
359
</para>
360
361
@value: a #GConfValue with type %GCONF_VALUE_LIST.
362
@type: the type of elements in this list.
363
364
365
<!-- ##### FUNCTION gconf_value_set_list_nocopy ##### -->
366
<para>
367
Sets the value of a #GConfValue with type %GCONF_VALUE_LIST. The
368
@list argument should be a #GSList of #GConfValue. Each #GConfValue in
369
the list must have the same type, and this type must be specified in
370
advance with gconf_value_set_list_type(). This function does
371
<emphasis>not</emphasis> copy the list; the #GConfValue will take
372
ownership of the list and its contents, and they will be destroyed
373
when the #GConfValue is destroyed. Alternatively, use
374
gconf_value_set_list() to make a copy.
375
</para>
376
377
@value: a #GConfValue with type %GCONF_VALUE_LIST.
378
@list: the #GSList of #GConfValue to set as the list value.
379
380
381
<!-- ##### FUNCTION gconf_value_set_list ##### -->
382
<para>
383
Sets the value of a #GConfValue with type %GCONF_VALUE_LIST. The
384
@list argument should be a #GSList of #GConfValue. Each #GConfValue in
385
the list must have the same type, and this type must be specified in
386
advance with gconf_value_set_list_type(). This function copies the
387
list; it will not modify the @list argument.
388
</para>
389
390
@value: a #GConfValue with type %GCONF_VALUE_LIST.
391
@list: the #GSList of #GConfValue to set as the list value.
392
393
394
<!-- ##### FUNCTION gconf_value_to_string ##### -->
395
<para>
396
Creates a human-readable string representation of a #GConfValue. This
397
is intended for debugging and the like; the string representation is
398
not suitable for reliable machine parsing (that is, you shouldn't use
399
this function to save a value to a file or anything like that). The
400
exact nature of the string representation may change in future
401
versions. The returned string is newly-allocated and must be freed
402
with g_free().
403
</para>
404
405
@value: a #GConfValue.
406
@Returns: a newly-allocated string representing the #GConfValue.
407
408
409
<!-- ##### STRUCT GConfMetaInfo ##### -->
410
<para>
411
412
</para>
413
414
@schema:
415
@mod_user:
416
@mod_time:
417
418
<!-- ##### FUNCTION gconf_meta_info_new ##### -->
419
<para>
420
Creates a new #GConfMetaInfo structure and returns the newly allocated
421
#GConfMetaInfo.
422
</para>
423
424
@void:
425
@Returns: the newly allocated #GConfMetainfo.
426
427
428
<!-- ##### FUNCTION gconf_meta_info_free ##### -->
429
<para>
430
Frees the #GConfMetaInfo.
431
</para>
432
433
@gcmi: the #GConfMetaInfo to be freed.
434
435
436
<!-- ##### FUNCTION gconf_meta_info_get_schema ##### -->
437
<para>
438
Returns the schema field of the #GConfMetaInfo.
439
</para>
440
441
@gcmi: a #GConfMetaInfo.
442
@Returns: the schema field, a char* value.
443
444
445
<!-- ##### FUNCTION gconf_meta_info_get_mod_user ##### -->
446
<para>
447
Returns the user owning the daemon that made the last modification of the key.
448
</para>
449
450
@gcmi: a #GConfMetaInfo.
451
@Returns: mod_user, a char* value.
452
453
454
<!-- ##### FUNCTION gconf_meta_info_mod_time ##### -->
455
<para>
456
Returns the last modification time of the key.
457
</para>
458
459
@gcmi: a #GConfMetaInfo.
460
@Returns: the mod_time, a #GTime value.
461
462
463
<!-- ##### FUNCTION gconf_meta_info_set_schema ##### -->
464
<para>
465
Sets the schema_name field of the #GConfMetaInfo to the name passed.
466
</para>
467
468
@gcmi: a #GConfMetaInfo.
469
@schema_name: the name to be set for the schema, a gchar* value.
470
471
472
<!-- ##### FUNCTION gconf_meta_info_set_mod_user ##### -->
473
<para>
474
Sets the mod_user field of the #GConfMetaInfo to the user name passed.
475
</para>
476
477
@gcmi: a #GConfMetaInfo.
478
@mod_user: the value to be set, a char*.
479
480
481
<!-- ##### FUNCTION gconf_meta_info_set_mod_time ##### -->
482
<para>
483
Sets the mod_last field of the #GConfMetaInfo to the mod_time passed.
484
</para>
485
486
@gcmi: a #GConfMetaInfo.
487
@mod_time: a #GTime.
488
489
490
<!-- ##### STRUCT GConfEntry ##### -->
491
<para>
492
Stores an entry from a GConf "directory," including a key-value pair,
493
the name of the schema applicable to this entry, whether the value is
494
a default value, and whether GConf can write a new value at this
495
key. @key should be an absolute key, not a relative key. (Note that
496
internally GConf breaks this rule sometimes; but in the public
497
interface, @key is always an absolute key.) To access the key and
498
value, use gconf_entry_get_key() and gconf_entry_get_value().
499
</para>
500
501
<warning><para>Value can be <symbol>NULL</symbol>, indicating that the
502
value is not set.</para></warning>
503
504
@key: an absolute key name.
505
@value: the value.
506
507
<!-- ##### FUNCTION gconf_entry_get_key ##### -->
508
<para>
509
Accesses the @key field of a #GConfEntry. The returned key is not a
510
copy, and should not be freed or modified.
511
</para>
512
513
@entry: a #GConfEntry.
514
@Returns: the key , a char*.
515
516
517
<!-- ##### FUNCTION gconf_entry_get_value ##### -->
518
<para>
519
Accesses the @value field of a #GConfEntry. The returned value is not
520
a copy, and should not be freed or modified. If you have called
521
gconf_entry_steal_value(), the returned value will be
522
<symbol>NULL</symbol>.
523
</para>
524
525
@entry: a #GConfEntry.
526
@Returns: a #GConfValue.
527
528
529
<!-- ##### FUNCTION gconf_entry_get_schema_name ##### -->
530
<para>
531
Returns the schema_name field of the #GConfEntry.
532
</para>
533
534
@entry: a #GConfEntry.
535
@Returns: the schema_name , a char* value.
536
537
538
<!-- ##### FUNCTION gconf_entry_get_is_default ##### -->
539
<para>
540
Returns the is_default field of the #GConfEntry , a gboolean value.
541
</para>
542
543
@entry: a #GConfEntry.
544
@Returns: a #gboolean value.
545
546
547
<!-- ##### FUNCTION gconf_entry_get_is_writable ##### -->
548
<para>
549
Returns the is_writable field of the #GConfEntry, a gboolean value.
550
</para>
551
552
@entry: a #GConfEntry.
553
@Returns: a #gboolean value.
554
555
556
<!-- ##### FUNCTION gconf_entry_new ##### -->
557
<para>
558
Creates a new #GConfEntry with key @key and value @val calling gconf_entry_new_nocopy ().
559
</para>
560
561
@key: the key name.
562
@val: the value.
563
@Returns: a new #GConfEntry.
564
565
566
<!-- ##### FUNCTION gconf_entry_new_nocopy ##### -->
567
<para>
568
Creates a new #GConfEntry with key @key and value @val. @key should be a full
569
path to the key, starting with '/'. Neither the key nor the value is copied;
570
both are freed when the #GConfEntry is freed. The string will be freed with
571
g_free() so should be allocated with a GLib function, not malloc().
572
</para>
573
574
@key: the key name.
575
@val: the value.
576
@Returns: a new #GConfEntry.
577
578
579
<!-- ##### FUNCTION gconf_entry_copy ##### -->
580
<para>
581
Copies the fields of an existing #GConfEntry and returns the new #GConfEntry.
582
</para>
583
584
@src: the #GConfEntry to be copied.
585
@Returns: the new #GConfEntry.
586
587
588
<!-- ##### FUNCTION gconf_entry_free ##### -->
589
<para>
590
Destroys a #GConfEntry, freeing the key, the value, and the entry itself.
591
</para>
592
593
@entry: a #GConfEntry to free.
594
595
596
<!-- ##### FUNCTION gconf_entry_ref ##### -->
597
<para>
598
Increases the refcount of a #GConfEntry by one.
599
</para>
600
601
@entry: a #GConfEntry.
602
@Returns: the referenced #GConfEntry.
603
604
605
<!-- ##### FUNCTION gconf_entry_unref ##### -->
606
<para>
607
Decreases the refcount of a #GConfEntry by one and frees the
608
#GConfEntry when the refcount becomes zero.
609
</para>
610
611
@entry: a #GConfEntry.
612
613
614
<!-- ##### FUNCTION gconf_entry_steal_value ##### -->
615
<para>
616
Extracts the value from a #GConfEntry, leaving the @value field in
617
#GConfEntry set to <symbol>NULL</symbol>. Destroying the #GConfEntry
618
will <emphasis>not</emphasis> destroy the value; the caller of
619
gconf_entry_steal_value() assumes ownership of it.
620
</para>
621
622
@entry: a #GConfEntry.
623
@Returns: a #GConfValue that the caller must free.
624
625
626
<!-- ##### FUNCTION gconf_entry_set_value ##### -->
627
<para>
628
Sets the value field of the #GConfEntry to the #GConfValue passed.
629
</para>
630
631
@entry: a #GConfEntry.
632
@val: a #GConfValue.
633
634
635
<!-- ##### FUNCTION gconf_entry_set_value_nocopy ##### -->
636
<para>
637
Sets the value field to @val after freeing the already existing value.
638
</para>
639
640
@entry: a #GConfEntry.
641
@val: the #GConfValue to be set.
642
643
644
<!-- ##### FUNCTION gconf_entry_set_schema_name ##### -->
645
<para>
646
Sets the schema_name field of the #GConfEntry to the name passed after freeing
647
the already existing name.
648
</para>
649
650
@entry: a #GConfEntry.
651
@name: the name to be set for the schema, a gchar* value.
652
653
654
<!-- ##### FUNCTION gconf_entry_set_is_default ##### -->
655
<para>
656
Sets the is_default field of the #GConfEntry to the boolean value passed.
657
</para>
658
659
@entry: a #GConfEntry.
660
@is_default: the boolean value to be set.
661
662
663
<!-- ##### FUNCTION gconf_entry_set_is_writable ##### -->
664
<para>
665
Sets the is_writable field of the #GConfEntry to the boolean value passed.
666
</para>
667
668
@entry: a #GConfEntry.
669
@is_writable: a boolean value.
670
671
Loggerhead is a web-based interface for Breezy
Version: 2.0.1