Packaging/SUSE Package Conventions/Desktop Menu

From openSUSE

9. Desktop Menu

This section describes how desktop menus are supported on SUSE Linux. After an introduction, there is a section about the basic file format of .desktop files. The next sections define the exact format of such files on SUSE Linux and how they can be installed and updated. Finally, there is an overview of categories used to sort menu entries into submenus.

Almost all window managers allow starting applications from a menu. This menu is often static. Therefore SUSE added support into some window managers, so their menu offers only the applications that are actually installed.

Before SL 9.0, the desktop menus were updated by the SUSE-specific tool susewm. One of the problems was that the information about a menu entry (like name, icon, position in menu, or call to execute) was not stored in the package. It was stored in a database included in the package susewm and only SUSE's developers were able to register a new menu entry with an internal SUSE tool.

Since SL 9.0, SUSE Linux has switched to following the desktop menu specification as defined at http://freedesktop.org/Standards/menu-spec. The solution is based on .desktop files and is supported by KDE and GNOME out of the box. In addition, SUSE Linux provides the tool /usr/bin/xdg_menu, which is able to update desktop menus for some other window managers. It is included the package xdg-menu and actually provides support for WindowMaker, fvwm2, blackbox, and icewm.

9.1. Basic Format of the File

The desktop menu entries are stored in .desktop files. This section includes only some general information about such files. Refer to http://www.freedesktop.org/standards/desktop-entry-spec for more details.

The .desktop files are plain text files where information is sorted into groups. A group starts with the line:

[group_name]

All the following lines belong to the same group until another group is started or until the end of file.

The information is defined by {key,value} pairs the following way:

key=value

This example is taken from the file /usr/share/applications/xboard.desktop and defines a desktop menu entry for the game xboard:

[Desktop Entry]
Name=Xboard
Comment=Chess Game
Type=Application
Exec=xboard
Icon=xboard
Categories=Game;BoardGame;
X-SuSE-translate=true

9.2. Desktop Menu Entry

This section defines the exact format of .desktop files on SUSE Linux. The files follow the desktop entry specification, which is available at http://www.freedesktop.org/standards/desktop-entry-spec, extended by desktop menu specification, which is available at http://freedesktop.org/Standards/menu-spec. This section mentions only the most important or SUSE-specific information. Refer the official specification for more details.

The .desktop files use the suffix .desktop. They are encoded in UTF-8 and provide the following information in the group:

[Desktop Entry]

These keys are required:

• Type defines the type of the desktop entry. The value ”Application” must be used for desktop menu entries.
• Name defines the English string that appears in the menu.
• Exec defines the executable call. Absolute paths should be avoided if possible.
• Categories defines a category of the application. It is a ';' separated list. Supported categories are defined in Section 9.4 "Category List". The information is used to sort menu entries into submenus.
• X-SuSE-translate defines whether the keys Name and GenericName should be translated. Possible values are “true” and “false”. This key is automatically added by the %suse_update_desktop_file macro if missing. See also Section 9.3 "Installation and Update". The default value is “true”.

These keys are optional:

• Icon defines the icon connected with the application. The value is an icon name without a suffix or an absolute path to an icon. Only the .png and .xpm icons are supported. They must be installed according to the directory layout defined by the icon theme specification, either below $XDG_DATA_DIRS/icons or /usr/share/pixmaps/.
• Comment defines a comment that can be shown in a tool tip.
• Name[lang] defines a translation of the key Name into the language lang. The required encoding is UTF-8.
• Comment[lang] defines a translation of the key GenericName into the language lang. The required encoding is UTF-8.
• MimeType defines the mime types that can be handled by the application. The value is a semicolon-separated (;) list, so several mime types can be defined.
• OnlyShowIn defines that the menu entry is intended only for a specific desktop. Possible values include “GNOME”, “KDE” and “XFCE”.

This example is taken from /usr/share/applications/xemacs.desktop:

[Desktop Entry]
Name=X Emacs
Comment=Text Editor
Comment[cs]=Textov� editor
Comment[de]=Texteditor
Comment[fr]=Éditeur de texte
Comment[it]=Editor di testi
MimeType=text/english;text/plain;text/x-makefile;\
text/x-c++hdr;text/x-c++src;text/x-chdr;text/x-csrc;\
text/x-java;text/x-moc;text/x-pascal;text/x-tcl;\
text/x-tex;application/x-shellscript;text/x-c;text/x-c++;
Exec=xemacs %f
Icon=emacs
Type=Application
Terminal=false
StartupNotify=true
StartupWMClass=emacs
X-KDE-AuthorizeAction=shell_access
Categories=TextEditor
X-SuSE-translate=true

9.3. Installation and Update

The desktop menu specification allows searching several directories for .desktop files. These are searched on SUSE Linux:

• /opt/kde3/share/applications/
• /opt/gnome/share/applications/
• /usr/share/applications/

This means that the GNOME and KDE applications can install .desktop files into the usual locations. The menu entries are then automatically used also in all other supported window managers. However, this could be avoided if the desktop file includes OnlyShowIn=GNOME; or OnlyShowIn=KDE;. This also means the .desktop files installed by GNOME and KDE applications must follow the common rules defined in the previous section.

The macro %suse_update_desktop_file should be called for each installed .desktop file. It updates translations and makes some sanity checks. It can be used to change the category. It can even be used to install the .desktop files or to create a new one from scratch. This macro requires that the package update_desktop_files be installed. See Section 3.33 "%suse_update_desktop_file" for more details.

Packages with GNOME and KDE applications usually provides their own .desktop files, which are installed with make install. Then it is enough to call the macro %suse_update_desktop_file on it and mention the file in the %files section. This example is taken from the package kdclock:

BuildRequires: ... update-desktop-files ...
[...]

%install
[...]
%suse_update_desktop_file  %name Utility TimeUtility

%files
[...]
/opt/kde3/share/applnk/Utilities/kdclock.desktop

Other packages usually do not provide a .desktop file by default. A simple one can be created from scratch with the macro %suse_update_desktop_file itself. A more complicated .desktop file is usually added as an extra source. Then it is installed, checked, and updated by the macro %suse_update_desktop_file in the %install section. Finally, it is mentioned in the %files sections. This example is taken from the package xboard (even the missing icon is installed from an extra source):

BuildRequires: ... update-desktop-files ...
[...]
Source1:      %name.desktop
Source2:      %name.png
[...]

%install
[...]
mkdir -p $RPM_BUILD_ROOT/usr/share/pixmaps/
install -m 644 $RPM_SOURCE_DIR/%name.png \
               $RPM_BUILD_ROOT/usr/share/pixmaps
%suse_update_desktop_file -i %name Game BoardGame

%files
[...]
/usr/share/applications/%name.desktop
/usr/share/pixmaps/%name.png

The %suse_update_desktop_file macro searches the directories $RPM_SOURCE_DIR and /usr/share/update-desktop-files/templates for the desktop file source. The example above shows the usual solution where the .desktop file already has the same name as the package source and is found in the $RPM_SOURCE_DIR directory then.

See Section 3.33, "%suse_update_desktop_file" for more examples.

9.4. Category List

This section provides a list of categories used on SUSE Linux. They are needed to sort desktop menu entries into submenus. The list is based on the desktop menu specification, see http://freedesktop.org/Standards/menu-spec. In addition, there are also some SUSE-specific categories that are not currently part of the specification.

The SUSE-specific categories must be prefixed by "X-SuSE-". However, the prefix is not mentioned in the lists below because the situation is evolving and the categories are becoming part of the specification. The %suse_update_desktop_file macro adds the prefix where needed.

Some of the categories were renamed in the past. The obsolete names are mentioned in the lists below. They are automatically renamed by the %suse_update_desktop_file macro.

9.4.1. Development Categories

Use these together with the Development category as in Category=Development;IDE;.

• Building
• Debugger
• Design
• Documentation
• GUIDesigner
• IDE
• Profiling
• RevisionControl
• Translation

9.4.2. Education Categories

Use these together with the Education category, for example, Category=Education;Astronomy;.

• Art
• Astronomy
• Chemistry
• Construction
• Engineering
• Languages — obsoletes Language and X-KDE-Edu-Language
• Math
• Music
• School
• Science
• Teaching — obsoletes X-KDE-Edu-Teaching

9.4.3. Game Categories

Use these together with the Game category, as in Category=Game;ArcadeGame;.

• 3DGame
• ActionGame
• AdventureGame
• Amusement
• ArcadeGame
• BlocksGame
• BoardGame
• CardGame
• FirstPersonGame
• KidsGame
• LogicGame
• PlatformGame
• PuzzleGame
• RolePlaying — obsoletes RolePlayingGame
• Simulation — obsoletes SimulationGame
• SportsGame
• StrategyGame

9.4.4. Graphics Categories

Use these together with the Graphics category, for example, Category=Graphics;Viewer;.

• 2DGraphics
• 3DGraphics
• OCR
• Photograph
• RasterGraphics
• Scanning
• VectorGraphics
• Viewer

9.4.5. Internet Categories

Use these together with the Network category, as in Category=Network;Email;.

• Dialup — obsoletes DialUp
• Email
• FileTransfer
• HamRadio
• InstantMessaging
• IRCClient
• Monitor
• News — obsoletes Newsreader
• P2P
• RemoteAccess
• Telephony — obsoletes Telephone
• WebBrowser
• WebDevelopment

9.4.6. Multimedia Categories

Use these together with the AudioVideo category, for example, Category=Audiovideo;AudioMixer;.

• Midi
• Mixer — obsoletes AudioMixer
• Music
• AudioVideoEditing
• Player — obsoletes AudioVideoPlayer
• Recorder — obsoletes AudioVideoRecorder
• DiscBurning — obsoletes Burning
• CD
• Jukebox
• Sequencer
• Tuner
• TV

9.4.7. Office Categories

Use these together with the Office category, for example, Category=Office;Presentation;.

• ContactManagement — obsoletes AddressBook
• Calendar
• Database
• Dictionary
• Finance
• FlowChart
• Presentation
• ProjectManagement
• Spreadsheet
• Viewer
• Warehouse
• WordProcessor

9.4.8. Utility Categories

Use these together with the Utility category, as in Category=Utility;TextEditor;.

• Accessibility
• Applet
• Archiving
• Calculator
• DesktopUtility
• PDA
• PrintingUtility
• Security
• Shell
• SyncUtility
• Telephony
• TextEditor
• TimeUtility
• WebUtility
• XMLUtility

9.4.9. System Categories

Use these together with the System category, for example, Category=System;Emulator;.

• Applet
• Archiving
• Backup
• Database
• Documentation
• Emulator
• FileManager
• Filesystem
• HardwareSettings
• Monitor
• Network
• PackageManager
• RemoteAccess
• Screensaver
• Security
• Shell
• SystemSetup
• Telephony — obsoletes Telephone
• TerminalEmulator
• TrayIcon
• Utility