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 .