# Integrating existing software with GNOME

## Preface

GNOME is a project to build a complete desktop and development platform based entirely on free software. Many companies, governments, schools, institutions, and individuals have deployed the GNOME desktop on their systems. If you are a developer of third-party software ("Independent Software Vendor" or ISV, or "Independent Software Developer" (ISD) if you don't do it commercially), you may want to ensure that your existing software runs properly under GNOME. This guide explains how to integrate existing software with GNOME, without actually rewriting that software to explicitly use the GNOME platform libraries and development tools.

This guide will be useful in the following situations:

- You are a software developer or distributor who has an application that is not explicitly designed to work with GNOME, but you want to ensure that it runs comfortably within a GNOME desktop.

- You are a system administrator for an institution that has deployed GNOME desktops to its users. You also have legacy or in-house applications, and you want your users of GNOME to be able to access those applications comfortably.

- You are writing a GNOME application proper and you need a checklist of basic things to do to ensure that your application integrates well with the rest of the GNOME desktop.

In general, this guide is about integrating existing software into a GNOME desktop. On the other hand, if you are considering writing new software, we encourage you to develop it completely with GNOME as your target platform; please refer to the GNOME Developer's Site for more information.

One of the main concerns of GNOME is the user experience. Users should have a comfortable computing environment: this means having a complete desktop and a set of applications which operate together in a consistent way. With relatively little work, applications which are not written explicitly with GNOME in mind can be made to run comfortably within a GNOME desktop.

### Structure of this guide

This guide is structured as a list of tasks that you need to perform to integrate existing software with GNOME. The guide presents these tasks roughly in order of importance. For example, the task of adding your application to the GNOME desktop's menus appears before the task for adding drag-and-drop support. Also, this guide has an appendix with an integration checklist to aid you in evaluating your integration work.

### Standards and freedesktop.org

Many of the integration tasks in this guide rely on standards which are relevant to more than GNOME. Other desktop projects like the K Desktop Environment also use these standards: if you integrate your applications with GNOME, you should have to do little or no extra work to make them run in those other environments as well.

Creating a perfect application is a wonderful feeling. Whether large or small, you want the desktop to recognise your application and for them to interact appropriately. With multiple desktops currently available, it is best for your application to be able to integrate itself in as many of them as possible. Even though 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 on to compliant desktops.

## Basic Integration

This chapter teaches you about the very basic steps you should take to integrate a program into the GNOME desktop. These steps concern the following:

- Letting the user launch your application by making it appear in the desktop's panel menus, or any other launching mechanism in the desktop.

- Letting the desktop know which types of user-created files require your application to be launched.

- Letting the desktop know how to display the appropriate icons for your program and the files which your program creates.

### 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 Main Menu.

- 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]
    	Encoding=UTF-8
    	Name=FooCorp Painter Pro
    	Exec=foocorp-painter-pro
    	Icon=foocorp-painter-pro
    	Type=Application
    	Categories=Application;

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.

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.

Each working desktop file needs to follow the same format. A minimal example of a desktop file is shown in ex-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 tb-desktop-file.

Other than the first line identifying the desktop file, the order of the lines is not important. In ex-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`.

#### Sample desktop file

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

### Line-by-line explanation

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

#### Starting your application

If your application can take command line arguments, you can signify that by using the fields as shown in tb-exec-params.

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

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

`Comment[sv]=Exempelprogramnamn`

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.

#### References

Desktop Entry Specification — Specifications for creating a desktop file.

### Installing icons

In ex-sample-desktop-file, 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.

#### References

Icon Theme Specification — Describes how to install and look up icons in a themeable way.

Icon Naming Specification — Provides a canonical naming scheme for icon files.

Tango Style Guidelines — Provides description on how to design clean and 'multiplatform' icon artwork.

### 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 with the MIME database. In the `/usr/share/mime/packages/` directory, create an XML file with the format as shown in ex-mime-xml.

#### 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>

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.

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

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

#### References

Shared MIME Info Specification — Describes the MIME registration system in detail.

## Deeper Integration with the Desktop

This chapter contains a list of things which you can do to make your application have better integration with GNOME than the absolute minimum. For example, GNOME is able to display feedback while an application is being launched: you can see how to enable this feedback in startup-notification. Also, if your software creates documents or other "printable" data, you can install a thumbnailer utility to let the GNOME file manager create thumbnail images specific to your program.

### Startup notification

Although the fields shown in desktop-files 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.

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 have it 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.

#### References

Startup Notification Protocol — Describes the low-level details of how startup notification is implemented in the X Window System.

### Installing a Thumbnailer Program

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:

`/desktop/gnome/thumbnailers/`application@x-foo`/enable`

- Type: boolean. Determines whether this thumbnailer will be run. You can enable or disable individual thumbnailers. When you install a new thumbnailer, you should of course make this key's value be true.

`/desktop/gnome/thumbnailers/`application@x-foo`/command`

- Type: string. The command which GNOME will use when it needs to generate a thumbnail for a file of type `application@x-foo`. For example, the value could be "`application-x-foo-thumbnailer %i %o %s`". See below for an explanation of the percent signs.

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:

`%i` | Input file name. This is the file that your thumbnailer needs to read.
`%u` | Input URI. If your thumbnailer can handle URIs instead of plain file names, use `%u` instead of `%i`.
`%o` | Output file name. This is where your thumbnailer should write the thumbnail image in PNG format.
`%s` | Size of the thumbnail as a single integer. For example, if this gets substituted with `128`, it means that your thumbnailer should output an image no bigger than 128×128 pixels.

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.

#### Additional information

As an additional configuration parameter, you can turn on the boolean key `/desktop/gnome/thumbnailers/disable_all` to disable the generation of all thumbnails.

## Integration Checklist

This appendix provides a checklist of the various tasks presented through this guide. You can use the checklist to ensure that your software is integrated into GNOME in at least the most basic ways, and also as a resource to plan for further integration work.

1. Does your application appear in the menus of the GNOME Panel?

2. Does your application have an icon for the panel menus or the desktop? If so, does it have multiple pre-rendered sizes and a scalable SVG version?

3. If your application can load or save files, does it register the MIME types that it can handle?

4. Does your application provide MIME icons for the file manager?

5. Does your application support startup notification, so that GNOME can display feedback to the user while your application is being launched?

6. If your application creates "printable" documents, does it install a thumbnailer for use by the file manager?

## Acknowledgments

Many thanks to Jakub Steiner for providing a beautiful CSS stylesheet for the HTML version of this guide!