Customizing MenusThe information in this chapter describes how the GNOME Desktop
implements menus and how you can customize menus.Introduction to MenusmenusintroductionThe GNOME Desktop implements menus according to the XDG menu
specification. By supporting this specification, GNOME allows you
to:Customize the menu hierarchy easily. You can edit a small number
of files to customize the menu hierarchy. You do not need to modify
your applications or move files.Install applications easily. You do not need to provide
information about the menu hierarchy to applications when you install
the applications.Configure menus so that users cannot modify the menus.Menus in the GNOME Desktop use the following components:Menu definition filesDesktop entry filesDirectory entry filesMenu Definition Filesmenu definition files.menu filesmenu definition filesMenu 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_DIRS$XDG_CONFIG_DIRS is the environment variable defined in the
XDG
base directory specification. 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:Search each directory in $XDG_CONFIG_HOME in
order to find /menus/applications.menu. If
$XDG_CONFIG_HOME is not set, default to
~/.config/Search each directory in $XDG_CONFIG_DIRS in
order to find /menus/applications.menu. If
$XDG_CONFIG_DIRS is not set, default to
/etc/xdg/Use the first applications.menu file
found.You can see an example of a .menu file in . 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 .Example of a .menu file<!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 -->
describes some of the
elements in .menu files. For a more detailed
description, please see the XDG menu
specification.
Menu Definition File ElementsElementDescription<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.
Desktop Entry Filesdesktop entry files.desktop filesdesktop entry filesA 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_DIRS$XDG_DATA_DIRS is the environment variable defined in the XDG base
directory specification. 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[ar]=آلة حاسبة
...
Comment=Perform calculations
Comment[ar]=تأدية حسابات
...
Exec=gcalctool
Icon=gnome-calculator
Terminal=false
Type=Application
StartupNotify=true
Categories=GTK;GNOME;Application;Utility; 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 KeysDesktop Entry KeyDescriptionEncodingSpecifies the encoding of the desktop
entry file. NameSpecifies the name of the item. This
name is displayed on the item in the menu. CommentSpecifies a short description of the
item. The comment is displayed as a tooltip when you point to the
item in the menu. ExecSpecifies a command to execute when you
choose the item from the menu. IconSpecifies the
filename of an icon that represents the item. Does not specify the
path to the filename, or the file extension. TerminalSpecifies 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.TypeSpecifies the type of
item. This value is one of the following: Application: An item that starts an
application.Link: An item that links to a file,
folder, or a remote resource (such as a FTP site, a web
page, a Windows share...).FSDevice: An item that is a file
system device.Directory: An item that is a
Directory.CategoriesSpecifies 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 the following URL:
http://www.freedesktop.org/Standards/menu-specMenu
Definition Files map desktop entries to menus by using
matching rules against the Categories key.MimeTypeSpecifies the MIME types
For more information on the keys in desktop entry files, see the
desktop entry specification at the following URL:http://www.freedesktop.org/Standards/desktop-entry-specPanel 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.Directory Entry Filesdirectory entry files.directory filesdirectory entry filesA 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 at
$XDG_DATA_DIRS/desktop-directories/. 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=Accessories
Comment=Accessories menu
Icon=gnome-util.png
Type=Directory describes the most important
keys in directory entry files.
Directory Entry KeysDirectory Entry KeyDescriptionNameSpecifies the name of
the menu. This name is displayed on the menu. CommentSpecifies a short
description of the menu. The comment is displayed as a tooltip
when you point to the menu. IconSpecifies the
filename of an icon that represents the menu. Does not specify the
path to the filename, or the file extension. TypeSpecifies the type of menu. The value of
this key is always Directory.
Editing System MenusmenuseditingYou can edit menu configuration files and menu data files manually
to customize menus.Adding MenusmenusaddingTo add a menu for all users, perform the following steps:Create a directory entry file for the item that you want to
add. Place the directory entry file in the
$XDG_DATA_DIRS/desktop-directories/
directory. For more information on directory entry files, see .Locate the
$XDG_CONFIG_DIRS/menus/applications.menu
file.In the .menu file, add a
<Menu> element for the new menu. For more
information on .menu files, see .Create a <Name> element below
<Menu>. The content of the element should
contain the name for the menu.Create a <Directory> element below
<Menu>. The content of the element should
contain the name of the directory entry file.See for how to add an item
to the menu.The next time that users log in, the menu should appear in the
menu bar.Missing Menu?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.Adding an Item to a Menumenusadding items toTo add an item to a menu for all users, perform the following
steps:Create a desktop entry file for the item that you want to add.
For more information on desktop entry files, see .Place the desktop entry file in the folder
$XDG_DATA_DIRS/applications/Locate the
$XDG_CONFIG_DIRS/menus/applications.menu
file.Verify that a <Menu> element contains
an <Include> element with a matching rule
that selects the desktop entry file made in step 1.The next time that users log in, the menu item is in the assigned
location.Editing the Properties of a Menumenusediting properties ofTo edit the properties of a menu for all users, perform the
following steps:Locate the
$XDG_CONFIG_DIRS/menus/applications.menu
file.Find the <Menu> entry in this file
that corresponds to the menu you want to modify. Note the filename
of the directory entry in the <Directory>
element.Locate the directory entry for this menu. Modify the contents
to change the properties of the menu. For more information on
.directory files, see .Editing a Menu Itemmenusediting menu itemsTo edit a menu item, perform the following steps:Locate the desktop entry in
$XDG_DATA_DIRS/applications/
corresponding to the menu item.Edit the desktop entry to change the properties of the menu
item. For more information on desktop entry files, see .Deleting an Item from a Menumenusdeleting menu itemsTo delete an item from a menu for all users:Locate the
$XDG_CONFIG_DIRS/menus/applications.menu
file.Find the <Menu> element in this file
that contains the desktop entry you want to delete.Insert an <Exclude> element after the
closing tag for the <Include> element. Make
sure this is in the <Menu> element
determined in step 2.Insert the <Filename> matching rule
as a subelement of <Exclude> to
specifically exclude a desktop entry.The next time that users log in, the menu item is not displayed in
the menu. shows how this
done in the applications.menu file. The desktop
entry for dasher.desktop is explicitly excluded
from showing up in the accessibility menu.Deleting an Item from a Menu<!-- ... -->
<Menu>
<Name>Accessibility</Name>
<Directory>Accessibility.directory</Directory>
<Include>
<And>
<Category>Accessibility</Category>
<Not><Category>Settings</Category></Not>
</And>
</Include>
<Exclude>
<Filename>dasher.desktop</Filename>
</Exclude>
</Menu>
<!-- ... -->
Editing User Menus and Menu Mergingmenusediting user menusYou can use the following GNOME Desktop applications to edit menus
for users:GNOME Menu EditorA simple menu editor is available for users to edit their menus. For
more information, see Working With Menus in the
GNOME User Guide. Alternatively, you
can manually create and edit a user menu file.To manually create a custom menu for a user, the
$XDG_CONFIG_HOME/menus/applications.menu
must exist. In the case that $XDG_CONFIG_HOME is not set,
the default ~/.config/ is used. Since this is the
first location that is searched for the
applications.menu file, it takes precedence over all
other menu files.User menus can contain all the elements described in . For a complete list of the elements
allowed, see the XDG menu
specification.Since user menu files take precedence over the system menu file, it
will completely replace the system menu unless it explicitly
merges the system menu. Information on menu merging
is available in the following subsections.Merging the System Menumenusmerging the system menuOften, a user only wants to add or delete menu items in addition
to the standard system menu. To support single changes like these, it is
recommended that you use the <MergeFile>
element with the attribute type="parent" within the
user's applications.menu file.The <MergeFile> element allows a menu to
be merged with the contents of the user's menu file. When you specify
the attribute type="parent", then the contents of the
<MergeFile> element are ignored and the next
applications.menu file in
$XDG_CONFIG_DIRS/menus/ is used for
merging.Older SpecificationsOlder specifications did not include the type
attribute and simply required the location of the menu file to be
merged as the content of the <MergeFile>
element. As a result, you may still see a location specified in the
contents of <MergeFile>, even when
type="parent".The merging is performed as follows:The children of the root <Menu>
element in the merged menu fileMerged menu file refers to the next
applications.menu in
$XDG_CONFIG_DIRS/menus/ are substituted for the
<MergeFile> element in the base menu
file.All child <Menu> elements with the
same name are consolidated into a single
<Menu> element. This is by done appending
all child elements of each <Menu> element
with the same name into the last occurrence of
the menu element. shows an example of a
user menu file explicitly merging the system menu file.Merging the System Menu<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">
<Menu>
<Name>Applications</Name>
<MergeFile type="parent">/etc/xdg/menus/applications.menu</MergeFile>
<Menu>
<Name>Accessibility</Name>
<Exclude>
<Filename>dasher.desktop</Filename>
</Exclude>
</Menu>
</Menu>
Merging Arbitrary Menusmenusmerging arbitrary menusArbitrary menu files can be merged in much the same way as system
menus. The difference is that the type attribute must
be set to path or must be excluded from the
<MergeFile> element in order to do this type of
merge.The merge is performed in the same way except that the location of
the merged menu file is specified in the contents
of the <MergeFile> element.