# Customizing Menus

The information in this chapter describes how the GNOME Desktop implements menus and how you can customize menus.

## Introduction to Menus

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 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`:

1. 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.

2. 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.

3. Use the first `applications.menu` file found.

You can see an example of a `.menu` file in example-menu. 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 menustructure-desktopentry.

### 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 -->

menustructure-xmlmenu describes some of the elements in `.menu` files. For a more detailed description, please see the XDG menu specification.

## 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.

## 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

menustructure-TBL-7 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 Keys

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

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

menustructure-TBL-15 describes the most important keys in directory entry files.

## Directory Entry Keys

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`.

## Editing System Menus

You can edit menu configuration files and menu data files manually to customize menus.

### Adding Menus

To add a menu for all users, perform the following steps:

1. 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 menustructure-14.

2. Locate the `$XDG_CONFIG_DIRS/menus/applications.menu` file.

3. In the `.menu` file, add a `<Menu>` element for the new menu. For more information on `.menu` files, see menustructure-13.

4. Create a `<Name>` element below `<Menu>`. The content of the element should contain the name for the menu.

5. Create a `<Directory>` element below `<Menu>`. The content of the element should contain the name of the directory entry file.

6. See menustructure-4 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 Menu

To add an item to a menu for all users, perform the following steps:

1. Create a desktop entry file for the item that you want to add. For more information on desktop entry files, see menustructure-desktopentry.

2. Place the desktop entry file in the `$XDG_DATA_DIRS/applications` folder.

3. Locate the `$XDG_CONFIG_DIRS/menus/applications.menu` file.

4. 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 Menu

To edit the properties of a menu for all users, perform the following steps:

1. Locate the `$XDG_CONFIG_DIRS/menus/applications.menu` file.

2. 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.

3. Locate the directory entry for this menu. Modify the contents to change the properties of the menu. For more information on `.directory` files, see menustructure-14.

### Editing a Menu Item

To edit a menu item, perform the following steps:

1. Locate the desktop entry in the `$XDG_DATA_DIRS/applications` directory that corresponds to the menu item.

2. Edit the desktop entry to change the properties of the menu item. For more information on desktop entry files, see menustructure-desktopentry.

### Deleting an Item from a Menu

To delete an item from a menu for all users:

1. Locate the `$XDG_CONFIG_DIRS/menus/applications.menu` file.

2. Find the `<Menu>` element in this file that contains the desktop entry you want to delete.

3. Insert an `<Exclude>` element after the closing tag for the `<Include>` element. Make sure this is in the `<Menu>` element determined in step 2.

4. 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. menustructure-deleteitem 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 Merging

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 menustructure-13. 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 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

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.

menustructure-systemmerge 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 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.