How to use Gconf

GConf

GConf is the configuration system of choice for GNOME 2
applications. It is replacing gnome-config, a very simple INI file
based format, which turned out to be rather limited for large
applications, and for handling advanced system-wide configuration by
sysadmins. GConf on the other hand, is a lot more capable in those
areas.

GConf was introduced in the GNOME 1.4 platform, but most GNOME
applications didn't use it, with the most notable exception being
Nautilus, the new GNOME file manager.

For GNOME 2 though, GConf is being rolled in more aggressively, with
all (or at least most) of the core applications using GConf to store
and manage their configuration data.

Advantages of GConf
There are numerous advantages to using GConf. The configuration data
is stored in a tree structure, which makes it a lot easier to manage
the preferences of a large application, which might have many
preferences and configuration options.

An example of this tree structured configuration data might look like the following, taken from the web browser Galeon:

/apps/galeon:

/apps/galeon/Rendering:

/apps/galeon/Rendering/FontsColors:

background_color = #FFFFFF

visited_link_color = #FF0000

Here you see that Galeon is storing its preferences under the apps
category, which is the place for applications to do so. Under the
desktop category, on the other hand, desktop wide preferences, such as
whether to use a left or right handed mouse, are stored.

Using subcategories, the preferences are split in small groups that
belong together. This makes things clearer than just keeping all the
options in one huge list, like the old-fashioned way dictated by
gnome-config.

Data types
The kinds of data you can store in a GConf entry are: integer, string, float, boolean, schema, list, pair.

Most of these should be familiar to you, perhaps with the exception of schema, list and pair.

Schemas store a GConfSchema data type, which contains
meta-information about a key. This will be described a bit more in
detail further on in the article.

The list type stores a list of keys, although it has a few
limitations. First all the elements must be of the same type, second,
only the primitive types can be contained in a list (that is, all the
types except list and pair).

Pairs can store two primitive values, either of the same type, or
two different ones. Pairs can, like lists, only contain primitive
types.

Notification
GConf offers another very nice feature for the modern desktop,
namely notification across applications. This makes it possible for
multiple applications, or multiple running instances of the same
application, to immediately react to changes to preferences, and
perform the necessary work to adapt to the new preferences.

In order to get notified of such a change, your application must
tell GConf that it wants to listen to changes to a certain value, or to
a whole directory in the configuration database.

Let's try all this out with a small example:(gconf-test.c)

#include <glib.h>
#include <gtk/gtk.h>
#include <gconf/gconf-client.h>
#define PATH "/apps/GNOMEnclature/gconf_example"
#define KEY "/apps/GNOMEnclature/gconf_example/my_option"
static void
button_toggled_cb (GtkWidget *button, gpointer data)
{
GConfClient *client = NULL;
gboolean value;
client = gconf_client_get_default ();

value = gtk_toggle_button_get_active (GTK_TOGGLE_BUTTON (button));

gconf_client_set_bool (client, KEY, value, NULL);
}
static void
gconf_notify_func (GConfClient *client,
guint cnxn_id,
GConfEntry *entry,
gpointer user_data)
{
GtkWidget *check_button = GTK_WIDGET (user_data);
GConfValue *value = NULL;
gboolean checked;

value = gconf_entry_get_value (entry);

checked = gconf_value_get_bool (value);

gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (check_button),
checked);
}
int main (int argc, char *argv[])
{
GtkWidget *window;
GtkWidget *check_button;
GConfClient *client;
gboolean value;

gtk_init (&argc, &argv);

client = gconf_client_get_default ();

window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
g_signal_connect (window, "destroy", gtk_main_quit, NULL);
value = gconf_client_get_bool (client, KEY, NULL);

check_button = gtk_check_button_new_with_label ("My Option");
gtk_toggle_button_set_active (GTK_TOGGLE_BUTTON (check_button), value);

g_signal_connect (check_button, "toggled",
(GCallback)(button_toggled_cb), NULL);

gtk_container_add (GTK_CONTAINER (window), check_button);
gtk_widget_show_all (window);

gconf_client_add_dir (client, PATH, GCONF_CLIENT_PRELOAD_NONE, NULL);
gconf_client_notify_add (client, KEY, gconf_notify_func, check_button,
NULL, NULL);
gtk_main ();
return 0;
}

Makefile:

CFLAGS =  `pkg-config --cflags gtk+-2.0 glib-2.0 gconf-2.0` -g
LDFLAGS =  `pkg-config --libs gtk+-2.0 gconf-2.0` -rdynamic
SRC=gconf-test.c
test:$(SRC)
$(CC) $(CFLAGS) $(LDFLAGS) $(SRC) -o test

This example will popup a small window with a check button, that is
connected to a GConf key. Try compiling the program, and start two
instances of it, to see the notification service at work. When you
check the button in one of the programs, it will immediately update the
second program window as well! Also note that the state of the button
is saved so the next time you start the program, it will be the same
way as the last time you ran it.

Writing and using schema files

To use schemas with your application, you first need to create a
schema file, which is an XML file, listing all the schemas. A simple
example might look like:

<gconfschemafile>
<schemalist>
<schema>
<key>/schemas/apps/totem/lock_screensaver_on_audio</key>
<applyto>/apps/totem/lock_screensaver_on_audio</applyto>
<owner>totem</owner>
<type>bool</type>
<default>true</default>
<locale name="C">
<short>Allow the screensaver to activate even when audio-only is playing</short>
<long>
Allow the screensaver to activate even when audio-only is playing.
This is useful for monitor powered speakers.
</long>
</locale>
</schema>
<schema>
<key>/schemas/apps/totem/open_path</key>
<applyto>/apps/totem/open_path</applyto>
<owner>totem</owner>
<type>string</type>
<default></default>
<locale name="C">
<short>Default location for the "Open..." dialogues</short>
<long>Default location for the "Open..." dialogues, default is the current directory</long>
</locale>
</schema>
</schemalist>
</gconfschemafile>

As you can see, a schema file is simply a list of schemas. For each
schema, you specify the type, default value, and which key the schema
applies to. Make sure to add useful descriptions of the key, both the
short and the long versions.

When you have your schema file, you can use gconftool to install it:

# gconftool --install-schema-file=FILENAME

If you want to read more about GConf, check out the API reference at: http://developer.gnome.org/doc/API/gconf/index.html
.