XDG menu system policy

What links here (1) →

ROSA Linux uses standard XDG menu system, already implemented natively in GNOME, KDE, Rox and supported by various ISV.

XDG menu system in details

Files used

The menu system consists of three types of files:

• *.menu files, which define the menu structure. They are found in subdirectories from XDG_CONFIG_DIRS/menus (XDG_CONFIG_DIRS environment variable; directories list separated by a colon; default search path is ~/.config/menus and /etc/xdg/menus). The most important file is applications.menu. It defines the standard menu structure. This file is packaged in desktop-common-data package and should not be modified. Any changes from ISV should be done using additional .menu files placed in XDG_CONFIG_DIRS/menus/applications-merged.

• *.directory files, which define menu directories name and icon. They are found in subdirectories from XDG_DATA_DIRS/desktop-directories (XDG_DATA_DIRS environment variable; directories list separated by colon; default search patch is ~/.local/share/desktop-directories and /usr/share/desktop-directories).

• *.desktop files, which define menu entries. They are found in subdirectories from XDG_DATA_DIRS/applications.

Dealing with XDG menu system in packages

All packages with graphical applications should be shipped with a .desktop file. Packages that add submenus should ship with .menu and .directory files.

Menu entry

Specification for .desktop file is available here.

When an application comes without a .desktop file the following should be added in %install

mkdir -p %{buildroot}%{_datadir}/applications
cat > %{buildroot}%{_datadir}/applications/rosa-%{name}.desktop <<EOF
[Desktop Entry]
Name=Foo
GenericName=Video player
Comment=Foo does special things
Exec=%{_bindir}/%{name} 
Icon=%{name}
Terminal=false
Type=Application
StartupNotify=true
MimeType=foo/bar;foo2/bar2;
Categories=GNOME;GTK;AudioVideo;Audio;Video;Player;
EOF

When the application already ships a .desktop file, the spec file should add missing information in %install:

desktop-file-install \
  --add-category="GTK" \
  --remove-category="Qt" \
  --add-mime-type="foo/bar" \
  --add-only-show-in="KDE" \
  --dir %{buildroot}%{_datadir}/applications %{buildroot}%{_datadir}/applications/*

Notice: option --vendor="" is not mandatory.

If the application supports file or url as arguments, the following keys should be added to the Exec line (see here for complete list),

• if no file can be added, don't add anything
• if only one file can be added as argument : %f
• if several files can be added as argument : %F
• if one url can be added as argument : %u
• if several urls can be added as argument : %U

For Icon , neither an extension nor path should be specified as long as icons are stored in the default icon path.

If the application can manage some mimetypes, they should be added in the MimeType field, separated by semi-colon (and the list must finish with a semi-colon).

Explanations about mimetypes are available here.

If the application is not a graphical one and must be run in a terminal, the Terminal key should be set to true and the ConsoleOnly key should be added to Categories.

If the application doesn't support the startup notification mechanism (i.e. a clock cursor is being displayed until the application is displayed on screen), the StartupNotify key should be set to false.

The Categories field must be filled with an entry based on the ROSA menu section, as listed here and should be filled with more category fields characterizing the application, using the registered keys from the standard list here. Currently, applications.menu shipped with ROSA makes use only of ROSA Categories. However, if you intend to place a menu entry in some new category you must supply a .menu and a .directory file and add your category of Category . Gtk applications should add a GTK key. Same for KDE applications (KDE), GNOME applications (GNOME), Qt applications (Qt), Motif applications (Motif), text-only applications (ConsoleOnly) and Java applications (Java).

For an application to appear only in one or in a list of desktop environments, the OnlyShowIn key should be added, with the possible values (separated by semi-colon): KDE, GNOME, ROX, XFCE.

Menu directory

When application needs submenu that is not in ROSA Categories then the following should be added in %install:

mkdir -p %{buildroot}/etc/xdg/menus/applications-merged
cat > %{buildroot}/etc/xdg/menus/applications-merged/%{name}.menu << EOF
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">
<Menu>
    <Name>ROSA Linux</Name>
    <Menu>
        <Name>More Applications</Name>
        <Menu>
            <Name>System</Name>
            <Menu>
                <Name>Foo</Name>
                <Directory>rosa-%{name}.directory</Directory>
                <Include>
                    <Category>%{title} or something else</Category>
                </Include>
            </Menu>
        </Menu>
    </Menu>
</Menu>
EOF

mkdir -p %{buildroot}%{_datadir}/desktop-directories
cat >
%{buildroot}%{_datadir}/desktop-directories/rosa-%{name}.directory <<
EOF
[Desktop Entry]
Encoding=UTF-8
Name=%{title}
Icon=%{name}
Type=Directory
EOF

This way the application will add its submenu to More Applications->System.

Desktop file validation

Since a recent version of xdg tools desktop files have to follow some more standardization. The XDG system used in ROSA checks the file encoding which must be UTF-8 and the presence of an extension after the icon name (which must NOT be present).

You will have build error when desktop-file-install is invoked on a non-compliant desktop file.

To remove an icon extension :

• sed -i -e 's/^Icon=%{name}.png$/Icon=%{name}/g' %{buildroot}%{_datadir}/applications/*

---

Note:

This Policy is based on the Mandriva XDG menu system policy.