Gnome2::GConf::Client(3pm)

1Gnome2::GConf::Client(3U)ser Contributed Perl DocumentatiGonnome2::GConf::Client(3)
2
3
4

NAME

6       Gnome2::GConf::Client
7

DESCRIPTION

9       Gnome2::GConf::Client is a commodity class based on "GObject" used to
10       access the default "GConfEngine" provided by the GConf daemon.  It has
11       a cache, finer-grained notification of changes and a default error han‐
12       dling mechanism.
13

ERROR HANDLING

15       In C, each fallible function has a "GError" optional argument: by set‐
16       ting it to a valid "GError" structure, the function will fill it in
17       case of error; by passing a NULL value, the function will silently
18       fail.
19
20       In Perl, each fallible method has a boolean "check_error" argument; by
21       setting this argument to "TRUE", the method will croak con failure,
22       otherwise it will silently fail.
23
24       NOTE: To retain backward compatibility, the default behaviour is to
25       check each error; that is, the "check_error" argument silently is set
26       to TRUE.
27
28       In order to catch an error, you might use eval as a try...catch equiva‐
29       lent:
30
31         eval { $s = $client->get_string($some_key); 1; };
32         if (Glib::Error::matches($@, 'Gnome2::GConf::Error', 'bad-key'))
33         {
34           # recover from a bad-key error.
35         }
36
37       On failure, if the error is unchecked, the "unreturned_error" signal
38       will be fired by the Gnome2::GConf::Client object; the "error" signal
39       will always be fired, whether the error is checked or not.
40
41       If you want to let the global error handler function catch just the
42       unchecked error, use the "Gnome2::GConf::Client::set_error_handling"
43       method, and attach a callback to the "unreturned_error" signal:
44
45         $client->set_error_handling('handle-unreturned');
46         $client->signal_connect(unreturned_error => sub {
47             my ($client, $error) = @_;
48             warn $error; # is a Glib::Error
49           });
50

HIERARCHY

52         Glib::Object
53         +----Gnome2::GConf::Client
54

METHODS

56       $client->add_dir ($dir, $preload, $check_error=TRUE)
57
58           * $dir (string)
59           * $preload (Gnome2::GConf::ClientPreloadType)
60           * $check_error (boolean)
61
62       list = $client->all_dirs($dir, $check_error=TRUE)
63
64           * $dir (string)
65           * $check_error (boolean)
66
67           This method returns an array containing all the directories in a
68           given directory.
69
70       list = $client->all_entries($dir, $check_error=TRUE)
71
72           * $dir (string)
73           * $check_error (boolean)
74
75           This method returns an array containing all the entries (as
76           Gnome2::GConf::Entry) of a given directory.
77
78       boolean = $client->get_bool ($key, $check_error=TRUE)
79
80           * $key (string)
81           * $check_error (boolean)
82
83       boolean = $client->set_bool ($key, $val, $check_error=TRUE)
84
85           * $key (string)
86           * $val (boolean)
87           * $check_error (boolean)
88
89           Returns FALSE on failure.
90
91       changeset = $client->change_set_from_current ($check_error=TRUE, $key,
92       ...)
93
94           * $check_error (boolean)
95           * ... (list) list of keys to add to the changeset
96
97           Create a Gnome2::GConf::ChangeSet from a list of keys inside the
98           GConf database.
99
100       $client->clear_cache
101
102       boolean = $client->commit_change_set ($cs, $remove_committed,
103       $check_error=TRUE)
104
105       (boolean, changeset) = $client->commit_change_set ($cs, $remove_commit‐
106       ted, $check_error=TRUE)
107
108           * $cs (changeset)
109           * $remove_committed (boolean)
110           * $check_error (boolean)
111
112           Commit a given Gnome2::GConf::ChangeSet.  In scalar context, or if
113           $remove_committed is FALSE, return a boolean value; otherwise,
114           return the boolean value and the Gnome2::GConf::ChangeSet $cs,
115           pruned of the successfully committed changes.
116
117       value = $client->get_default_from_schema ($key, $check_error=TRUE)
118
119           * $key (string)
120           * $check_error (boolean)
121
122       client = Gnome2::GConf::Client->get_default
123
124       boolean = $client->dir_exists ($dir, $check_error=TRUE)
125
126           * $dir (string)
127           * $check_error (boolean)
128
129       entry = $client->get_entry ($key, $locale, $use_schema_default,
130       $check_error=TRUE)
131
132           * $key (string)
133           * $locale (string)
134           * $use_schema_default (boolean)
135           * $check_error (boolean)
136
137       list = $client->error ($error)
138
139           * $error (scalar) a Glib::Error
140
141           You should not use this method.  This method emits the "error" sig‐
142           nal.
143
144       $client->set_error_handling ($mode)
145
146           * $mode (Gnome2::GConf::ClientErrorHandlingMode)
147
148       double = $client->get_float ($key, $check_error=TRUE)
149
150           * $key (string)
151           * $check_error (boolean)
152
153       boolean = $client->set_float ($key, $val, $check_error=TRUE)
154
155           * $key (string)
156           * $val (double)
157           * $check_error (boolean)
158
159           Returns FALSE on failure.
160
161       client = Gnome2::GConf::Client->get_for_engine ($engine)
162
163           * $engine (engine)
164
165       value = $client->get ($key, $check_error=TRUE)
166
167           * $key (string)
168           * $check_error (boolean)
169
170           Fetch the "GConfValue" bound to the give $key.
171
172       $client->set ($key, $value, $check_error=TRUE)
173
174           * $key (string)
175           * $value (value)
176           * $check_error (boolean)
177
178           Set the "GConfValue" $val bound to the given $key.
179
180       integer = $client->get_int ($key, $check_error=TRUE)
181
182           * $key (string)
183           * $check_error (boolean)
184
185       boolean = $client->set_int ($key, $val, $check_error=TRUE)
186
187           * $key (string)
188           * $val (integer)
189           * $check_error (boolean)
190
191           Returns FALSE on failure.
192
193       boolean = $client->key_is_writable ($key, $check_error=TRUE)
194
195           * $key (string)
196           * $check_error (boolean)
197
198       $client->get_list ($key, $check_error=TRUE)
199
200           * $key (string)
201           * $check_error (boolean)
202
203       boolean = $client->set_list ($key, $list_type, $list,
204       $check_error=TRUE)
205
206           * $key (string)
207           * $list_type (string)
208           * $list (scalar)
209           * $check_error (boolean)
210
211       integer = $client->notify_add ($namespace_section, $func, $data=undef,
212       $check_error=TRUE)
213
214           * $namespace_section (string)
215           * $func (scalar)
216           * $data (scalar)
217           * $check_error (boolean)
218
219       $client->notify_remove ($cnxn_id)
220
221           * $cnxn_id (integer)
222
223       $client->get_pair ($key, $check_error=TRUE)
224
225           * $key (string)
226           * $check_error (boolean)
227
228       boolean = $client->set_pair ($key, $car, $cdr, $check_error=TRUE)
229
230           * $key (string)
231           * $car (value)
232           * $cdr (value)
233           * $check_error (boolean)
234
235       $client->preload ($dirname, $type, $check_error=TRUE)
236
237           * $dirname (string)
238           * $type (Gnome2::GConf::ClientPreloadType)
239           * $check_error (boolean)
240
241       boolean = $client->recursive_unset ($key, $flags=0, $check_error=TRUE)
242
243           * $key (string)
244           * $flags (Gnome2::GConf::UnsetFlags)
245           * $check_error (boolean)
246
247       $client->remove_dir ($dir, $check_error=TRUE)
248
249           * $dir (string)
250           * $check_error (boolean)
251
252       changeset = $client->reverse_change_set ($cs, $check_error=TRUE)
253
254           * $cs (changeset)
255           * $check_error (boolean)
256
257           Reverse the given Gnome2::GConf::ChangeSet.
258
259       schema = $client->get_schema ($key)
260
261           * $key (string)
262
263       boolean = $client->set_schema ($key, $schema, $check_error=TRUE)
264
265           * $key (string)
266           * $schema (schema)
267           * $check_error (boolean)
268
269       string = $client->get_string ($key, $check_error=TRUE)
270
271           * $key (string)
272           * $check_error (boolean)
273
274       boolean = $client->set_string ($key, $val, $check_error=TRUE)
275
276           * $key (string)
277           * $val (string)
278           * $check_error (boolean)
279
280           Returns FALSE on failure
281
282       $client->suggest_sync ($check_error=TRUE)
283
284           * $check_error (boolean)
285
286       list = $client->unreturned_error ($error)
287
288           * $error (scalar) a Glib::Error
289
290           You should not use this method.  This method emits the "unre‐
291           turned-error" signal.
292
293       boolean = $client->unset ($key, $check_error=TRUE)
294
295           * $key (string)
296           * $check_error (boolean)
297
298       list = $client->value_changed ($key, $value)
299
300           * $key (string)
301           * $value (value)
302
303           You should not use this method.  This method emits the
304           "value-changed" signal.
305
306       value = $client->get_without_default ($key, $check_error=TRUE)
307
308           * $key (string)
309           * $check_error (boolean)
310

SIGNALS

312       value-changed (Gnome2::GConf::Client, string, gpointer)
313       unreturned-error (Gnome2::GConf::Client, gpointer)
314       error (Gnome2::GConf::Client, gpointer)
315

ENUMS AND FLAGS

317       enum Gnome2::GConf::ClientErrorHandlingMode
318
319       * 'handle-none' / 'GCONF_CLIENT_HANDLE_NONE'
320       * 'handle-unreturned' / 'GCONF_CLIENT_HANDLE_UNRETURNED'
321       * 'handle-all' / 'GCONF_CLIENT_HANDLE_ALL'
322
323       enum Gnome2::GConf::ClientPreloadType
324
325       * 'preload-none' / 'GCONF_CLIENT_PRELOAD_NONE'
326       * 'preload-onelevel' / 'GCONF_CLIENT_PRELOAD_ONELEVEL'
327       * 'preload-recursive' / 'GCONF_CLIENT_PRELOAD_RECURSIVE'
328
329       flags Gnome2::GConf::UnsetFlags
330
331       * 'names' / 'GCONF_UNSET_INCLUDING_SCHEMA_NAMES'
332

COPYRIGHT

337       Copyright (C) 2003-2006 by the gtk2-perl team.
338
339       This software is licensed under the LGPL.  See Gnome2::GConf for a full
340       notice.
341
342
343
344perl v5.8.8                       2007-10-24          Gnome2::GConf::Client(3)