← Back to branch summary

~ubuntu-branches/ubuntu/quantal/gconf/quantal

« back to all changes in this revision

Viewing changes to doc/gconf/tmpl/gconf-client.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Emilio Pozuelo Monfort, Josselin Mouette, Sjoerd Simons, Emilio Pozuelo Monfort
  • Date: 2010-12-06 00:53:14 UTC
  • mfrom: (1.1.25 upstream)
  • mto: (7.3.4 sid)
  • mto: This revision was merged to the branch mainline in revision 58.
  • Revision ID: james.westby@ubuntu.com-20101206005314-uz89yke6r1xfw504
Tags: 2.32.1-1
http://bugs.debian.org/599032
http://bugs.debian.org/599049
http://bugs.debian.org/599125
http://bugs.debian.org/599198
http://bugs.debian.org/599393
http://bugs.debian.org/599683
http://bugs.debian.org/599854
http://bugs.debian.org/600899
[ Josselin Mouette ]
* Include patch-translations.mk, bump build-depends accordingly.
* Include 03_error_message.patch in POTFILES.in.
* pt_BR.po: Brazilian Portuguese translation. Closes: #599032.
* fr.po: French translation by Christian Perrier. Closes: #599049.
* da.po: Danish translation by Joe Hansen. Closes: #599125.
* cs.po: Czech translation by Michal Simunek. Closes: #599198.
* update-gconf-defaults: patch from Ubuntu to deal with broken 
  symlinks. Closes: #599393. Thanks Michael Vogt.
* de.po: German translation by Helge Kreutzmann. Closes: #599683.
* sv.po: Swedish translation by Martin Bagge. Closes: #599854.
* 04_manpage.patch: patch from A. Costa. Fixes typos in the manual 
  page. Closes: #600899.

[ Sjoerd Simons ]
* New upstream release
* Bump gobject-introspection to the lastest version to generate the most
  recent .gir version
* debian/patches/03_error_message.patch
  + Removed, merged upstream
* debian/rules:
  + Specify compilation with gtk2

[ Emilio Pozuelo Monfort ]
* Switch to source format 3.0 (quilt).
* debian/patches/*:
  - Updated to apply cleanly.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/gconf/tmpl/gconf-client.sgml
191
191
 
192
192
<!-- ##### FUNCTION gconf_client_get_default ##### -->
193
193
<para>
194
 
Creates a new #GConfClient using the default #GConfEngine. Normally this is the
195
 
engine you want. If someone else is already using the default
196
 
#GConfClient, this function returns the same one they're using, but 
197
 
with the reference count incremented. So you have to unref either way.
198
 
</para>
199
194
 
200
 
<para>
201
 
It's important to call g_type_init() before using this GObject, to initialize the type system.
202
195
</para>
203
196
 
204
197
@void: 
205
 
@Returns: a new #GConfClient. g_object_unref() when you're done.
 
198
@Returns: 
206
199
 
207
200
 
208
201
<!-- ##### FUNCTION gconf_client_get_for_engine ##### -->
209
202
<para>
210
 
Creates a new #GConfClient with a specific #GConfEngine. Only specialized
211
 
configuration-related programs should need to call this function. The
212
 
returned #GConfClient should be unref'd when you're done with g_object_unref().
213
 
Remember to avoid using the #GConfEngine directly once you have a #GConfClient
214
 
wrapper.
 
203
 
215
204
</para>
216
205
 
217
 
@engine: the #GConfEngine to use.
218
 
@Returns: a new #GConfClient.
 
206
@engine: 
 
207
@Returns: 
219
208
 
220
209
 
221
210
<!-- ##### FUNCTION gconf_client_add_dir ##### -->
329
318
 
330
319
<!-- ##### FUNCTION gconf_client_set_global_default_error_handler ##### -->
331
320
<para>
332
 
Set @func as the default error handler for the #GConfClient. This handler would be called
333
 
for all #GConfClient internal errors.
 
321
 
334
322
</para>
335
323
 
336
 
@func: pointer to the function to be called for error handling.
 
324
@func: 
337
325
 
338
326
 
339
327
<!-- ##### FUNCTION gconf_client_clear_cache ##### -->
456
444
 
457
445
<!-- ##### FUNCTION gconf_client_all_entries ##### -->
458
446
<para>
459
 
Lists the key-value pairs in @dir. Does not list subdirectories; for
460
 
that use gconf_client_all_dirs(). The returned list contains #GConfEntry
461
 
objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key
462
 
and a value. The list is not recursive, it contains only the immediate
463
 
children of @dir.  To free the returned list, gconf_entry_free()
464
 
each list element, then g_slist_free() the list itself.
465
 
Just like gconf_engine_all_entries (), but uses #GConfClient caching and error-handling features.
 
447
 
466
448
</para>
467
449
 
468
 
@client: a #GConfClient.
469
 
@dir: directory to list.
470
 
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
471
 
@Returns: List of #GConfEntry.
 
450
@client: 
 
451
@dir: 
 
452
@err: 
 
453
@Returns: 
472
454
 
473
455
 
474
456
<!-- ##### FUNCTION gconf_client_all_dirs ##### -->
475
457
<para>
476
 
Lists the subdirectories in @dir. The returned list contains allocated
477
 
strings. Each string is the absolute path of a subdirectory. You should g_free() each string in the list, then g_slist_free() the list itself.
478
 
Just like gconf_engine_all_dirs (), but uses #GConfClient caching and error-handling features.
 
458
 
479
459
</para>
480
460
 
481
 
@client: a #GConfClient.
482
 
@dir: directory to get subdirectories from.
483
 
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
484
 
@Returns: List of allocated subdirectory names.
 
461
@client: 
 
462
@dir: 
 
463
@err: 
 
464
@Returns: 
485
465
 
486
466
 
487
467
<!-- ##### FUNCTION gconf_client_suggest_sync ##### -->
601
581
 
602
582
<!-- ##### FUNCTION gconf_client_get_list ##### -->
603
583
<para>
604
 
Requests the list (%GCONF_VALUE_LIST) stored at @key.  Automatically
605
 
performs type-checking, so if a non-list is stored at @key, or the
606
 
list does not contain elements of type @list_type, an error is
607
 
returned. If no value is set or an error occurs, <symbol>NULL</symbol>
608
 
is returned. Note that <symbol>NULL</symbol> is also the empty list,
609
 
so if you need to distinguish the empty list from an unset value, you
610
 
must use gconf_client_get () to obtain a raw #GConfValue.
611
 
</para>
612
 
 
613
 
<para>
614
 
<emphasis>Remember that GConf lists can only store primitive types:
615
 
%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
616
 
%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember
617
 
that lists must be uniform, you may not mix types in the same list.
618
 
</para>
619
 
 
620
 
<para>
621
 
The type of the list elements depends on @list_type. A #GConfValue
622
 
with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue
623
 
objects. gconf_client_get_list() automatically converts to primitive C
624
 
types. Thus, the list-&gt;data fields in the returned list 
625
 
contain:
626
 
 
627
 
<informaltable pgwide="1" frame="none">
628
 
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
629
 
<tbody>
630
 
 
631
 
<row>
632
 
<entry>%GCONF_VALUE_INT</entry>
633
 
<entry>The integer itself, converted with GINT_TO_POINTER()</entry>
634
 
</row>
635
 
 
636
 
<row>
637
 
<entry>%GCONF_VALUE_BOOL</entry>
638
 
<entry>The bool itself, converted with GINT_TO_POINTER()</entry>
639
 
</row>
640
 
 
641
 
<row>
642
 
<entry>%GCONF_VALUE_FLOAT</entry>
643
 
<entry>A pointer to #gdouble, which should be freed with g_free()</entry>
644
 
</row>
645
 
 
646
 
<row>
647
 
<entry>%GCONF_VALUE_STRING</entry>
648
 
<entry>A pointer to #gchar, which should be freed with g_free()</entry>
649
 
</row>
650
 
 
651
 
<row>
652
 
<entry>%GCONF_VALUE_SCHEMA</entry>
653
 
<entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry>
654
 
</row>
655
 
 
656
 
</tbody></tgroup></informaltable>
657
 
 
658
 
In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must
659
 
g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must
660
 
gconf_schema_free() each element. In all cases you must free the
661
 
list itself with g_slist_free().
662
 
 
663
 
Just like gconf_engine_get_list (), but uses #GConfClient caching and error-handling features.
664
 
</para>
665
 
 
666
 
@client: a #GConfClient.
667
 
@key: key you want the value of.
668
 
@list_type: type of each list element.
669
 
@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
670
 
@Returns: an allocated list, with elements as described above.
 
584
 
 
585
</para>
 
586
 
 
587
@client: 
 
588
@key: 
 
589
@list_type: 
 
590
@err: 
 
591
@Returns: 
671
592
 
672
593
 
673
594
<!-- ##### FUNCTION gconf_client_get_pair ##### -->