Gnome2::GConf::Client(User Contributed Perl DocumentatGnome2::GConf::Client(3)NAMEGnome2::GConf::ClientDESCRIPTIONGnome2::GConf::Client is a commodity class based on "GObject" used to
access the default "GConfEngine" provided by the GConf daemon. It has
a cache, finer-grained notification of changes and a default error
handling mechanism.
ERROR HANDLING
In C, each fallible function has a "GError" optional argument: by
setting it to a valid "GError" structure, the function will fill it in
case of error; by passing a NULL value, the function will silently
fail.
In Perl, each fallible method has a boolean "check_error" argument; by
setting this argument to "TRUE", the method will croak con failure,
otherwise it will silently fail.
NOTE: To retain backward compatibility, the default behaviour is to
check each error; that is, the "check_error" argument silently is set
to TRUE.
In order to catch an error, you might use eval as a try...catch
equivalent:
eval { $s = $client->get_string($some_key); 1; };
if (Glib::Error::matches($@, 'Gnome2::GConf::Error', 'bad-key'))
{
# recover from a bad-key error.
}
On failure, if the error is unchecked, the "unreturned_error" signal
will be fired by the Gnome2::GConf::Client object; the "error" signal
will always be fired, whether the error is checked or not.
If you want to let the global error handler function catch just the
unchecked error, use the "Gnome2::GConf::Client::set_error_handling"
method, and attach a callback to the "unreturned_error" signal:
$client->set_error_handling('handle-unreturned');
$client->signal_connect(unreturned_error => sub {
my ($client, $error) = @_;
warn $error; # is a Glib::Error
});
HIERARCHY
Glib::Object
+----Gnome2::GConf::Client
METHODS
$client->add_dir ($dir, $preload, $check_error=TRUE)
· $dir (string)
· $preload (Gnome2::GConf::ClientPreloadType)
· $check_error (boolean)
list = $client->all_dirs($dir, $check_error=TRUE)
· $dir (string)
· $check_error (boolean)
This method returns an array containing all the directories in a given
directory.
list = $client->all_entries($dir, $check_error=TRUE)
· $dir (string)
· $check_error (boolean)
This method returns an array containing all the entries (as
Gnome2::GConf::Entry) of a given directory.
boolean = $client->get_bool ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
boolean = $client->set_bool ($key, $val, $check_error=TRUE)
· $key (string)
· $val (boolean)
· $check_error (boolean)
Returns FALSE on failure.
changeset = $client->change_set_from_current ($check_error=TRUE, $key, ...)
· $check_error (boolean)
· ... (list) list of keys to add to the changeset
Create a Gnome2::GConf::ChangeSet from a list of keys inside the GConf
database.
$client->clear_cache
boolean = $client->commit_change_set ($cs, $remove_committed,
$check_error=TRUE)
(boolean, changeset) = $client->commit_change_set ($cs, $remove_committed,
$check_error=TRUE)
· $cs (changeset)
· $remove_committed (boolean)
· $check_error (boolean)
Commit a given Gnome2::GConf::ChangeSet. In scalar context, or if
$remove_committed is FALSE, return a boolean value; otherwise, return
the boolean value and the Gnome2::GConf::ChangeSet $cs, pruned of the
successfully committed changes.
value = $client->get_default_from_schema ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
client = Gnome2::GConf::Client->get_default
boolean = $client->dir_exists ($dir, $check_error=TRUE)
· $dir (string)
· $check_error (boolean)
entry = $client->get_entry ($key, $locale, $use_schema_default,
$check_error=TRUE)
· $key (string)
· $locale (string)
· $use_schema_default (boolean)
· $check_error (boolean)
list = $client->error ($error)
· $error (scalar) a Glib::Error
You should not use this method. This method emits the "error" signal.
$client->set_error_handling ($mode)
· $mode (Gnome2::GConf::ClientErrorHandlingMode)
double = $client->get_float ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
boolean = $client->set_float ($key, $val, $check_error=TRUE)
· $key (string)
· $val (double)
· $check_error (boolean)
Returns FALSE on failure.
client = Gnome2::GConf::Client->get_for_engine ($engine)
· $engine (engine)
value = $client->get ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
Fetch the "GConfValue" bound to the give $key.
$client->set ($key, $value, $check_error=TRUE)
· $key (string)
· $value (value)
· $check_error (boolean)
Set the "GConfValue" $val bound to the given $key.
integer = $client->get_int ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
boolean = $client->set_int ($key, $val, $check_error=TRUE)
· $key (string)
· $val (integer)
· $check_error (boolean)
Returns FALSE on failure.
boolean = $client->key_is_writable ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
$client->get_list ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
boolean = $client->set_list ($key, $list_type, $list, $check_error=TRUE)
· $key (string)
· $list_type (string)
· $list (scalar)
· $check_error (boolean)
integer = $client->notify_add ($namespace_section, $func, $data=undef,
$check_error=TRUE)
· $namespace_section (string)
· $func (scalar)
· $data (scalar)
· $check_error (boolean)
$client->notify_remove ($cnxn_id)
· $cnxn_id (integer)
$client->get_pair ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
boolean = $client->set_pair ($key, $car, $cdr, $check_error=TRUE)
· $key (string)
· $car (value)
· $cdr (value)
· $check_error (boolean)
$client->preload ($dirname, $type, $check_error=TRUE)
· $dirname (string)
· $type (Gnome2::GConf::ClientPreloadType)
· $check_error (boolean)
boolean = $client->recursive_unset ($key, $flags=0, $check_error=TRUE)
· $key (string)
· $flags (Gnome2::GConf::UnsetFlags)
· $check_error (boolean)
Since: gconf 2.3
$client->remove_dir ($dir, $check_error=TRUE)
· $dir (string)
· $check_error (boolean)
changeset = $client->reverse_change_set ($cs, $check_error=TRUE)
· $cs (changeset)
· $check_error (boolean)
Reverse the given Gnome2::GConf::ChangeSet.
schema = $client->get_schema ($key)
· $key (string)
boolean = $client->set_schema ($key, $schema, $check_error=TRUE)
· $key (string)
· $schema (schema)
· $check_error (boolean)
client = Gnome2::GConf::Client->get_source ($config_source,
$use_local_source)
· $config_source (string)
· $use_local_source (boolean)
string = $client->get_string ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
boolean = $client->set_string ($key, $val, $check_error=TRUE)
· $key (string)
· $val (string)
· $check_error (boolean)
Returns FALSE on failure
$client->suggest_sync ($check_error=TRUE)
· $check_error (boolean)
list = $client->unreturned_error ($error)
· $error (scalar) a Glib::Error
You should not use this method. This method emits the "unreturned-
error" signal.
boolean = $client->unset ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
list = $client->value_changed ($key, $value)
· $key (string)
· $value (value)
You should not use this method. This method emits the "value-changed"
signal.
value = $client->get_without_default ($key, $check_error=TRUE)
· $key (string)
· $check_error (boolean)
SIGNALS
value-changed (Gnome2::GConf::Client, string, gpointer)
unreturned-error (Gnome2::GConf::Client, gpointer)
error (Gnome2::GConf::Client, gpointer)
ENUMS AND FLAGS
enum Gnome2::GConf::ClientErrorHandlingMode
· 'handle-none' / 'GCONF_CLIENT_HANDLE_NONE'
· 'handle-unreturned' / 'GCONF_CLIENT_HANDLE_UNRETURNED'
· 'handle-all' / 'GCONF_CLIENT_HANDLE_ALL'
enum Gnome2::GConf::ClientPreloadType
· 'preload-none' / 'GCONF_CLIENT_PRELOAD_NONE'
· 'preload-onelevel' / 'GCONF_CLIENT_PRELOAD_ONELEVEL'
· 'preload-recursive' / 'GCONF_CLIENT_PRELOAD_RECURSIVE'
flags Gnome2::GConf::UnsetFlags
· 'names' / 'GCONF_UNSET_INCLUDING_SCHEMA_NAMES'
SEE ALSO
Gnome2::GConf, Glib::Object
COPYRIGHT
Copyright (C) 2003-2006 by the gtk2-perl team.
This software is licensed under the LGPL. See Gnome2::GConf for a full
notice.
perl v5.10.1 2010-03-07 Gnome2::GConf::Client(3)
