This chapter describes how to use GConf
to
manage user preferences.
GConf
simplifies the administration of preferences
for users of the Java Desktop System. GConf
enables
you to do the following:
Set mandatory values for particular preferences for all users. In this way, you can control whether users can update particular preferences.
Set default values for particular preferences for all users.
Use suggested values for preferences that are specified in definition files for the preferences.
Read documentation on each preference.
GConf
also notifies applications when a preference
value changes, locally or across a network. In this way, when you change a
preference, all applications that use the preference are immediately updated.
GConf
has the following components:
A repository of user preferences.
A daemon, gconfd-2.
A command line tool, gconftool-2.
Each preference in the GConf
repository is
expressed as a key-value pair. A GConf preference key
is an element in the repository that corresponds to an application preference.
For example, the /apps/gnome-session/options/show_splash_screen
preference key corresponds to the Show splash screen on login
option in the Sessions
preference tool. The Java
Desktop System user interface does not contain all of the preference keys
in the GConf
repository. For example, the Panel
preference tool does not contain an option that corresponds
to the /apps/panel/global/tooltips_enabled key.
The repository is structured like a simple hierarchical file system. The repository contains the following:
Directories that correspond to applications that use the GConf
repository. For example, the file system contains the
directory /apps/gnome-terminal.
Subdirectories that correspond to categories of preferences. For example, the file system contains the directory /apps/gnome-terminal/global.
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 /system/http_proxy.
A /schemas directory that contains files that describe all of the preference keys.
Preference keys typically have simple data types, such as the following:
Strings
Integers
Lists of strings
Lists of 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 /desktop/gnome/interface/font_name preference key when an Extensible Markup Language (XML) backend module is used to read the repository:
<entry name="font_name" mtime="1038323555" muser="user123" type="string"> <stringvalue>Sans 10</stringvalue></entry>
When this guide refers to a preference key, the path to the key is added to the name of the key. For example, the font_name preference key in the /desktop/gnome/interface subdirectory is referred to as /desktop/gnome/interface/font_name.
The GConf
repository contains
a series of storage locations that are called configuration sources. The configuration sources are listed in the GConf
path file. The location of the GConf
path file is /etc/gconf/gconf-version-number/path. Each user has a path file. The path file specifies the following
information for each configuration source:
The backend module to use to read the repository.
The permissions on the repository.
The location of the repository.
The GConf
path file also contains include instructions. By default, the contents of the GConf
path file are as follows:
xml:readonly:/etc/gconf/gconf.xml.mandatory include /etc/gconf/2/local-mandatory.path apoc:readonly:mandatory@ include "$(HOME)/.gconf.path" xml:readwrite:$(HOME)/.gconf apoc:readonly:@ include /etc/gconf/2/local-defaults.path xml:readonly:/etc/gconf/gconf.xml.defaults
When GConf
searches for a preference value, GConf
reads the configuration sources in the order specified
in the path file. The following table describes the configuration sources
in the path file:
Configuration Source |
Description |
---|---|
Mandatory |
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. |
User |
This configuration source is stored in the .gconf directory in the home directory of the user. When the user sets a preference, the new preference information is added to this location. You can use
the |
Default |
This configuration source contains the default preference settings. |
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, GConf
applies preferences in the following
order of priority:
Mandatory preferences
User-specified preferences
Default preferences
The include instructions in the GConf
path file enable you to specify other configuration sources.
Included Configuration Source |
Description |
---|---|
/etc/gconf/2/local-mandatory.path |
Use this configuration source to store mandatory preference values for a particular system. |
$(HOME)/.gconf.path |
The user specifies the location of the configuration source in the home directory, in a file that is called .gconf.path. |
/etc/gconf/2/local-defaults.path |
Use this configuration source to store default preference values for a particular system. |
The apoc references in the GConf
path file specify a Sun Java Desktop System Configuration Manager
backend module. For more information about Sun
Java Desktop System Configuration Manager
, see the Sun Java Desktop System Configuration Manager
documentation
at http://docs.sun.com.
A GConf schema is a collective term for a GConf schema key and a GConf schema object. The following table describes schema keys and schema objects and the relationship of these items to preference keys:
The following table gives examples of a preference key, a schema key, and a schema object:
Item |
Example |
---|---|
Preference key |
/desktop/gnome/interface/font_name |
Schema key |
/schemas/desktop/gnome/interface/font_name |
Schema object |
<schema> <applyto>/desktop/gnome/interface/font_name</applyto> <key>/schemas/desktop/gnome/interface/font_name</key> <owner>gnome</owner> <type>string</type> <default>Sans 10</default> <locale name="C"> <short>Default font</short> <long>Name of the default font used by gtk+.</long> </locale> </schema> |
You can associate a schema key with a preference key. For example, the following /desktop/gnome/interface/font_name key includes a schema key:
<entry name="font_name" mtime="1034873859" schema="/schemas/desktop/gnome/interface/font_name"/>
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 <default> element in the schema object. By default, all the preference keys in the default configuration source are associated with schema keys.
Typically, schemas are stored in the default configuration source.
Schemas are generated from schema definition files. A schema definition file defines the characteristics of all of the keys in a particular application. Schema definition files have a .schemas extension.
The schema definition files are included in the /etc/gconf/schemas directory. You can use the schema definition files to create a new configuration source.
Some schema definition files correspond closely to a part of the Java
Desktop System user interface. For example, system_http_proxy.schemas corresponds to the Internet
preference
tool. Other schema definition files contain preference keys that are not present
in the Java Desktop System user interface. For example, the /apps/panel/global/tooltips_enabled key is not present in the user interface.
Some parts of the Java Desktop System user interface contain preferences
that represent preference keys from more than one schema definition file.
For example, the Shortcuts
preference tool contains
preferences that represent keys from the panel-global-config.schemas and metacity.schemas files.
The GConf
daemon is called gconfd-2. The GConf
daemon notifies applications
when a preference value changes. For example, you might select to show only
icons in toolbars in the Menus & Toolbars
preference
tool. When you select this option in the preference tool, the toolbars on
all open applications are updated instantly. The GConf
daemon can operate locally, or across a network.
An instance of the GConf
daemon is started
for each user. If a user logs in to more than one system, an instance of the GConf
daemon is started for each session. You can configure
the Java Desktop System to use only one instance of the GConf
daemon when a user logs in to more than one system. For information
about how to do this, see Configuring the Java Desktop System to Use One Instance of the GConf
Daemon.
The GConf
daemon does not have to deal with
complex problems such as authentication and data security. When the GConf
daemon starts, the daemon loads the GConf
path file. The GConf
daemon manages
all access between applications and the configuration sources.
When an application requests the value of a preference key, the daemon searches the configuration sources as follows:
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.
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.
If the schema key is found, check the value of the schema key.
If the value of the schema key is a schema object, return the suggested value in the <default> element of the schema object.
The GConf
daemon also caches preference key
values. All applications use this cache, so applications only need to access
the configuration sources once.
To terminate the GConf
daemon, execute the
following command:
# gconftool-2 --shutdown
By default, the Java Desktop System creates multiple instances of the GConf
daemon when users log in to more than one system. You
can configure the Java Desktop System to use only one instance of the GConf
daemon when a user logs in to more than one system. The
user must have an Network File System (NFS) home directory.
When a user uses one instance of the GConf
daemon on more than one system, and the user changes the value of a preference,
the change is applied to all of the sessions to which the user is logged in.
For example, if the user selects to show only icons in toolbars in the Menus & Toolbars
preference tool in one session, the toolbars
on all open applications are updated instantly in all sessions to which the
user is logged in.
Users can only use a single instance of the GConf
daemon for multiple sessions if all of the sessions can access
the home directory of the user.
The Java Desktop System uses Common Object Request Broker Architecture (CORBA). CORBA enables application objects to communicate with one another regardless of what programming language the applications are written in, and regardless of what operating system the applications are running on.
In CORBA, an Object Request Broker (ORB) communicates
between servers and clients. One of the ORBs in the Java Desktop System is ORBit2
. GConf
uses the TCP protocol
in ORBit2
to communicate between the GConf
daemon and the sessions to which the user is logged in.
To configure a system to use one instance of the GConf
daemon for each user, perform the following steps:
For all the systems that the users log in to, ensure that the file /etc/orbitrc contains the following line:
ORBIIOPIPv4=1
Set the value of the GCONF_GLOBAL_LOCKS environment
variable to 1. This ensures that GConf
creates locks in the home directory of the user, and not in a directory on
the local system.
Restart the GConf
daemon.
To configure the system to use multiple instances of the GConf
daemon for each user, unset the value of the GCONF_GLOBAL_LOCKS environment variable. Then restart the GConf
daemon.
The TCP protocol in ORBit2
is not
completely secure because the communications between servers and clients are
not encrypted.
GConf
includes a command line
tool, gconftool-2. You can use the gconftool–2 command to perform the following tasks:
Set the values of keys.
Display the values of keys.
Install schemas from schema definition files when you install an application.
For example, use the following command to display the values of all keys in the /desktop/gnome directory and subdirectories.
# gconftool-2 --recursive-list /desktop/gnome
Table 1–1 lists some of the options that you can use with the gconftool-2 command.
Table 1–1 gconftool-2 Command Options
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 GConf
daemon is not running for any user. Ensure that all users
are logged out before you change preference values for users.
To set a mandatory value or a default value for a preference key, use the gconftool-2 command, as follows:
# gconftool-2 --direct --config-source configuration-source --type data-type --set preference-key value
For example, to set wwwproxy.xyz.com as the mandatory HTTP proxy host, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory --type string --set /system/http_proxy/host wwwproxy.xyz.com
The user cannot override this preference value.
You can also use the gconftool-2 command to set default values. For example, to set the default number of workspaces to five, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --type int --set /apps/metacity/general/num_workspaces 5
The user can override this preference value.
Before you change mandatory preference values or default preference values for users, you must ensure that all users are logged out.
The following sections describe how to assign mandatory or default values to general preferences.
To set HTTP proxy preferences, you modify the values of the preference keys in the /system/http_proxy/ location. For example, to set a mandatory value for the HTTP proxy host, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory --type string --set /system/http_proxy/host proxy-name
To set a default value for the HTTP proxy host, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --type string --set /system/http_proxy/host proxy-name
You can also set other HTTP proxy-related preferences. For information about the other HTTP proxy preferences, see the system_http_proxy.schemas schema definition file.
To set a mandatory number of workspaces, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory --type int --set /apps/metacity/general/num_workspaces integer
To set a default number of workspaces, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --type int --set /apps/metacity/general/num_workspaces integer
You can also set other window manager preferences. For information about the other window manager preferences, see the metacity.schemas schema definition file.
To set keyboard accessibility preferences, you modify the values of the preference keys in the /desktop/gnome/accessibility/keyboard location. For example, if you want to set a mandatory value so that keyboard accessibility features are enabled, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory --type bool --set /desktop/gnome/accessibility/keyboard/enable true
To set a default value for this preference, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --type bool --set /desktop/gnome/accessibility/keyboard/enable false
You can also set other keyboard accessibility preferences. For information about the other keyboard accessibility preferences, see the desktop_gnome_accessibility_keyboard.schemas schema definition file.
To set keyboard shortcut preferences, you modify the values of preference keys in /apps/metacity/global_keybindings location. For example, you might want users to use only the Alt + F3 keyboard shortcut to open the Run Application dialog. To set this mandatory value, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory --type string --set /apps/metacity/global_keybindings/panel_run_dialog '<Alt>F3'
You can also set other keyboard shortcut preferences. For information about the other keyboard shortcut preferences, see the metacity.schemas schema definition file.
The panel-default-setup.entries file specifies the following details of the panels in the Java Desktop System:
Number of panels
Types of the panels
Properties of the panels
Contents of the panels
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 panel-default-setup.entries file. For more information about the panel-default-setup.entries file, see Structure of Panel Configuration File.
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 gconftool-2 command with the --dump and --load options. For more information about how to set preferences for panels and objects on panels, see To Set Preferences for Individual Panels and Panel Objects.
The file panel-default-setup.entries contains sections that specify panels and panel contents. The panel-default-setup.entries file specifies values for schema keys. The panel-default-setup.entries file resides in the /etc/gconf/schemas directory.
The panel-default-setup.entries file is structured as follows:
An entrylist element that specifies the base path for all the keys in the file. The following excerpt from panel-default-setup.entries specifies /apps/panel/default_setup as the base path for keys:
<entrylist base="/apps/panel/default_setup">
For example, if the key general/toplevel_id_list is referred to in panel-default-setup.entries, the full path for the key is /apps/panel/default_setup/general/toplevel_id_list.
Keys that specify the general structure of panels, panel applications, and other panel objects in the desktop. The following keys specify the number of panels, panel objects, and panel applications that appear in the desktop:
general/toplevel_id_list
general/object_id_list
general/applet_id_list
The keys also assign identifiers to each panel, panel object, and panel application. For example, the following sample from panel-default-setup.entries specifies that one panel appears in the desktop:
<entry> <key>general/toplevel_id_list</key> <schema_key>/schemas/apps/panel/general/toplevel_id_list</schema_key> <value> <list type="string"> <value> <string>bottom_panel</string> </value> </list> </value> </entry>
In the panel-default-setup.entries file, the identifier bottom_panel identifies the panel at the bottom of the screen.
Keys that specify the properties of the panels. The panel property keys are structured as follows:
toplevels/panel-name/panel-property-key
For example, the key toplevels/bottom_panel/size specifies the size of the bottom panel.
Keys that specify the panel objects, the panel object properties, and the panels in which the objects reside. For example, the following sample from panel-default-setup.entries specifies a Main Menu object at the left side of the bottom panel:
<entry> <key>objects/main_menu/object_type</key> <schema_key>/schemas/apps/panel/objects/object_type</schema_key> <value> <string>menu-object</string> </value> </entry> <entry> <key>objects/main_menu/toplevel_id</key> <schema_key>/schemas/apps/panel/objects/toplevel_id</schema_key> <value> <string>bottom_panel</string> </value> </entry> <entry> <key>objects/main_menu/position</key> <schema_key>/schemas/apps/panel/objects/position</schema_key> <value> <int>0</int> </value> </entry>
Keys that specify the panel applications, the panel application
preferences, and the panels in which the panel applications reside. For example,
the following sample from panel-default-setup.entries
specifies the Window List
panel application, in
the bottom panel:
<entry> <key>applets/window_list/object_type</key> <schema_key>/schemas/apps/panel/objects/object_type</schema_key> <value> <string>bonobo-applet</string> </value> </entry> <entry> <key>applets/window_list/toplevel_id</key> <schema_key>/schemas/apps/panel/objects/toplevel_id</schema_key> <value> <string>bottom_panel</string> </value> </entry> <entry> <key>applets/window_list/position</key> <schema_key>/schemas/apps/panel/objects/position</schema_key> <value> <int>3</int> </value> </entry> . . . <entry> <key>applets/window_list/bonobo_iid</key> <schema_key>/schemas/apps/panel/objects/bonobo_iid_type</schema_key> <value> <string>OAFIID:GNOME_WindowListApplet</string> </value> </entry>
The OAFIID is a unique identifier for a panel application. To find the
OAFIID for a particular panel application, see the .server
file for the panel application in the /usr/lib/bonobo/servers
directory. For example, the following excerpt from GNOME_Wncklet_Factory.server shows the OAFIID for the Window List
panel application:
<oaf_server iid="OAFIID:GNOME_WindowListApplet" type="factory" location="OAFIID:GNOME_Wncklet_Factory">
To set the preferences for a panel and the objects on a panel, perform the following steps:
Log in to a session with a test user account.
Configure the panels as required.
Use the --dump option with the gconftool-2 command line tool to generate a file that contains an
XML description of your panel configuration. The --dump
option generates a list that contains all preference keys in a GConf
repository directory that you specify.
For example, the following command creates an XML description of the default panel configuration in a file called my-panel-setup.entries:
# gconftool-2 --dump /apps/panel/profiles/default > my-panel-setup.entries
Open the my-panel-setup.entries file in a text editor, and modify the file as required.
For example, you might want to change the location of the desktop entry files. The following is an excerpt from a file generated with the --dump option:
<entry> <key>objects/object_16/launcher_location</key> <schema_key>/schemas/apps/panel/objects/launcher_location</schema_key> <value> <string>hadjaha-00adce02f7.desktop</string> </value> </entry>
In the sample above, you might want to change the reference to hadjaha-00adce02f7.desktop to another desktop entry file that is available globally.
When you generate a panel configuration with the --dump 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 position value of 0. The next object has a position value of 1, and so on. If you want object positions to be relative to the right side of the panel, set the value of the right_stick key to true.
Use the --load option with the gconftool-2 command line tool to set the values of the default configuration source to the values in the my-panel-setup.entries 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 my-panel-setup.entries:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --load my-panel-setup.entries
Log out of the test user account.
The following sections describe how to assign mandatory or default values to look-and-feel preferences.
To set font preferences, you modify the values of two preference keys. The following table shows the keys to modify, and the part of the user interface to which the keys correspond:
GConf Location |
User Interface Component |
---|---|
/desktop/gnome/interface/font_name |
|
/apps/nautilus/preferences/desktop_font |
|
For example, to set Sans 12 as the mandatory application font, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory --type string --set /desktop/gnome/interface/font_name “Sans 12”
To set palatino 12 as the default desktop object font, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --type string --set /apps/nautilus/preferences/desktop_font “palatino 12”
To set preferences for the desktop background, you modify the values of the preference keys in the /desktop/gnome/background location. For example, to set a mandatory image for the background, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory --type string --set /desktop/gnome/background/picture_filename filename.png
To set a default value for this preference, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --type string --set /desktop/gnome/background/picture_filename filename.png
You can also set other background preferences. For information about the other background preferences, see the desktop_gnome_background.schemas schema definition file.
To set splash image preferences, you modify the value of the preference keys in the /apps/gnome-session/options/ location. For example, if you do not want users to see a splash image, set a mandatory value as follows:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory --type bool --set /apps/gnome-session/options/show_splash_screen false
To set a default value for this preference, execute the following command:
# gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --type bool --set /apps/gnome-session/options/show_splash_screen false
You can also set other splash image preferences. For information about the other splash image preferences, see the gnome-session.schemas schema definition file.
To restore the default preference values for a user, execute the following command:
# gconftool-2 --direct --config-source user-configuration-source --recursive-unset
Replace user-configuration-source with the configuration source in the .gconf directory in the home directory of the user. For example:
# gconftool-2 --direct --config-source xml:readwrite:$(HOME)/.gconf --recursive-unset
This command resets the values of all preference keys, in all subdirectories, from the user setting to the setting in the default configuration source.