libgnome2-gconf-perl 1.044-4build1 / usr / lib / perl5 / Gnome2 / GConf / Client.pod

=head1 NAME

Gnome2::GConf::Client -  client module for GConf

=cut

=for position DESCRIPTION

=head1 DESCRIPTION

Gnome2::GConf::Client is a commodity class based on C<GObject> used to access
the default C<GConfEngine> provided by the GConf daemon.  It has a cache,
finer-grained notification of changes and a default error handling mechanism.

=head1 ERROR HANDLING

In C, each fallible function has a C<GError> optional argument: by setting it
to a valid C<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 C<check_error> argument; by setting
this argument to C<TRUE>, the method will croak con failure, otherwise it will
silently fail.

B<NOTE>: To retain backward compatibility, the default behaviour is to check
each error; that is, the C<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 C<unreturned_error> signal will be
fired by the Gnome2::GConf::Client object; the C<error> signal will B<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 C<Gnome2::GConf::Client::set_error_handling> method, and attach
a callback to the C<unreturned_error> signal:

  $client->set_error_handling('handle-unreturned');
  $client->signal_connect(unreturned_error => sub {
      my ($client, $error) = @_;
      warn $error; # is a Glib::Error
    });

=cut



=head1 HIERARCHY

  Glib::Object
  +----Gnome2::GConf::Client



=cut

=for object Gnome2::GConf::Client client module for GConf

=cut

=for apidoc
=for signature list = $client->get_list($key, $check_error=TRUE)
=cut

=for apidoc
=for signature (car, cdr) = $client->get_pair($key, $check_error=TRUE)
=cut




=head1 METHODS

=head2 $client-E<gt>B<add_dir> ($dir, $preload, $check_error=TRUE)

=over

=item * $dir (string) 

=item * $preload (Gnome2::GConf::ClientPreloadType) 

=item * $check_error (boolean) 

=back

=head2 list = $client->B<all_dirs>($dir, $check_error=TRUE)

=over

=item * $dir (string) 

=item * $check_error (boolean) 

=back


This method returns an array containing all the directories in a given directory.

=head2 list = $client->B<all_entries>($dir, $check_error=TRUE)

=over

=item * $dir (string) 

=item * $check_error (boolean) 

=back

This method returns an array containing all the entries (as L<Gnome2::GConf::Entry>) of a given directory.

=head2 boolean = $client-E<gt>B<get_bool> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 boolean = $client-E<gt>B<set_bool> ($key, $val, $check_error=TRUE)

=over

=item * $key (string) 

=item * $val (boolean) 

=item * $check_error (boolean) 

=back

Returns FALSE on failure.

=head2 changeset = $client-E<gt>B<change_set_from_current> ($check_error=TRUE, $key, ...)

=over

=item * $check_error (boolean) 

=item * ... (list) list of keys to add to the changeset

=back


Create a L<Gnome2::GConf::ChangeSet> from a list of keys inside the GConf
database.


=head2 $client-E<gt>B<clear_cache> 

=head2 boolean = $client->B<commit_change_set> ($cs, $remove_committed, $check_error=TRUE)

=head2 (boolean, changeset) = $client->B<commit_change_set> ($cs, $remove_committed, $check_error=TRUE)

=over

=item * $cs (changeset) 

=item * $remove_committed (boolean) 

=item * $check_error (boolean) 

=back


Commit a given L<Gnome2::GConf::ChangeSet>.  In scalar context, or if
I<$remove_committed> is FALSE, return a boolean value; otherwise, return the
boolean value and the L<Gnome2::GConf::ChangeSet> I<$cs>, pruned of the
successfully committed changes.


=head2 value = $client-E<gt>B<get_default_from_schema> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 client = Gnome2::GConf::Client-E<gt>B<get_default> 

=head2 boolean = $client-E<gt>B<dir_exists> ($dir, $check_error=TRUE)

=over

=item * $dir (string) 

=item * $check_error (boolean) 

=back

=head2 entry = $client-E<gt>B<get_entry> ($key, $locale, $use_schema_default, $check_error=TRUE)

=over

=item * $key (string) 

=item * $locale (string) 

=item * $use_schema_default (boolean) 

=item * $check_error (boolean) 

=back

=head2 list = $client-E<gt>B<error> ($error)

=over

=item * $error (scalar) a L<Glib::Error>

=back


You should not use this method.
This method emits the "error" signal.


=head2 $client-E<gt>B<set_error_handling> ($mode)

=over

=item * $mode (Gnome2::GConf::ClientErrorHandlingMode) 

=back

=head2 double = $client-E<gt>B<get_float> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 boolean = $client-E<gt>B<set_float> ($key, $val, $check_error=TRUE)

=over

=item * $key (string) 

=item * $val (double) 

=item * $check_error (boolean) 

=back

Returns FALSE on failure.

=head2 client = Gnome2::GConf::Client-E<gt>B<get_for_engine> ($engine)

=over

=item * $engine (engine) 

=back

=head2 value = $client-E<gt>B<get> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

Fetch the C<GConfValue> bound to the give I<$key>.

=head2 $client-E<gt>B<set> ($key, $value, $check_error=TRUE)

=over

=item * $key (string) 

=item * $value (value) 

=item * $check_error (boolean) 

=back

Set the C<GConfValue> I<$val> bound to the given I<$key>.

=head2 integer = $client-E<gt>B<get_int> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 boolean = $client-E<gt>B<set_int> ($key, $val, $check_error=TRUE)

=over

=item * $key (string) 

=item * $val (integer) 

=item * $check_error (boolean) 

=back

Returns FALSE on failure.

=head2 boolean = $client-E<gt>B<key_is_writable> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 $client-E<gt>B<get_list> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 boolean = $client-E<gt>B<set_list> ($key, $list_type, $list, $check_error=TRUE)

=over

=item * $key (string) 

=item * $list_type (string) 

=item * $list (scalar) 

=item * $check_error (boolean) 

=back

=head2 integer = $client-E<gt>B<notify_add> ($namespace_section, $func, $data=undef, $check_error=TRUE)

=over

=item * $namespace_section (string) 

=item * $func (scalar) 

=item * $data (scalar) 

=item * $check_error (boolean) 

=back

=head2 $client-E<gt>B<notify_remove> ($cnxn_id)

=over

=item * $cnxn_id (integer) 

=back

=head2 $client-E<gt>B<get_pair> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 boolean = $client-E<gt>B<set_pair> ($key, $car, $cdr, $check_error=TRUE)

=over

=item * $key (string) 

=item * $car (value) 

=item * $cdr (value) 

=item * $check_error (boolean) 

=back

=head2 $client-E<gt>B<preload> ($dirname, $type, $check_error=TRUE)

=over

=item * $dirname (string) 

=item * $type (Gnome2::GConf::ClientPreloadType) 

=item * $check_error (boolean) 

=back

=head2 boolean = $client-E<gt>B<recursive_unset> ($key, $flags=0, $check_error=TRUE)

=over

=item * $key (string) 

=item * $flags (Gnome2::GConf::UnsetFlags) 

=item * $check_error (boolean) 

=back

Since: gconf 2.3

=head2 $client-E<gt>B<remove_dir> ($dir, $check_error=TRUE)

=over

=item * $dir (string) 

=item * $check_error (boolean) 

=back

=head2 changeset = $client-E<gt>B<reverse_change_set> ($cs, $check_error=TRUE)

=over

=item * $cs (changeset) 

=item * $check_error (boolean) 

=back

Reverse the given L<Gnome2::GConf::ChangeSet>.

=head2 schema = $client-E<gt>B<get_schema> ($key)

=over

=item * $key (string) 

=back

=head2 boolean = $client-E<gt>B<set_schema> ($key, $schema, $check_error=TRUE)

=over

=item * $key (string) 

=item * $schema (schema) 

=item * $check_error (boolean) 

=back

=head2 string = $client-E<gt>B<get_string> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 boolean = $client-E<gt>B<set_string> ($key, $val, $check_error=TRUE)

=over

=item * $key (string) 

=item * $val (string) 

=item * $check_error (boolean) 

=back

Returns FALSE on failure

=head2 $client-E<gt>B<suggest_sync> ($check_error=TRUE)

=over

=item * $check_error (boolean) 

=back

=head2 list = $client-E<gt>B<unreturned_error> ($error)

=over

=item * $error (scalar) a L<Glib::Error>

=back


You should not use this method.
This method emits the "unreturned-error" signal.


=head2 boolean = $client-E<gt>B<unset> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back

=head2 list = $client-E<gt>B<value_changed> ($key, $value)

=over

=item * $key (string) 

=item * $value (value) 

=back


You should not use this method.
This method emits the "value-changed" signal.


=head2 value = $client-E<gt>B<get_without_default> ($key, $check_error=TRUE)

=over

=item * $key (string) 

=item * $check_error (boolean) 

=back



=cut


=head1 SIGNALS

=over

=item B<value-changed> (Gnome2::GConf::Client, string, gpointer)

=item B<unreturned-error> (Gnome2::GConf::Client, gpointer)

=item B<error> (Gnome2::GConf::Client, gpointer)

=back



=cut


=head1 ENUMS AND FLAGS

=head2 enum Gnome2::GConf::ClientErrorHandlingMode



=over

=item * 'handle-none' / 'GCONF_CLIENT_HANDLE_NONE'

=item * 'handle-unreturned' / 'GCONF_CLIENT_HANDLE_UNRETURNED'

=item * 'handle-all' / 'GCONF_CLIENT_HANDLE_ALL'

=back


=head2 enum Gnome2::GConf::ClientPreloadType



=over

=item * 'preload-none' / 'GCONF_CLIENT_PRELOAD_NONE'

=item * 'preload-onelevel' / 'GCONF_CLIENT_PRELOAD_ONELEVEL'

=item * 'preload-recursive' / 'GCONF_CLIENT_PRELOAD_RECURSIVE'

=back


=head2 flags Gnome2::GConf::UnsetFlags

=over

=item * 'names' / 'GCONF_UNSET_INCLUDING_SCHEMA_NAMES'

=back




=cut


=head1 SEE ALSO

L<Gnome2::GConf>, L<Glib::Object>


=cut


=head1 COPYRIGHT

Copyright (C) 2003-2006 by the gtk2-perl team.

This software is licensed under the LGPL.  See L<Gnome2::GConf> for a full
notice.



=cut