Desktop files: putting your application in the desktop menus
To run applications from GNOME, users click on icons on their desktops or they select the applications which they want to run from a menu. Therefore, the first step in integrating an existing program with GNOME is to register it with the set of applications that users can run.
Unlike in Windows or Mac OS, in GNOME the user's menus are automatically constructed from the list of registered applications. Each published application specifies a set of categories to which it belongs, and the systems menu configuration sorts and arranges them. This mechanism follows the freedesktop.org desktop entry and menu standards.
Though common in other desktops, creating your own application-specific submenu is not recommended. Instead, provide one menu item for each application you ship. Extra items such as help files, READMEs or links to your web site should be embedded into the application itself.
In GNOME and other freedesktop.org-compliant desktops, an application gets registered into the desktop's menus through a desktop entry, which is a text file with the .desktop extension. This desktop file contains a listing of the configurations for your application. The desktop takes the information in this file and uses it to:
- put the application in the Desktop Menu Specification. . To find a list of valid categories, take a look into FreeDesktop.org's
- list the application in the Run Application dialogue
- create appropriate launchers in the menu or on the desktop.
- associate the name and description of the application.
- use the appropriate icon.
- recognise the MIME types it supports for opening files.
To add a menu entry for your application, create a desktop file. It should have a unique filename, and there are no length limits so avoid abbreviations and feel free to include brand names. However, don't put spaces or international characters in the file name. For instance, "foocorp-painter-pro.desktop" would be a good filename to choose but "fcpp.desktop" would be a bad name, as would "FooCorp Painter Pro.desktop". The file should be UTF-8 encoded, and should resemble the following template:
[Desktop Entry] Name=FooCorp Painter Pro Exec=foocorp-painter-pro Icon=foocorp-painter-pro Type=Application Categories=GTK;GNOME;Utility;
These desktop files contain metadata about your application, and play a central role in integrating the program with the GNOME and other standards compliant desktops. The template presented here is the most basic possible. The file can be linguistically translated so your applications name can appear in the user's native language.
Place this file in the /usr/share/applications directory so that it is accessible by everyone, or in ~/.local/share/applications if you only wish to make it accessible to a single user. Which is used should depend on whether your application is installed systemwide or into a user's home directory. GNOME monitors these directories for changes, so simply copying the file to the right location is enough to register it with the desktop. 1
Each working desktop file needs to follow the same format. A minimal example of a desktop file is shown in Example 1-1. The file is split into sections, each starting with the section descriptor in square brackets. In this example, only one section is shown as that is the essential section to integrating your application to the desktop. Within each section, the part of each line before the equal sign is the key while the second half is the value. An explanation of each line is shown in Table 1-1.
Other than the first line identifying the desktop file, the order of the lines is not important. In Example 1-1, the line Type=Application could be the second row, the fifth row, or the last row and the result would be the same.
However, the keys are case-sensitive. Type=Application is not the same as type=Application or TYPE=Application.
[Desktop Entry] Type=Application Encoding=UTF-8 Name=Sample Application Name Comment=A sample application Exec=application Icon=application.png Terminal=false
|[Desktop Entry]||The first line of every desktop file and the section header to identify the block of key value pairs associated with the desktop. Necessary for the desktop to recognise the file correctly.|
|Type=Application||Tells the desktop that this desktop file pertains to an application. Other valid values for this key are Link and Directory.|
|Encoding=UTF-8||Describes the encoding of the entries in this desktop file.|
|Name=Sample Application Name||Names of your application for the main menu and any launchers.|
|Comment=A sample application||Describes the application. Used as a tooltip.|
|Exec=application||The command that starts this application from a shell. It can have arguments.|
|Icon=application.png||The icon name associated with this application.|
|Terminal=false||Describes whether the application should run in a terminal.|
1.1.1. Starting your application
If your application can take command line arguments, you can signify that by using the fields as shown in Table 1-2.
|%f||a single filename.|
|%u||a single URL.|
|%d||a single directory. Used in conjunction with %f to locate a file.|
|%D||multiple directories. Used in conjunction with %F to locate files.|
|%n||a single filename without a path.|
|%N||multiple filenames without paths.|
|%k||a URI or local filename of the location of the desktop file.|
|%v||the name of the Device entry.|
1.1.2. Foreign languages
To create localised names and comments, additional lines for each locale need to be added. For example, to add a Swedish version of the comment, add the following line:
There is no limit to the number of translations in the file.
Since maintaining a long list of translations in a file is cumbersome, a better way to create these translations is to use the intltool package. See the man pages for intltool-extract and intltool-merge for more information.
Desktop Entry Specification — Specifications for creating a desktop file.
Note that the ~/.local/share/applications location is not monitored by versions of GNOME prior to version 2.10 or on Fedora Core Linux, prior to version 2.8. These versions of GNOME follow the now-deprecated vfolder standard, and so desktop files must be installed to ~/.gnome2/vfolders/applications. This location is not supported by GNOME 2.8 on Fedora Core nor on upstream GNOME 2.10 so for maximum compatibility with deployed desktops, put the file in both locations.
Note that the KDE Desktop requires one to run kbuildsycoca to force a refresh of the menus.