Integrating existing software with GNOME

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.

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:

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

In Example 1-1, we have specified the icon for this application as application.png. In order for this to work, we need to put that icon file in the correct directory.

The desktop looks for icons in the selected theme directory of /usr/share/icons/. Application icons should be available at least at a resolution of 48x48 pixels. Place the icon in /usr/share/icons/hicolor/48x48/apps/. This is the directory the desktop looks in if there is no icon for your application in the selected theme. If you have themed icons, put them in the appropriate directories.

To better visually integrate with the GNOME desktop, while keeping your application look native when run under KDE, Windows XP or Mac OS X, follow the Tango Style guidelines when creating your artwork. The document explains various aspects of icon design, including colours, lighting and sizes. Some typical workflow and video tutorials are also provided.

If your application can open specific MIME types, you need to let the desktop know in the desktop file. For example, if your application can accept PNG files, add the following line into your desktop file:

MimeType=image/png

Additional MIME types can be added by separating the different types with semicolons.

The system already knows of a large number of MIME types. However, if you are creating one of your own, you need to register your MIME type with the MIME database. In the /usr/share/mime/packages/ directory, create an XML file with the format as shown in Example 1-2.

<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
   <mime-type type="application/x-example">
     <comment>Example file type </comment>
     <magic priority="50">
       <match value="search-string" type="string" offset="10:140"/>
     </magic>
     <glob pattern="*.newextension"/>
   </mime-type>
</mime-info>

In this example, replace the example MIME type with the name of your MIME type. The magic section searches files for the search string for identification. The glob line uses the suffix of file names for identification.

Once your new MIME type is adequately described in the file, run the following in a shell:

update-mime-database /usr/share/mime

Although the fields shown in Section 1.1 ― Desktop files: putting your application in the desktop menus provide enough information for the desktop to recognise your application, there are other fields that may be useful for your particular case. One of these fields is startup notification.

When startup notification is set, the panel and cursor notifies the user that the application has started. When the application appears onscreen, the panel and cursor return to normal.

To let the launcher know your application supports startup notification, add the following line to your desktop file:

StartupNotify=true

This command in the desktop file enables the desktop to use whatever startup notification is built in to either your application or your toolkit. Most modern toolkits work transparently with the startup notification system. If you are not using a modern toolkit, the Startup Notification Spec has the details that you need to implement it yourself.

The GNOME file manager, Nautilus, can display little thumbnails tailored for each file instead of generic icons in its file lists. For example, a word processor document can be made to appear as a little version of the first page in the document. This is useful because users can see a small representation of the visible data in their files, which may aid in recalling what file they are looking for. You can make your application create these thumbnails with a few simple steps.

A thumbnailer is a program with no user interface that takes a file and a pixel size as inputs, and it writes a thumbnail for that file. GNOME determines which thumbnailer program to use based on the MIME type of the file for which a thumbnail is to be generated. The mapping between MIME types and thumbnailer programs is stored as a series of GConf keys.

For each MIME type which you want to handle, you have to create a pair of GConf keys:

That is, each MIME type requires two GConf keys (enable and command) under the same path. The path name can be derived from the MIME type name by substituting a "/" with "@". For example, a thumbnailer for image/x-my-format would need two keys: /desktop/gnome/thumbnailers/image@x-my-format/enable and /desktop/gnome/thumbnailers/image@x-my-format/command.

Within the command key, GNOME will look for percent sequences and substitute them with actual values:

Either of %i and %u must appear in your command, and %o is also mandatory. The %s substitution is optional, but we recommend that your thumbnailer pay attention to it.