Issue #12 October 2005

Integrating your applications into the desktop,
Part 1

by Rosanna Yuen

Introducing freedesktop.org

Creating a perfect application is a wonderful feeling. Whether large or small, you want the desktop to recognize your application and interact appropriately with it. With multiple desktops available, it is best for your application to be able to integrate itself into as many as possible. Although no official rules have been adopted, there is a set of specifications available at freedesktop.org.

Although not a formal standards body, freedesktop.org maintains a set of informal but commonly agreed upon guidelines. When followed, these guidelines allow applications to be integrated onto compliant desktops.

Desktop files

The biggest step in integrating your application into the desktop is to create a desktop file. 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 Main Menu.
  • List the application in the Run Application... dialog.
  • Create appropriate launchers in the Menu or on the desktop.
  • Associate the name and description of the application.
  • Use the appropriate icon.
  • Recognize the MIME types it supports.

To allow the desktop to find your desktop file, create your file with the name application.desktop, using the name of your application. Place this file in the /usr/share/applications/ directory.

Each working desktop file needs to follow the same format. A minimal example of a desktop file is shown in Example 1, “Sample desktop file”. 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, “Line-by-line explanation”.

Note:
Other than the first line identifying the desktop file, the order of the lines is not important. In Example 1, “Sample desktop file”, 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
Example 1. Sample desktop file
Line Description
[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 recognize 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 Name 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.
Table 1. Line-by-line explanation

Starting your application

If your application can take command line arguments, you can signify them by using the fields as shown in Table 2, “Exec variables”.

Add... Accepts...
%f A single filename.
%F Multiple filenames.
%u A single URL.
%U Multiple URLs.
%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.
Table 2. Exec variables

Foreign languages

To create localized 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:

Comment[sv]=Exempelprogramnamn

There is no limit to the number of translations in the file.

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

Startup notification

Although the fields shown in the “Desktop files” section provide enough information for the desktop to recognize 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 notify 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 into 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.

Tip:
Regardless of toolkit, there is one type of application where you would have to manually handle feedback. Applications with remoting capabilities (where you tell an existing process to open a new window instead of starting a new process) cannot use the built-in mechanism. The value of the DESKTOP_LAUNCH_ID environment has to be passed by your application and has to notify the launching system of your new window. If you are using GTK+, the documentation for gdk_notify_startup_complete() has a bit more information.

Installing icons

In Example 1, “Sample desktop file”, we have specified the icon for this file as application.png. 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/. If you have only one icon, place it 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.

Tip:
Icons placed in the /usr/share/icons/hicolor/ directory should consist of neutral colors so as to not clash with any other theme.

Adding MIME types

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 into the MIME database. In the /usr/share/mime/packages/ directory, create an XML file with the format as shown in Example 2, “Sample file for registering a new MIME type”. 

<?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>
Example 2. Sample file for registering a new MIME type

In this example, replace the sample 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 filenames for identification.

Tip:
Because the magic command forces the computer to open the files to search for the string, the glob command is preferable.

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

update-mime-database /usr/share/mime

Tip:
For more information on choosing a good MIME extension and to register your MIME type, go to the IANA website.

Next time

Although this article can get you started with your desktop files, there are many other specifications at freedesktop.org that are useful in integrating applications to the desktop. Next month, we will discuss specifications for XDND, system tray, Xsettings, and intltool.

Further reading

About the author

Rosanna Yuen is an avid computer user who often finds herself surrounded by computer programmers. She co-wrote AisleRiot and is a dabbler in the GNOME project. In her spare time, she reads, knits, and experiments in her kitchen.