Gtk+/Gnome Application Development
Prev	Home	Next

Saving Configuration Information

libgnome comes with the ability to store simple key-value pairs in plain text configuration files. Convenience routines are provided for numeric and boolean types which transparently convert to and from a text representation of each type. The standard location for Gnome configuration files is ~/.gnome, and the library will use that location by default. However, the library can be used with any file. There are also variants of each function which save to ~/.gnome_private, a directory with user permissions only. The basic functions to store and retrieve data are listed in Figure 4 in the section called Reading Stored Config Data and Figure 5 in the section called Storing Data In Configuration Files. This module of libgnome is often referred to as gnome-config. Don't confuse this usage of "gnome-config" with the gnome-config script that reports the compile and link flags for Gnome programs.

The gnome-config functions work with a path. A path has three components:

The filename to use, underneath the ~/.gnome or ~/.gnome_private directory. By convention this is the name of your application.
A section---a logical subcategory of related configuration information.
A key---the key half of a key-value pair. The key is actually associated with a piece of configuration data.

A path is passed to Gnome as a string, with the form "/filename/section/key". If you want to use a filename which is not in the standard Gnome directories, you can bracket the entire path with the '=' character and it will be interpreted as absolute. You can even use this as a simple datafile format (it is used for the .desktop files programs install in order to appear on the Gnome panel menu). However, XML (perhaps using the gnome-xml package) is almost certainly a better choice for that. XML may also be a better choice for storing some kinds of configuration information; the primary advantage of the libgnome configuration library is its simplicity.

gnome-config has a long history; it was first written for the WINE Windows emulator project, then used in the GNU Midnight Commander file manager, and finally migrated into the Gnome libraries. The plan is to replace gnome-config with something more powerful in the next version of Gnome; we want to support per-host configuration, backends such as LDAP, and other features. However, the gnome-config API will almost certainly be supported even if the underlying engine changes dramatically.

Reading Stored Config Data

Retrieving data from files is simple. You simply call a function to retrieve the value for a given key. The value-retrieving functions (shown in Figure 4) accept a path as their argument. For example, you might ask whether the user wants to see a dialog box:

  gboolean show_dialog;

  show_dialog = 
    gnome_config_get_bool("/myapp/General/dialog");

If the config file doesn't exist yet, or there is no key matching the path you provide, these functions return 0, FALSE, or NULL. The functions that return a string return allocated memory; you should g_free() the returned string. The string vector functions return an allocated vector full of allocated strings (g_strfreev() is the easiest way to free this vector).

You can specify a default value to be returned if the key does not exist; to do so, append an "=value" to the path. For example:

  gboolean show_dialog;

  show_dialog = 
    gnome_config_get_bool("/myapp/General/dialog=true");

Each function has a with_default variant; these tell you whether the return value was taken from a config file or from the default you specified. For example:

  gboolean show_dialog;
  gboolean used_default;

  show_dialog = 
    gnome_config_get_bool_with_default("/myapp/General/dialog=true", 
                                       &used_default); 

  if (used_default)
    printf("Default value used for show_dialog\n");

gnome_config_push_prefix() and gnome_config_pop_prefix() (in Figure 7 in the section called Other Config File Operations) can be used to avoid specifying the entire path each time. For example:

  gboolean show_dialog;

  gnome_config_push_prefix("/myapp/General/");

  show_dialog = 
    gnome_config_get_bool("dialog=true"); 

  gnome_config_pop_prefix();

These functions also work when saving values.

The configuration functions with private in their name use a .gnome_private directory with restricted permissions, as discussed above. The translated_string functions qualify the provided key with the name of the current locale; these are used when Gnome reads .desktop files (see the section called .desktop Entries in the chapter called Creating Your Source Tree) and are probably not useful to applications.

#include <libgnome/gnome-config.h>

gchar* gnome_config_get_string(const gchar* path);

gchar* gnome_config_get_translated_string(const gchar* path);

gint gnome_config_get_int(const gchar* path);

gdouble gnome_config_get_float(const gchar* path);

gboolean gnome_config_get_bool(const gchar* path);

void gnome_config_get_vector(const gchar* path, gint* argcp, gchar*** argvp);

gchar* gnome_config_private_get_string(const gchar* path);

gchar* gnome_config_private_get_translated_string(const gchar* path);

gint gnome_config_private_get_int(const gchar* path);

gdouble gnome_config_private_get_float(const gchar* path);

gboolean gnome_config_private_get_bool(const gchar* path);

void gnome_config_private_get_vector(const gchar* path, gint* argcp, gchar*** argvp);

gchar* gnome_config_get_string_with_default(const gchar* path, gboolean* was_default);

gchar* gnome_config_get_translated_string_with_default(const gchar* path, gboolean* was_default);

gint gnome_config_get_int_with_default(const gchar* path, gboolean* was_default);

gdouble gnome_config_get_float_with_default(const gchar* path, gboolean* was_default);

gboolean gnome_config_get_bool_with_default(const gchar* path, gboolean* was_default);

void gnome_config_get_vector_with_default(const gchar* path, gint* argcp, gchar*** argvp, gboolean* was_default);

gchar* gnome_config_private_get_string_with_default(const gchar* path, gboolean* was_default);

gchar* gnome_config_private_get_translated_string_with_default(const gchar* path, gboolean* was_default);

gint gnome_config_private_get_int_with_default(const gchar* path, gboolean* was_default);

gdouble gnome_config_private_get_float_with_default(const gchar* path, gboolean* was_default);

gboolean gnome_config_private_get_bool_with_default(const gchar* path, gboolean* was_default);

void gnome_config_private_get_vector_with_default(const gchar* path, gint* argcp, gchar*** argvp, gboolean* was_default);

Figure 4. Retrieving data from configuration files

Gtk+/Gnome Application Development
Prev	Home	Next