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_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:
- 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 Esimerkki 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 Kappale 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 -->
Taulukko 2.1 describes some of the elements in .menu files. For a more detailed description, please see the XDG menu specification.
Element | Kuvaus |
---|---|
<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. |