# Configuration Editor Manual

## Introduction

The GNOME Desktop and many applications use GConf to store user preferences and system configuration data. GConf provides a central storage location for preferences, simplifying configuration management for users and system administrators. More information about GConf can be found in the GNOME System Administrator's Guide.

&app; allows users to modify their preferences for the entire GNOME Desktop and any applications which use GConf. Additionally, system administrators can use &app; to set default and mandatory settings which will affect all users.

Preferences are stored in GConf in a hierarchy of keys. Each key has an associated value which specifies your setting for that preference. For instance, the key `/apps/glines/preferences/ball_theme` stores which theme you use in the game Five or More.

&app; enables you to modify your configuration source directly. If you are not an experienced user, do not use &app; to set preferences for the GNOME Desktop. Instead, use the preference tools in the GNOME Desktop. For information about how to use preference tools, see the latest version of the GNOME Desktop User Guide for your platform.

## Getting Started

### To Start &app;

You can start &app; in the following ways:

Applications menu

- Choose System Tools Configuration Editor.

Command line

- Execute the following command: `gconf-editor`

### When You Start &app;

When you start &app;, the following window is displayed.

#### &app; Window

Shows GConf Editor window. Callouts: Tree pane, Modification pane, Documentation pane.

The &app; window contains the following panes:

Tree pane

- Enables you to navigate the hierarchy of keys in GConf. Use this pane to display the keys that you want to modify in the modification pane. The tree pane is on the left side of the window.

Modification pane

- Displays the keys in the selected GConf location in the tree pane. Use this pane to select keys that you want to modify and to modify the values of keys. The modification pane is in the upper part of the right side of the window.

  The icons beside the keys in the modification pane indicate what type of value you can enter for the key. For example, the check mark icon beside the `/system/http_proxy/use_http_proxy` key indicates that you can enter a Boolean value (true or false) for the key. See icons for more information on each icon.

Documentation pane

- Displays documentation for the currently selected key. Use this pane to read more information about the GConf preference keys.

Results pane (not shown)

- Enables you to view the results of a search or to search through the list of your recently viewed key names. The rest of the window will show the information for whichever key you have selected in this pane. The results pane will appear on the bottom of the window when you list the recent keys or perform a search.

## Working with Windows

### Opening New Windows

There are a three types of window you can open in &app;: Settings, Defaults, and Mandatory. What values &app; sets depends on what type of window you have open. You can open each type of window with the appropriate item under the File menu.

Since the settings in Defaults and Mandatory windows affect all users of the computer, only a system administrator can use these types of windows. To change your preferences, you should use the Settings window.

Settings

- You can use the Settings window to set your personal preferences. Changes made in the Settings window only affect your desktop. You cannot change the settings that the system administrator has made mandatory.

Defaults

- If you are a system administrator, you can use the Defaults window to edit the default settings for all users. If a user does not set the value of a key explicitly, the value will be taken from the default settings. Users can always override the default settings.

Mandatory

- If you are a system administrator, you can use the Mandatory window to edit the mandatory settings for all users. When a mandatory value is set for a key, users are not able to change that value. This can be used to lock down certain options.

### Closing and Quitting

You can close a &app; window by selecting File Close Window in that window. To close all &app; windows and quit the application completely, select File Quit in any &app; window.

## Working with Keys

Keys are a way of looking up a value. Every preference stored in GConf is assigned to a key. Applications which use GConf access the values of keys to determine how to look and behave. When you change something in the Preferences of an application, you are changing the value associated to a key in GConf.

### Copying a Key Name

To copy a key name to the clipboard, select the key name you want to copy in the modification pane. Choose Edit Copy Key Name. You can paste the key name into any other application.

### Viewing Recent Key Names

To view recent key names, choose Edit List Recent Keys. This action will open the results pane at the bottom of the current window. You can move through the results list by scrolling up and down with the scroll bar or the arrow keys. The information for the selected key or folder will appear in the rest of the window.

Viewing recent keys is useful if you need to get back to a key you just changed and don't remember where it is.

### Modifying the Value of a Key

The icons next to the key name show what kind of value that key can take. See icons for more information on each icon. To modify the value of a key, perform the following steps:

1. Use the tree pane to display the key that you want to modify in the modification pane.

2. Select the key to modify in the modification pane.

3. To change the value of an integer key or a string key, click in the Value column of the key. Type the new value for the key. Alternatively, right-click on the key and select Edit Key from the popup menu.

   To change the value of a Boolean key, click in the Value column of the key to select or deselect the check box. Alternatively, right-click on the key and select Edit Key from the popup menu.

   To change the value of a list key, right-click on the key and select Edit Key from the popup menu. The Edit Key dialog provides a list of the values associated to that key. You can use this dialog to edit each particular value in the list, add or remove values from the list, and move each value up or down in the list.

Your system administrator may have locked down certain keys by providing mandatory values. If the selected key has a mandatory value set, you will not be able to edit the value. The documentation pane will display the label This key is not writable if you are not allowed to edit the value of that key.

## Finding Keys Quickly

To locate keys quickly, &app; allows you to search the key names in GConf. Additionally, you can use bookmarks to find directories of keys that you need to access frequently.

### Using Bookmarks

To access a directory location in your bookmarks, choose the location from the Bookmarks menu. You can add and remove directory locations to your Bookmarks menu.

To add a bookmark, select the location that you want to bookmark in the tree pane. Choose Bookmarks Add Bookmark.

To delete a bookmark, perform the following steps:

1. Choose Bookmarks Edit bookmarks.

2. Select the bookmark in the Edit bookmarks dialog, then click Delete.

3. Click Close.

### Searching for Keys

To search for keys, perform the following steps:

1. Choose Edit Find.

2. Enter the keyword you want to search for in the Search for field. You can also select the optional check boxes Search also in key names and Search also in key values. If these check boxes are not selected, the search will only be performed on folder names. Selecting these boxes will expand the search parameters.

3. Click Find.

The results from the search will appear in the results pane. To move through the results list, first select that pane. Then you can move through the results with the scroll bar or the arrow keys. The information for the selected key or folder will appear in the rest of the window.

## Default and Mandatory Settings

If you are a system administrator, you can set default and mandatory settings in GConf which will affect all users. Default settings are used when the user has not set a value explicitly, and users can always override them. Mandatory settings are always used for all users, and they cannot override them.

You can use the Defaults and Mandatory windows to edit and remove default and mandatory settings. The Defaults and Mandatory windows will only show you those settings which have already been made default or mandatory. You cannot use these windows to create new default and mandatory settings. Instead, you can set settings from the Settings window to be default or mandatory.

To open a Defaults window, choose File New Defaults Window. To open a Mandatory window, choose File New Mandatory Window .

### Creating Default Settings

To create a default setting, perform the following steps:

1. In the Settings window, use the tree pane to display the key that you want to set as default.

2. Right-click on the key and select Set as Default from the popup menu.

### Creating Mandatory Settings

To create a mandatory setting, perform the following steps:

1. In the Settings window, use the tree pane to display the key that you want to set as mandatory.

2. Right-click on the key and select Set as Mandatory from the popup menu.

### Modifying and Removing Default and Mandatory Settings

You can use the Defaults and Mandatory windows to modify and remove default and mandatory settings. To modify a default or mandatory setting, use the appropriate window and modify the key as you would for keys in the Settings window. See modify-key for more information on modifying keys.

To remove a default or mandatory key, perform the following steps:

1. In the appropriate window, use the tree pane to display the key that you want to remove from the default or mandatory settings.

2. Right-click on the key and select Unset Key from the popup menu.

## Icons and Key Types

The icons beside the keys in the modification pane indicate what type of value you can enter for the key. The following list shows the possible icons and what types of values they represent.

Boolean key

- Can be either true or false. &app; will provide a check box for this type of key.

Number key

- Can hold numbers. These can be either integer or floating point (fractional) numbers.

String key

- Can hold any string of text.

Schema key

- Used for documenting other keys. The documentation for each key is provided by a seperate key, typically under the `/schemas` directory. Users and system administrators usually will not need to work with schema keys directly.

List key

- Lists of arbitrary length. Each element of the list must be of the same type, and one of the primitive types of boolean, number, or string.

Pair key

- Can hold exactly two values. The two values must be one of the primitive types, but they do not have to be the same type. Currently, &app; is unable to edit pair keys.

Blank

- Used when &app; does not understand the type of key. The blank icon is also currently used for pair keys.