The information in this chapter describes how the GNOME Desktop implements menus and how you can customize menus. menus introduction The 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 files Desktop entry files Directory entry files menu definition files .menu files 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 $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, 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 . 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 . <!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. 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. desktop entry files .desktop files desktop entry files 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_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_DATA_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 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: 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. 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-spec 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. directory entry files .directory files directory entry files 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 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. menus editing You can edit menu configuration files and menu data files manually to customize menus. menus adding To 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. 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. menus adding items to To 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 $XDG_DATA_DIRS/applications folder. 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. menus editing properties of To 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 . menus editing menu items To edit a menu item, perform the following steps: Locate the desktop entry in the $XDG_DATA_DIRS/applications directory that corresponds to the menu item. Edit the desktop entry to change the properties of the menu item. For more information on desktop entry files, see . menus deleting menu items To 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. <!-- ... --> <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> <!-- ... --> menus editing user menus You can use the following GNOME Desktop applications to edit menus for users: GNOME Menu Editor A 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 directory 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. menus merging the system menu Often, 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 the $XDG_CONFIG_DIRS/menus directory is used for merging. Older 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 file Merged menu file refers to the next applications.menu in the $XDG_CONFIG_DIRS/menus directory. 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. <!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> menus merging arbitrary menus Arbitrary 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.