The information in this chapter describes how to use GConf to manage user preferences.
GConf simplifies the administration of preferences for GNOME Desktop users. GConf enables system administrators to do the following:
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:
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 GNOME Desktop 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:
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 /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 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 include "$(HOME)/.gconf.path" include /etc/gconf/2/local-defaults.path xml:readwrite:$(HOME)/.gconf 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 Configuration Editor to modify the user configuration source. |
| 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:
The include instructions in the GConf path file enable system administrators 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. |
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:
| Item | Description |
|---|---|
| Preference key | An element in the GConf repository that corresponds to an application preference. |
| Schema key | A key that stores a schema object for a preference key. |
| Schema object |
An element in a configuration source that contains information for a preference key, such as the following:
|
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 GNOME Desktop user interface. For example, system_http_proxy.schemas corresponds to the Network Proxy preference tool. Other schema definition files contain preference keys that are not present in the GNOME Desktop user interface. For example, the /apps/panel/global/tooltips_enabled key is not present in the user interface.
Some parts of the GNOME Desktop user interface contain preferences that represent preference keys from more than one schema definition file. For example, the Keyboard 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. 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:
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, run the following command:
gconftool-2 --shutdownGConf includes a command line tool, gconftool-2. You can use the gconftool-2 command to perform the following tasks:
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/gnomeBelow are listed some of the options that you can use with the gconftool-2 command. For detailed command line options, please see man:gconftool-2(1).
Lists all subdirectories in a directory that you specify.
Displays the values of all keys in a directory that you specify.
Use this option with the --direct 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.
Use this option with the --config-source option to access a configuration source directly. When you use this option, GConf bypasses the server. Ensure that the GConf daemon, gconfd-2, is not running before you use this option.
Generates a list that contains all preference keys in a GConf repository directory that you specify. The list contains XML descriptions of all the keys. The list is contained in a <gconfentryfile> element.
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 --load option with this file.
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.
Displays a help message about the gconftool-2 command, and the options that you can use with the gconftool-2 command.
Use this option to sets the values of preference keys in the current directory in a configuration source to the values in the file that you specify. The file that you specify must contain XML descriptions of the keys, in a <gconfentryfile> element.
Use this option with the --set-schema option to specify a long description for a schema key.
Installs schema definition files to applications.
Use this option with the --set-schema option to specify an owner for a schema key.
Displays the values of all preference keys in all subdirectories in a directory that you specify.
Resets the values of all preference keys, in all subdirectories in a directory, from the user setting to the setting in the default configuration source.
Sets the value of a preference key, and writes the value to the user configuration source. Use the --type option with the --set option to specify the data type of the value that you want to set. For example, the following command sets the value of the /apps/gnome-terminal/profiles/Default/background_color key in the user configuration source:
gconftool-2 \
--set "/apps/gnome-terminal/profiles/Default/background_color" \
--type string "#000000"You can also use the --direct option and the --config-source option with the --set option to write a value to another configuration source.
Sets the value of an attribute in a schema key, and writes the value to the default configuration source.
Use the following options with the --set-schema option to specify the attribute that you want to update:
For example, the following command sets the short description in the schema key for the /apps/gnome-terminal/profiles/Default/background_color key:
gconftool-2 \
--set-schema "/schemas/apps/gnome-terminal/profiles/Default/background_color" \
--short-desc "Default background color of terminal"Use this option with the --set-schema option to specify a short description for a schema key.
Terminates the GConf daemon.
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:
Resets the value of a preference key from the user setting to the setting in the default configuration source.
Displays a brief help message about the gconftool-2 command, and the options that you can use with the gconftool-2 command.
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 valueFor example, to set wwwproxy.xyz.com as the mandatory HTTP proxy host, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
--type string \
--set /system/http_proxy/host wwwproxy.xyz.comThe 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, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.defaults \
--type int \
--set /apps/metacity/general/num_workspaces 5The 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, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
--type string \
--set /system/http_proxy/host proxy-nameTo set a default value for the HTTP proxy host, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.defaults \
--type string \
--set /system/http_proxy/host proxy-nameYou can also set other HTTP proxy-related preferences. For information on the other HTTP proxy preferences, see the system_http_proxy.schemas schema definition file.
To set print manager preferences, you modify the values of the preference keys in the /apps/gnome-print-manager location. For example, if you do not want users to view the print jobs of other users, set a mandatory value as follows:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
--type bool \
--set /apps/gnome-print-manager/show_all_jobs falseTo set a default value for this preference, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.defaults \
--type bool \
--set /apps/gnome-print-manager/show_all_jobs falseYou can also set other print manager preferences. For information on the other print manager preferences, see the gnome-print-manager.schemas schema definition file.
To set a mandatory number of workspaces, use the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
--type int \
--set /apps/metacity/general/num_workspaces integerTo set a default number of workspaces, use the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.defaults \
--type int \
--set /apps/metacity/general/num_workspaces integerYou can also set other window manager preferences. For information on 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, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
--type bool \
--set /desktop/gnome/accessibility/keyboard/enable trueTo set a default value for this preference, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.defaults \
--type bool \
--set /desktop/gnome/accessibility/keyboard/enable falseYou can also set other keyboard accessibility preferences. For information on 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, run 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 on 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 GNOME Desktop:
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 on the panel-default-setup.entries file, see the next section.
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 on how to set preferences for panels and objects on panels, see Section 1.6.6.2 ― 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:
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:
The keys also assign identifiers to each panel, panel object, and applet. For example, the following sample from panel-default-setup.entries specifies that one panel appears in the GNOME Desktop:
<entry>
<key>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 bottom edge panel.
Keys that specify the properties of the panels. The panel property keys are structured as follows:
/apps/panel/default_setup/toplevels/panel-name/panel-property-key
For example, the key /apps/panel/default_setup/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:
<entrylist base="/apps/panel/default_setup/objects/main_menu">
<entry>
<key>object_type</key>
<schema_key>/schemas/apps/panel/objects/object_type</schema_key>
<value>
<string>menu-object</string>
</value>
</entry>
<entry>
<key>toplevel_id</key>
<schema_key>/schemas/apps/panel/objects/toplevel_id</schema_key>
<value>
<string>bottom_panel</string>
</value>
</entry>
<entry>
<key>position</key>
<schema_key>/schemas/apps/panel/objects/position</schema_key>
<value>
<int>0</int>
</value>
</entry>
<!-- Possibly more entry elements -->
</entrylist>Keys that specify the applets, the applet preferences, and the panels in which the applets reside. For example, the following sample from panel-default-setup.entries specifies the Window List applet, in the bottom panel:
<entrylist base="/apps/panel/default_setup/applets/window_list">
<entry>
<key>object_type</key>
<schema_key>/schemas/apps/panel/objects/object_type</schema_key>
<value>
<string>bonobo-applet</string>
</value>
</entry>
<entry>
<key>toplevel_id</key>
<schema_key>/schemas/apps/panel/objects/toplevel_id</schema_key>
<value>
<string>bottom_panel</string>
</value>
</entry>
<entry>
<key>position</key>
<schema_key>/schemas/apps/panel/objects/position</schema_key>
<value>
<int>2</int>
</value>
</entry>
<!-- Possibly more entry elements -->
<entry>
<key>bonobo_iid</key>
<schema_key>/schemas/apps/panel/objects/bonobo_iid_type</schema_key>
<value>
<string>OAFIID:GNOME_WindowListApplet</string>
</value>
</entry>
</entrylist>The OAFIID is a unique identifier for an applet. To find the OAFIID for a particular applet, see the .server file for the applet in the /usr/lib/bonobo/servers directory. For example, the following excerpt from GNOME_Wncklet_Factory.server shows the OAFIID for the Window List applet:
<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 GNOME session, and 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 > my-panel-setup.entriesOpen 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.entriesThe 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 | Font preference tool, Application font option |
| /apps/nautilus/preferences/desktop_font | Font preference tool, Desktop font option |
For example, to set Sans 12 as the mandatory application font, run 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, run 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, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
--type string \
--set /desktop/gnome/background/picture_filename filename.pngTo set a default value for this preference, run the following command:
gconftool-2 --direct \
--config-source xml:readwrite:/etc/gconf/gconf.xml.defaults \
--type string \
--set /desktop/gnome/background/picture_filename filename.pngYou can also set other background preferences. For information on 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 ever 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 falseTo set a default value for this preference, run 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 falseYou can also set other splash image preferences. For information on the other splash image preferences, see the gnome-session.schemas schema definition file.
To restore the default preference values for a user, run the following command:
gconftool-2 --direct \
--config-source user-configuration-source \
--recursive-unsetReplace user-configuration-source with the configuration source in the .gconf directory in the home directory of the user.
This command resets the values of all preference keys, in all subdirectories, from the user setting to the setting in the default configuration source.
The information in this chapter describes how the GNOME Desktop implements menus and how you can customize menus.
The GNOME Desktop implements menus according to the XDG menu specification. By supporting this specification, GNOME allows you to:
Menus in the GNOME Desktop use the following components:
Menu files define the hierarchy of menus that are used in the GNOME menu bar. By modifying these files, you can customize menus for all users, or for a single user depending on the location of the applications.menu file that you modify.
Menu files must reside at $XDG_CONFIG_DIRS/menus/applications.menu. If $XDG_CONFIG_DIRS1 is not set, then the default path /etc/xdg is used. This also implies that a user specific version may be located at $XDG_CONFIG_HOME/menus/applications.menu which is searched first. If $XDG_CONFIG_HOME is not set, then the default path ~/.config is used. Directories which appear first in $XDG_CONFIG_DIRS are given precedence when there are several applications.menu files. The first file found is used and subsequent files are ignored.
If you are confused about the order in which paths are searched, here is a simple list for resolving the location of applications.menu:
You can see an example of a .menu file in Example 2-1. In this example, the top level menu is named Applications, which is specified using the <Name> element. The Applications menu contains a single submenu, but several submenus are allowed. Each submenu may also have an <Include> element. The purpose of the <Include> element is to perform a filter on the set of available desktop entries using matching rules.
For example, the <Category> element is a basic matching rule that selects a desktop entry only if the Categories key contains the content of the <Category> element. In the example, the Accessories menu will include a desktop entry only if it contains “Utility” but not “System” in the Categories key. For more information on the Categories key, see Section 2.3 ― Desktop Entry Files.
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
<Name>Applications</Name>
<Directory>Applications.directory</Directory>
<!-- Read standard .directory and .desktop file locations -->
<DefaultAppDirs/>
<DefaultDirectoryDirs/>
<!-- Accessories submenu -->
<Menu>
<Name>Accessories</Name>
<Directory>Accessories.directory</Directory>
<Include>
<And>
<Category>Utility</Category>
<Not>
<Category>System</Category>
</Not>
</And>
</Include>
</Menu> <!-- End Accessories -->
<!-- possibly more submenus -->
</Menu> <!-- End Applications -->
Table 2-1 describes some of the elements in .menu files. For a more detailed description, please see the XDG menu specification.
| Element | Description |
|---|---|
| <Menu> | The root element which may contain nested <Menu> elements that define submenus. How these elements are nested determines the menu structure. |
| <Name> | Specifies the name of the menu. Every <Menu> element must contain a <Name> element. |
| <Directory> | Specifies the name of the directory entry file that specifies the name, comment, and icon for the menu. If this element is not specified, then the <Name> element is to be used to display the menu name. By default, .directory files are searched for in the location $XDG_DATA_DIRS/desktop-directories/ as set forth in the XDG menu specification. |
| <DefaultAppDirs> | This is an instruction which indicates that all the available desktop entries from $XDG_DATA_DIRS/applications/ should be scanned. If this instruction is not included, then these locations are not scanned for desktop entries. |
| <DefaultDirectoryDirs> | This is an instruction which indicates that all the available directory entries from $XDG_DATA_DIRS/desktop-directories/ should be scanned. If the instruction is not included, then these locations are not scanned for directory entries. |
| <Include> | Contains a list of matching rules by which the contents of a menu are generated. May include the <Filename>, <Category>, <And>, <Or>, <Not>, or <All> matching rules. If more than one rule is present, the rules are logically ORed so that desktop entries that match any rule are included. |
| <Exclude> | The opposite of <Include> since any desktop entries that are matched in this element are excluded from the previous set of included elements. For this reason, this element must appear after the <Include> element. |
| <Filename> | A matching rule that selects a desktop entry when the Desktop File-Id matches the contents of the <Filename> element. |
| <Category> | A matching rule that selects a desktop entry when the Categories key matches the contents of the <Category> element. |
| <And> | A matching rule that selects a desktop entry when it is selected by all the nested matching rules in the <And> element. |
| <Or> | A matching rule that selects a desktop entry when it is selected by any of the nested matching rules in the <Or> element. |
| <Not> | A matching rule that does not select a desktop entry when it is selected by any of the nested matching rules in the <Not> element. |
| <All> | A matching rule which selects all desktop entries. |
A desktop entry file is a data file that provides information about an item in a menu. The desktop entry file specifies the details for the item such as a name, a command to run, an icon, and so on. It also contains keywords which determine the location of the item in the menu hierarchy.
Desktop entry files must reside in the $XDG_DATA_DIRS/applications directory and must have a .desktop file extension. If $XDG_DATA_DIRS2 is not set, then the default path is /usr/share is used. This also implies that user specific desktop entries may be located at $XDG_DATA_HOME/applications which is searched first. If $XDG_DATA_HOME is not set, then the default path ~/.local/share is used. Desktop entries are collected from all directories in the $XDG_DATA_DIRS environment variable. Directories which appear first in $XDG_CONFIG_DIRS are given precedence when there are several .desktop files with the same name.
The following is a sample desktop entry file:
[Desktop Entry] Encoding=UTF-8 Name=Calculator Name[fr]=Calculatrice ... Comment=Perform calculations Comment[fr]=Effectue des calculs compliqués ... Exec=gcalctool Icon=accessories-calculator Terminal=false Type=Application StartupNotify=true Categories=GNOME;GTK;Utility;Calculator
Table 2-2 describes the most important keys in desktop entry files. To get more information about desktop entry files, see the XDG Desktop Entry Specification.
| Desktop Entry Key | Description |
|---|---|
| Categories | Specifies the keywords that describe the item. The keywords are separated with semicolons (;). To see a list of the standard category keywords, see the desktop menu specification at http://www.freedesktop.org/Standards/menu-spec Menu Definition Files map desktop entries to menus by using matching rules against the Categories key. |
| Comment | Specifies a short description of the item. The comment is displayed as a tooltip when you point to the item in the menu. |
| Encoding | Specifies the encoding of the desktop entry file. |
| Exec | Specifies a command to execute when you choose the item from the menu. |
| Icon | Specifies the filename of an icon that represents the item. Does not specify the path to the filename, or the file extension. |
| MimeType | Specifies the MIME types that the application can handle. |
| Name | Specifies the name of the item. This name is displayed on the item in the menu. |
| NoDisplay | This options means “This application exists, but don't display it in the menus”. |
| Terminal | Specifies whether the command in the Exec key runs in a terminal window. If the value is true the command runs in a terminal window. If the command does not create a window in which to run, the value of this key must be true. |
| Type | Specifies the type of item. This value is one of the following:
|
For more information on the keys in desktop entry files, see the desktop entry specification at the following URL:
Panel launchers and desktop objects also use desktop entry files. The desktop entry files for launchers and desktop objects provide the same information as for items in a menu. For example, the desktop entry files provide the command to run when a user chooses the launcher or object.
A directory entry file is a data file that provides information about a menu. The directory entry file specifies the details for the menu such as a name, a tooltip, and an icon. Directory entry files have a .directory file extension.
Directory entry files must reside in the $XDG_DATA_DIRS/desktop-directories directory. If $XDG_DATA_DIRS is not set, then the default path is /usr/share is used. This also implies that user specific directory entries may be located at $XDG_DATA_HOME/desktop-directories which is searched first. If $XDG_DATA_HOME is not set, then the default path ~/.local/share is used. Directory entries are collected from all directories in the $XDG_DATA_DIRS environment variable. Directories which appear first in $XDG_DATA_DIRS are given precedence when there are several .directory files with the same name.
The following is a sample directory entry file:
[Desktop Entry] Name=Graphics Name[fr]=Graphisme ... Comment=Graphics applications Comment[fr]=Applications graphiques ... Icon=gnome-graphics Type=Directory Encoding=UTF-8
Table 2-3 describes the most important keys in directory entry files.
| Directory Entry Key | Description |
|---|---|
| Name | Specifies the name of the menu. This name is displayed on the menu. |
| Comment | Specifies a short description of the menu. The comment is displayed as a tooltip when you point to the menu. |
| Icon | Specifies the filename of an icon that represents the menu. Does not specify the path to the filename, or the file extension. |
| Type | Specifies the type of menu. The value of this key is always Directory. |
You can edit menu configuration files and menu data files manually to customize menus.
To add a menu for all users, perform the following steps:
The next time that users log in, the menu should appear in the menu bar.
If you did not specify any matching rules in the <Include> element, or if the rule did not match any desktop entries, then you may not see the menu in the menu bar.
To add an item to a menu for all users, perform the following steps:
The next time that users log in, the menu item is in the assigned location.
To edit the properties of a menu for all users, perform the following steps:
To edit a menu item, perform the following steps:
To delete an item from a menu for all users:
The next time that users log in, the menu item is not displayed in the menu. Example 2-2 shows how thi