Desktop files: putting your application in the desktop menus

• Integrating existing software with GNOME
• Basic Integration

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 MacOS, in GNOME the users 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.

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

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

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.

[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=Sample Application Name
Comment=A sample application
Exec=application
Icon=application.png
Terminal=false