Menu Definition Files
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_DIRS[1] 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, it defaults to the
~/.config/ directory.
Search each directory in $XDG_CONFIG_DIRS in
order to find menus/applications.menu. If
$XDG_CONFIG_DIRS is not set, it defaults to the
/etc/xdg/ directory.
Use the first applications.menu file
found.
You can see an example of a .menu file in Example 2.1, “Example of a .menu file”. 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 the section called “Desktop Entry Files”.
Example 2.1. Example of a .menu file
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"https://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, “Menu Definition File Elements” describes some of the
elements in .menu files. For a more detailed
description, please see the XDG menu
specification.
Table 2.1. Menu Definition File Elements
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. |
