7.2 The User End

The following sections describe the user's GConf database and how to view and manipulate keys and values independent of an application. Although most users never see any of this, the tools described here can be quite useful when you debug your applications.

7.2.1 Configuration Database Keys and Values

The GConf database looks like a Unix file system. The root and directory separator is the / character. Path components may include letters , numbers , and underscores; a full path is a GConf key. A key may not start with a dot.

The value behind a key can use the following types:

Integer: A 32-bit signed integer, like the C int .
Floating-point number: Similar to C double , but with no defined precision (for portability).
String: A C string encoded in UTF-8. You cannot store binary data in a GConf string because it may not contain NULL bytes.
Boolean: True or false.
List: A set of elements with the preceding basic value types. You may not have a list of lists, a list of pairs (described next ), or a list with differently typed elements.
Pair: Two values of any two basic types.
Schema: Describes a key. You probably will not need to work with schemas directly because GConf automatically installs them; see Section 7.3.6.

To get a clearer picture, you should run a GConf configuration editor.

7.2.2 The GConf Configuration Editor

To start a graphical, interactive GConf configuration editor, run gconf-editor from the command line. You should get a window similar to Figure 7.1 on the next page.

Figure 7.1: GConf configuration editor.

The left side of the window contains the GConf database's tree structure with these primary directories:

/apps: Application-specific settings. Each GConf-enabled application has a subdirectory named after its application identifier here. The /apps/gnome-settings subdirectory is the lone exception; it contains certain GNOME internal values, such as GnomeEntry history items.
/desktop: Environment-wide settings that apply to more than one application. GNOME-specific settings are in /desktop/gnome . There is room for other environments (for example, /desktop/kde for KDE), and any keys that apply to all environments go in /desktop/standard .
/system: Settings that apply to the entire GNOME system, not just applications. For example, the HTTP proxy settings are in /system/http_proxy .
/schemas: Key descriptions. This category contains only metadata, so it isn't terribly interesting.

When you navigate through the GConf database tree and choose a directory, a list of the directory's keys and values appears in the upper-right part of the window. You can change values here and see how an application reacts. Try it yourself ” start Gnomine and then alter some of the values in /apps/gnomine/ geometry . This process works the other way around, too; the GConf editor values change when you set them in the application.

When you select a key in the list, the key description appears below the list if the key has a schema.

7.2.3 gconftool-2

You can manipulate and view GConf values on the command line with gconftool-2 . There are several things that gconftool-2 can do that its graphical counterpart in the previous section cannot, and a command-line tool can go in a Makefile rule.

Retrieving Information

To see the value for a GConf key, use

 $ gconftool-2 --get  key

Make sure that key is a full pathname. Note that -g is an abbreviation for --get .

If the key has a schema, you can see its short and long descriptions with

 $ gconftool-2 --short-docs  key  $ gconftool-2 --long-docs  key

To list the keys and values in a directory, run

 $ gconftool-2 --all-entries  dir

You may substitute -a for --all-entries . To see the directories in a path component, you can use the --all-dirs option:

 $ gconftool-2 --all-dirs  dir

If you just want to list everything in a directory and all of its subdirectories, use

 $ gconftool-2 -R  dir

(Here, -R is short for --recursive-list .) To see a lot of output, try gconftool-2 -R / .

You can test that a directory exists with

 $ gconftool-2 --dir-exists  dir

If dir exists, the return value is 0, and 2 otherwise , as this example shows:

 $ gconftool-2 --dir-exists=/desktop/gnork $ echo $? 2 $ gconftool-2 --dir-exists=/desktop/gnome $ echo $? 0

Here is more of what you can expect from gconftool-2 :

 $ gconftool-2 --all-dirs /desktop/gnome  /desktop/gnome/file_views  /desktop/gnome/applications  /desktop/gnome/sound  /desktop/gnome/interface  /desktop/gnome/url-handlers  /desktop/gnome/accessibility  /desktop/gnome/background  /desktop/gnome/thumbnailers  /desktop/gnome/peripherals  /desktop/gnome/font_rendering $ gconftool-2 -R /desktop/gnome/applications  /desktop/gnome/applications/help_viewer:   needs_term = false   accepts_urls = true   exec = nautilus  /desktop/gnome/applications/window_manager:   workspace_names = (no value set)   current = (no value set)   default = /usr/local/bin/metacity   number_of_workspaces = (no value set)  /desktop/gnome/applications/browser:   nremote = true   needs_term = false   exec = mozilla  /desktop/gnome/applications/terminal:   exec_arg = -x   exec = gnome-terminal $ gconftool-2 -a /desktop/gnome/interface  gtk-im-status-style = callback  toolbar_style = both  gtk_key_theme = Default  enable_animations = true  font_name = Sans 10  cursor_blink_time = 1200  menus_have_tearoff = false  cursor_blink = true  use_custom_font = false  toolbar_icon_size = (no value set)  menus_have_icons = true  can_change_accels = false  accessibility = false  gtk_theme = Default  status_bar_meter_on_right = false  gtk-im-preedit-style = callback  menubar_detachable = false  icon_theme = gnome  toolbar_detachable = true $ gconftool-2 -g /desktop/gnome/interface/gtk_theme Default $ gconftool-2 --short-docs /desktop/gnome/interface/gtk_theme Gtk+ Theme $ gconftool-2 --long-docs /desktop/gnome/interface/gtk_theme Basename of the default theme used by gtk+.

Editing Keys

To set a key's value with a basic type, use --set (or -s ) with the --type ( -t ) qualifier:

 $ gconftool-2 --set  key  --type=  type value

The basic type identifiers are int , float , bool , and string .

Set a list with

 $ gconftool-2 --set  key  --type=list --list-type=  type  [  value1  ,  value2  , ...]

Here, type is the list element type. Pairs are similar:

 $ gconftool-2 --set  key  --type=pair --car-type=  type1  --cdr-type=  type2  '(  value1  ,  value2  )'

Here, type1 and type2 are the types of the elements inside the pair.

Note	When setting a list or pair, do not leave any whitespace between brackets, parentheses, commas, and values.

You can remove a key (and its value) by running

 $ gconftool-2 --unset key

This works only when key is not a directory; -u is the short form of this option. If key is a directory and you want to remove everything inside, use

 $ gconftool-2 --recursive-unset  dir

Here a few examples that set and remove keys and values:

 $ gconftool-2 --set /example/number --type=int 42 $ gconftool-2 --set /example/floatnumber --type=float 42.37e-13 $ gconftool-2 --set /example/state --type=bool true $ gconftool-2 --set /example/name --type=string "J. Random" $ gconftool-2 -s /example/animals --type=list --list-type=string [dog,cat,mouse] $ gconftool-2 -s /example/assoc --type=pair --car-type=int --cdr-type=string \ (534,"num"\) $ gconftool-2 -a /example/assoc $ gconftool-2 -a /example  assoc = (534,num)  floatnumber = 4.2370000737090852e-12  state = true  number = 42  animals = [dog,cat,mouse]  name = J. Random $ gconftool-2 --unset /example/assoc $ gconftool-2 -g /example/assoc No value set for `/example/assoc' $ gconftool-2 --recursive-unset /example $ gconftool-2 -R /example $

Two of the most useful gconftool-2 commands for debugging a program are

 $ gconftool-2 --break-key  key  $ gconftool-2 --break-directory  dir

The --break-key command cycles a key's value through many different types in an attempt to break an application. Your application should be able to survive this test, possibly giving some warning messages. The --break-directory command does the same thing for all keys in a directory. You can specify more than one key or directory with each option; in addition, these two options restore the keys' original values when they finish.

Now that you've seen the how to view and manipulate GConf values, you're ready to use them in your applications.