<para>A command line tool, <command>gconftool-2</command>.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="gconf-24">
<title>GConf Repository</title>
<indexterm>
<primary>GConf</primary>
<secondary>repository</secondary>
</indexterm>
<para>Each preference in the <application>GConf</application> repository is
expressed as a key-value pair. A <firstterm>GConf preference key</firstterm>
is an element in the repository that corresponds to an application preference.
For example, the <systemitem>/apps/gnome-session/options/show_splash_screen</systemitem>
preference key corresponds to the <guilabel>Show splash screen on login</guilabel>
option in the <application>Sessions</application> preference tool. The GNOME
Desktop user interface does not contain all of the preference keys in the <application>GConf</application> repository. For example, the <application>Panel</application>
preference tool does not contain an option that corresponds to the <systemitem>/apps/panel/global/tooltips_enabled</systemitem> key.</para>
<para>The repository is structured like a simple hierarchical file system.
The repository contains the following:</para>
<itemizedlist>
<listitem>
<para>Directories that correspond to applications that use the <application>GConf</application> repository. For example, the file system contains the
<para>Subdirectories that correspond to categories of preferences.
For example, the file system contains the directory <systemitem>/apps/metacity/general</systemitem>.</para>
</listitem>
<listitem>
<para>Special files that list the preference keys in the directory,
and contain information about the keys. For example, a file that contains
information about the keys that relate to the HTTP proxy preferences is in
the directory <systemitem>/system/http_proxy</systemitem>. </para>
</listitem>
<listitem>
<para>A <systemitem>/schemas</systemitem> directory that contains files
that describe all of the preference keys.</para>
</listitem>
</itemizedlist>
<para>Preference keys typically have simple values such as strings, integers,
or lists of strings and integers. The format of the preference key in the
repository depends on the backend module that is used to read the repository.
The following is an example of the <systemitem>/desktop/gnome/interface/font_name</systemitem> preference key when an Extensible Markup Language (XML) backend
a series of storage locations that are called <firstterm>configuration sources</firstterm>. The configuration sources are listed in the <firstterm>GConf
path file</firstterm>. The location of the <application>GConf</application>
path file is <systemitem>/etc/gconf/<replaceable>gconf-version-number</replaceable>/path</systemitem>. Each user has a path file. The path file specifies the following
information for each configuration source:</para>
<itemizedlist>
<listitem>
<para>The backend module to use to read the repository. </para>
</listitem>
<listitem>
<para>The permissions on the repository.</para>
</listitem>
<listitem>
<para>The location of the repository.</para>
</listitem>
</itemizedlist>
<para>The <application>GConf</application> path file also contains <systemitem>include</systemitem> instructions. By default, the contents of the <application>GConf</application> path file are as follows: </para>
<para>When <application>GConf</application> searches for a preference value, <application>GConf</application> reads the configuration sources in the order specified
in the path file. The following table describes the configuration sources
in the path file:</para>
<informaltable frame="topbot">
<tgroup cols="2" colsep="0" rowsep="0">
<colspec colwidth="31.29*"/>
<colspec colwidth="68.71*"/>
<thead>
<row rowsep="1">
<entry>
<para>Configuration Source</para>
</entry>
<entry>
<para>Description</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry valign="top">
<para>Mandatory</para>
</entry>
<entry valign="top">
<para>The permissions on this configuration source are set to read only. Users cannot
overwrite the values in this source, so the preferences in the source are
mandatory.</para>
</entry>
</row>
<row>
<entry valign="top">
<para>User</para>
</entry>
<entry valign="top">
<para>This configuration source is stored in the <filename>.gconf</filename> directory
in the home directory of the user. When the user sets a preference, the new
preference information is added to this location. </para>
<para>You can use
the <application>Configuration Editor</application> to modify the user configuration
source.</para>
</entry>
</row>
<row>
<entry valign="top">
<para>Default</para>
</entry>
<entry valign="top">
<para>This configuration source contains the default preference settings.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The sequence of the configuration sources in the path file ensures that
mandatory preference settings override user preference settings. The sequence
also ensures that user preference settings override default preference settings.
That is, <application>GConf</application> applies preferences in the following
order of priority:</para>
<orderedlist>
<listitem>
<para>Mandatory preferences </para>
</listitem>
<listitem>
<para>User-specified preferences </para>
</listitem>
<listitem>
<para>Default preferences</para>
</listitem>
</orderedlist>
<para>The <systemitem>include</systemitem> instructions in the <application>GConf</application> path file enable system administrators to specify other configuration
<para>When you associate a schema key with a preference key, the preference
uses the suggested value that is specified in the schema object of the schema
key. The suggested value is contained in the <sgmltag><default></sgmltag>
element in the schema object. By default, all the preference keys in the default
configuration source are associated with schema keys.</para>
<para>Typically, schemas are stored in the default configuration source. </para>
</sect2>
<sect2 id="gconf-2">
<title>GConf Schema Definition Files</title>
<indexterm>
<primary>GConf</primary>
<secondary>schema definition files</secondary>
<tertiary>introduction</tertiary>
</indexterm>
<indexterm>
<primary>schemas</primary>
<secondary>schema definition files</secondary>
<tertiary>introduction</tertiary>
</indexterm>
<para>Schemas are generated from <firstterm>schema definition
files</firstterm>. A schema definition file defines the characteristics of
all of the keys in a particular application. Schema definition files have
a <filename>.schemas</filename> extension.</para>
<para>The schema definition files are included in the <filename>/etc/gconf/schemas</filename> directory. You can use the schema definition files to create a
new configuration source.</para>
<para>Some schema definition files correspond closely to a part of the GNOME
Desktop user interface. For example, <filename>system_http_proxy.schemas</filename>
corresponds to the <application>Network Proxy</application> preference tool. Other schema definition files contain
preference keys that are not present in the GNOME Desktop user interface.
For example, the <systemitem>/apps/panel/global/tooltips_enabled</systemitem> key
is not present in the user interface. </para>
<para>Some parts of the GNOME Desktop user interface contain preferences that
represent preference keys from more than one schema definition file. For example,
the <application>Keyboard Shortcuts</application> preference tool contains preferences that represent
keys from the <filename>panel-global-config.schemas</filename> and <filename>metacity.schemas</filename> files.</para>
</sect2>
</sect1>
<sect1 id="gconf-25">
<title>GConf Daemon</title>
<indexterm>
<primary>gconfd</primary>
<see>GConf daemon</see>
</indexterm>
<indexterm>
<primary>GConf</primary>
<secondary>daemon</secondary>
</indexterm>
<para>The <application>GConf</application> daemon is called <command>gconfd-2</command>. The <application>GConf</application> daemon notifies applications when a preference value changes.
For example, you might select to show only icons in toolbars in the <application>Menus & Toolbars</application> preference tool. When you select this option
in the preference tool, the toolbars on all open applications are updated
instantly. The <application>GConf</application> daemon can operate locally,
or across a network.</para>
<para>An instance of the <application>GConf</application> daemon is started
for each user. The <application>GConf</application> daemon does not have to
deal with complex problems such as authentication and data security. When
the <application>GConf</application> daemon starts, the daemon loads the <application>GConf</application> path file. The <application>GConf</application> daemon
manages all access between applications and the configuration sources.</para>
<para>When an application requests the value of a preference key, the daemon
searches the configuration sources as follows:</para>
<orderedlist>
<listitem>
<para>Search for the value of the preference key in each configuration
source, in the order specified in the path file. If the value is found, return
the value.</para>
</listitem>
<listitem>
<para>If a value is not found, search for the schema key that corresponds
to the preference key in each configuration source, in the order specified
in the path file.</para>
</listitem>
<listitem>
<para>If the schema key is found, check the value of the schema
key.</para>
</listitem>
<listitem>
<para>If the value of the schema key is a schema object, return
the suggested value in the <sgmltag><default></sgmltag> element of the
schema object.</para>
</listitem>
</orderedlist>
<para>The <application>GConf</application> daemon also caches preference key
values. All applications use this cache, so applications only need to access
the configuration sources once.</para>
<para>To terminate the <application>GConf</application> daemon, run the following
<para>Use this option with the <option>--direct</option> option
to specify a configuration source to use. If you do not specify a configuration
source with this option, the command runs on all configuration sources in
the path file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--direct</option>
</term>
<listitem>
<para>Use this option with the <option>--config-source</option> option to access a configuration source directly.
When you use this option, <application>GConf</application> bypasses the server.
Ensure that the <application>GConf</application> daemon, <command>gconfd-2</command>, is not running before you use this option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--dump</option>
</term>
<listitem>
<para>Generates a list that contains all preference
keys in a <application>GConf</application> repository directory that you specify.
The list contains XML descriptions of all the keys. The list is contained
in a <sgmltag><gconfentryfile></sgmltag> element. </para>
<para>For example,
you can redirect the output from this option to generate a file that lists
all keys that are related to your panel configuration. You can use the <option>--load</option> option with this file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--get</option>
</term>
<listitem>
<para>Displays the value of a preference key that you specify.
Also displays the values of the elements in the schema object for a schema
key that you specify.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--help</option>
</term>
<listitem>
<para>Displays a help message about the <command>gconftool-2</command> command, and the options that you can use with the <command>gconftool-2</command> command.</para>
<para>Use this option to specify the data type when you set a
value of a preference key. You can also use this option when you set the value
of an attribute in a schema key. The following is a list of valid data types:</para>
<itemizedlist>
<listitem>
<para>
<type>bool</type>
</para>
</listitem>
<listitem>
<para>
<type>float</type>
</para>
</listitem>
<listitem>
<para>
<type>int</type>
</para>
</listitem>
<listitem>
<para>
<type>list</type>
</para>
</listitem>
<listitem>
<para>
<type>pair</type>
</para>
</listitem>
<listitem>
<para>
<type>string</type>
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--unset</option>
</term>
<listitem>
<para>Resets the value of a preference
key from the user setting to the setting in the default configuration source.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--usage</option>
</term>
<listitem>
<para>Displays a brief help message
about the <command>gconftool-2</command> command, and the options that you
can use with the <command>gconftool-2</command> command.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="gconf-7">
<title>To Set Preference Values</title>
<indexterm>
<primary>GConf</primary>
<secondary>preference values, setting</secondary>
</indexterm>
<indexterm>
<primary>preference values</primary>
<secondary>setting
with GConf</secondary>
</indexterm>
<para>You can set a mandatory value or a
default value for a preference key. Before you change mandatory preference
values or default preference values for users, you must ensure that the <application>GConf</application> daemon is not running for any user. Ensure that all users
are logged out before you change preference values for users.</para>
<para>To set a mandatory value or a default value for a preference key, use
the <command>gconftool-2</command> command, as follows:</para>
<para>You can also set other keyboard accessibility preferences. For information
on the other keyboard accessibility preferences, see the <filename>desktop_gnome_accessibility_keyboard.schemas</filename> schema definition file.</para>
</sect2>
<sect2 id="gconf-18">
<title>To Set Keyboard Shortcut Preferences</title>
<secondary>setting shortcut preferences with GConf</secondary>
</indexterm>
<para>To set
keyboard shortcut preferences, you modify the values of preference keys in <systemitem>/apps/metacity/global_keybindings</systemitem> location. For example, you might
want users to use only the <keycombo><keycap>Alt</keycap><keycap>F3</keycap></keycombo> keyboard
shortcut to open the <guilabel>Run Application</guilabel> dialog. To set this
mandatory value, run the following command:</para>
specifies the following details of the panels in the GNOME Desktop:</para>
<itemizedlist>
<listitem>
<para>Number of panels.</para>
</listitem>
<listitem>
<para>Types of the panels.</para>
</listitem>
<listitem>
<para>Properties of the panels.</para>
</listitem>
<listitem>
<para>Contents of the panels.</para>
</listitem>
</itemizedlist>
<para>The configuration of individual panels and of panel objects is a complex
task. To configure individual panels and panel objects, you must first understand
the structure of the <filename>panel-default-setup.entries</filename> file.
For more information on the <filename>panel-default-setup.entries</filename>
file, see the next section.</para>
<para>To set preferences for individual panels and panel objects, you must
set the values of many preferences in a configuration source. The easiest
way to set the values of panel preferences is to use the <command>gconftool-2</command> command with the <option>--dump</option> and <option>--load</option> options. For more information on how to set preferences for panels
and objects on panels, see <xref linkend="gconf-3"/>.</para>
<sect3 id="gconf-23">
<title>Specifying Individual Panels and Panel Objects</title>
<indexterm>
<primary>GConf</primary>
<secondary>schema definition files</secondary>
<tertiary>panel and panel object</tertiary>
</indexterm>
<indexterm>
<primary>schemas</primary>
<secondary>schema definition files</secondary>
<tertiary>panel and panel object</tertiary>
</indexterm>
<para>The file <filename>panel-default-setup.entries</filename> contains sections that specify panels and panel contents. The <filename>panel-default-setup.entries</filename> file specifies values for schema keys.
The <filename>panel-default-setup.entries</filename> file resides in the <filename>/etc/gconf/schemas</filename> directory. </para>
<para>The <filename>panel-default-setup.entries</filename> file is structured
as follows:</para>
<orderedlist>
<listitem>
<para>Keys that specify the general structure of panels, applets,
and other panel objects in the GNOME Desktop. The following keys specify the
number of panels, panel objects, and applets that appear in the GNOME Desktop:</para>
<para>In the <filename>panel-default-setup.entries</filename> file, the identifier <systemitem>bottom_panel</systemitem> identifies the bottom edge panel.</para>
</listitem>
<listitem>
<para>Keys that specify the properties of the panels. The panel
<para>For example, the key <systemitem>/apps/panel/default_setup/toplevels/bottom_panel/size</systemitem> specifies the size of the bottom panel. </para>
</listitem>
<listitem>
<para>Keys that specify the panel objects, the panel object properties,
and the panels in which the objects reside. For example, the following sample
from <filename>panel-default-setup.entries</filename> specifies a <guimenu>Main Menu</guimenu> object at the left side of the bottom panel:</para>
<para>In the sample above, you might want to change the reference to <filename>hadjaha-00adce02f7.desktop</filename> to another desktop entry file that is
available globally.</para>
<para>When you generate a panel configuration with the <option>--dump</option>
option, the positions of the panel objects are absolute positions. You might
want to change the positions of panel objects from absolute positions to relative
positions. The object at the extreme left of a panel has a <systemitem>position</systemitem> value of <literal>0</literal>. The next object has a <systemitem>position</systemitem> value of <literal>1</literal>, and so on. If you want object
positions to be relative to the right side of the panel, set the value of
the <systemitem>right_stick</systemitem> key to <literal>true</literal>. </para>
<!--Give full key name for position.-->
</listitem>
<listitem>
<para>Use the <option>--load</option> option with the <command>gconftool-2</command> command line tool to set the values of the default configuration
source to the values in the <filename>my-panel-setup.entries</filename> file.
For example, the following command sets the values of the keys in the default
configuration source to the values of the corresponding keys in <filename>my-panel-setup.entries</filename>:</para>
desktop background, you modify the values of the preference keys in the <systemitem>/desktop/gnome/background</systemitem> location. For example, to set a mandatory
image for the background, run the following command:</para>
<para>You can also set other background preferences. For information on the
other background preferences, see the <filename>desktop_gnome_background.schemas</filename> schema definition file.</para>
</sect2>
<sect2 id="gconf-21">
<title>To Set Splash Image Preferences</title>
<indexterm>
<primary>GConf</primary>
<secondary>splash image, setting</secondary>
</indexterm>
<indexterm>
<primary>splash screen</primary>
<secondary>image, setting
with GConf</secondary>
</indexterm>
<para>To set splash image preferences, you
modify the value of the preference keys in the <systemitem>/apps/gnome-session/options/</systemitem> location. For example, if you do not want users ever to see a
splash image, set a mandatory value as follows:</para>
