NAME

       Gnome2::GConf - Perl wrappers for the GConf configuration engine.

SYNOPSIS

         use Gnome2::GConf;

         my $client = Gnome2::GConf::Client->get_default;
         my $app_key = "/apps/myapp/mykey";

         $client->add_dir($app_key, 'preload-none');

         # add a notify for the key
         my $notify_id = $client->notify_add($app_key, sub {
             my ($client, $cnxn_id, $entry) = @_;
             return unless $entry->{value};

             if ($entry->{value}->{type} eq 'string') {
               printf "key '%s' changed to '%s'\n",
                      $entry->{key},
                      $entry->{value}->{value};
             }
           });

         my $string = $client->get_string($app_key);
         $string = 'some string' unless $string;

         $client->set($app_key, { type => 'string', data => $string });

         # set a schema for the key
         $client->set_schema ($app_key,
             {
               type => 'string',
               locale => 'C',
               short_desc => 'Some key.',
               long_desc => 'This key does something.',
               owner => 'some_program'
             });

         # remove the notification callback
         $client->notify_remove($notify_id);

ABSTRACT

       Perl bindings to the 2.2 series of the GConf configuration engine libraries, for use with gtk2-perl.

DESCRIPTION

       This module allows you to use the GConf configuration system in order to store/retrieve the configuration
       of an application.  The GConf system is a powerful configuration manager based on a user daemon that
       handles a set of key and value pairs, and notifies any changes of the value to every program that
       monitors those keys.  GConf is used by GNOME 2.x.

       To discuss gtk2-perl, ask questions and flame/praise the authors, join gtk-perl-list@gnome.org at
       lists.gnome.org.

       Find out more about Gnome at http://www.gnome.org.

DIFFERENT DATA TYPES

       Some opaque data types in GConf are not registered inside the Glib type system.  Thus, they have been
       implemented in a more perlish way, when possible, for the sake of coherency and following the principle
       of least surprise for the perl developer.  These changes try to preserve semantics, to add syntactic
       sugar and to remove the need for accessor methods.

       GConfEntry
           See Gnome2::GConf::Entry

       GConfValue
           See Gnome2::GConf::Value

       GConfChangeSet
           See Gnome2::GConf::ChangeSet

       GConfSchema
           See Gnome2::GConf::Schema

DIFFERENT CALL SIGNATURES

       Reflecting the changes operated for the data types, some methods that use those type have had the call
       signature modified.

       GConfNotifyFunc
           In C, the function passed to "Gnome2::GConf::notify_add" must have the following signature:

                   void (GConfNotifyFunc *) (GConfClient * client,
                                             guint cnxn_id,
                                             GConfEntry * entry);

           Where "GConfEntry" is a container for the key/value pair.  Since in perl there's no "GConfEntry" (see
           above), the "entry" parameter is an hashref.

       GConfClient::get
       GConfClient::set
           In C, these accessor methods return/use a "GConfValue".  In perl, they return/use an hashref.  See
           Gnome2::GConf::Value

       GConfClient::get_list
       GConfClient::set_list
           These accessor methods use a string for setting the type of the lists (lists may have values of only
           one type), and an arrayref containing the values.

       GConfClient::get_pair
       GConfClient::set_pair
           These accessor methods use two hashref (representing "GConfValue"s) for the "car" and the "cdr"
           parameters.

       GConfClient::get_schema
       GConfClient::set_schema
           Similarly to the get/set pair above, these two methods return/use an hashref. See
           Gnome2::GConf::Schema.

       GConfClient::commit_change_set
           In C, this method return a boolean value (TRUE on success, FALSE on failure). On user request (using
           the boolean parameter "remove_committed"), it also returns the "GConfChangeSet", pruned of the
           successfully committed keys.  In perl, this method returns a boolean value both in scalar context or
           if the user sets to FALSE the "remove_committed" parameter; in array context or if the user requests
           the uncommitted keys, returns both the return value and the pruned "GConfChangeSet".

SEE ALSO

       perl(1), Glib(3pm).

AUTHOR

       Emmanuele Bassi <ebassi@gmail.com>

       gtk2-perl created by the gtk2-perl team: http://gtk2-perl.sf.net

COPYRIGHT AND LICENSE

       Copyright 2003-2006 by Emmanuele Bassi

       This library is free software; you can redistribute it and/or modify it under the terms of the GNU
       Library General Public License as published by the Free Software Foundation; either version 2 of the
       License, or (at your option) any later version.

       This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General
       Public License for more details.

       You should have received a copy of the GNU Library General Public License along with this library; if
       not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
       USA.