Issue #13 November 2005

Integrating applications into the desktop, part 2

by Rosanna Yuen

Introduction

Last time, in Integrating your applications into the desktop, Part 1, we discussed the basics of integrating an application onto the desktop. This time, we look a little further, and discuss some of the more specific standards as well as a tool that may be useful towards integrating your application.

Creating custom thumbnails

If your application creates files with a new extension, you may want the file manager to show these files a certain way. Rather than having a set icon for all every file with this extension, you may want to create a custom thumbnail for every one of these files. For example, notice that the file manager displays all .pdf files with a thumbnail containing the first page of the document.

In order for the file manager to show your custom thumbnails, you need a thumbnailer and a gconf key.

Creating the thumbnailer

A thumbnailer is an application that produces a thumbnail of the document in png format based on the command line arguments. The possible arguments are:

  • %u — thumbnailer takes this URL.
  • %i — thumbnailer takes this file.
  • %o — thumbnailer outputs this file.
  • %s — creates a thumbnail of this size, in pixels.

As %u and %i are both input possibilities, only one of them can be used. If your thumbnailer can take URLs, use %u. Otherwise use %i. For example: 

my-thumbnailer --size %s %u %o

would get called by Nautilus with the command 

my-thumbnailer --size 128 http://example.com/file/to/thumbnail /tmp/.gnome_thumbnail.123456

You can create your thumbnailer application in any language or style you like. However, it must follow the following constraints:

  • Return 0 if the thumbnail is generated successfully. If it fails, return -1 and do not create the image.
  • Scale the image so that the maximum dimension is the size given. If no size is given, assume a size of 128 pixels.
  • Do not add a border. The file manager adds a border to all images automatically.

Installing the gconf key

Once your thumbnailer application is written, you need to let the desktop know that it exists. To register your thumbnailer in GNOME, you need to create a .schemas file and put it in the /etc/gconf/schemas/ directory. This file also needs to state what arguments your thumbnailer application can take. An example of a .schemas file is shown in Example 1. Sample .schemas file. 

<gconfschemafile>
    <schemalist>
        <schema>
            <key>/schemas/desktop/gnome/thumbnailers/application@extension/enable</key>

            <applyto>/desktop/gnome/thumbnailers/application@extension/enable</applyto>
            <owner>myapplication</owner>
            <type>bool</type>

            <default>true</default>
            <locale name="C">
                <short>Enable thumbnailing of myapplication documents.</short>
                <long>Boolean options available, true enables thumbnailing and false disables the creation of new thumbnails.</long>

            </locale>
        </schema>
        <schema>
            <key>/schemas/desktop/gnome/thumbnailers/application@extension/command</key>
            <applyto>/desktop/gnome/thumbnailers/application@extension/command</applyto>

            <owner>myapplication</owner>
            <type>string</type>
            <default>my-thumbnailer -s %s %u %o</default>
            <locale name="C">

                <short>Thumbnail command for documents from my application.</short>
                <long>Valid command plus arguments for my-thumbnailer.</long>
            </locale>
        </schema>
    </schemalist>

</gconfschemafile>
Example 1. Sample .schemas file

In order for the user to start your application, first they have to find it. Having your application listed appropriately in the desktop's main menu is very important. Thankfully, having the main menu list your application is usually a straightforward affair.

Remember how we wrote a .desktop file in the part 1? We are going to add to that. In order to be added to the main menu, a Category line needs to be in the desktop file. For example, the desktop file for an email application might contain the following line: 

Category=Office;Email;

As the list of possible categories is a list, every category must be followed by a semicolon. The list of available categories are shown in the menu specification.

Tip:
The desktop file is located in the /usr/share/applications/ directory. Remember that entries in this file are case sensitive. For more information on desktop files, refer to Part I.

There are two more lines that can be added to the desktop file that affects the placement of the application in the main menu. These are the OnlyShownIn field and the NotShownIn field. The valid values for these fields are GNOME, KDE, ROX, XFCE, and Old. These lines limit showing the applications in the menus when specific environments are used. For example, if you add the following line: 

OnlyShownIn=GNOME;

the application would only be shown in the menu if the desktop is in the GNOME environment.

Although having the menu system automatically create the menus is convenient, sometimes you want to be able to be even more precise in your categorization. Perhaps you wish to create your own submenu in the menu tree. Or maybe your application belongs to a different place in the menu than the categories permit. In these instances, it is useful to know how the menu is created.

The desktop menu system is essentially a system of stored queries. It reads all the desktop files in the /usr/share/applications/ directory and matches the categories listed in these files with the queries. These queries are formed in XML files and end with a .menu extension. The generic menu file is located at /etc/xdg/menus/applications.menu.

In order to extend the main menu to list your application in the location of your choice, you need to write your own XML file which encompasses your own queries.

After you create your own .menu file, place it in /etc/xdg/menus/applications-merged/ for your query to be merged with the main /etc/xdg/menus/applications.menu file. In Example 2. Sample .menu file, a new menu directory is created called New Directory. In this menu, the applications myapplication and otherapplication can be found. 

<Menu>
  <Name>New Directory</Name>
  <Directory>NewDirectory.directory</Directory>

  <Include>

    <Filename>myapplication.desktop</Filename>
    <Filename>otherapplication.desktop</Filename>
  </Include>
</Menu>
Example 2. Sample .menu file

System tray

The system tray is a cross-desktop method of notifying the user. It can be used to relay information and occasionally control your application remotely. The specification has standardized the process such that setting a widget in the system tray works regardless of the desktop. This allows you to have a widget associated with your application located in the panel without it being an applet.

Placing an icon in the system tray can be very useful to your application. If the user should be notified whenever:

  • A change has occurred — for example, your application is an email client and new email has arrived.
  • A problem needs the user's attention — for example, an error has occurred that the user needs to address.
  • Access to your application — for example, your application is running in the background but no windows are currently open. The icon allows the user to access this application.

These are just some possible uses of the system tray. It is a very handy way of relaying useful information to the user.

Placing an icon in the system tray can be done in Python, C, or any language that has the necessary libraries. A simple program written in Python is shown in Example 3. Sample Python program that creates an icon in the system tray. 

#! /usr/bin/python
import gtk
import egg.trayicon
t = egg.trayicon.TrayIcon("MyFirstTrayIcon")
t.add(gtk.Label("Hello"))
t.show_all()
gtk.main()
Example 3. Sample Python program that creates an icon in the system tray

Easy translations

intltool is a tool that lets you easily translate the strings in your application.

To take advantage of the translation powers from intltool, create a .desktop.in file. This file is identical to the .desktop file we discussed in the part 1 except there are no translations in this file. Place an underscore character in front of the lines you wish to translate. For example, this would be the first few lines of myapplication.desktop.in: 

[Desktop Entry]
Encoding=UTF-8
_Name=MyApplication
_Comment=A useful application that does useful things

Once your .desktop.in file is complete, create a po/ directory for your application. In this directory, create a file called POTFILES.in. This file should contain a list of every file you want to translate. In this example, we would have: 

myapplication.desktop.in

From this same po/ directory, enter the following into a shell: 

intltool-update --pot --gettext-package=myapplication

This command creates a file called myapplication.pot in the po/ directory. For each translation you want to create, copy this file into a file called language_code.po. For example, a Swedish translation would require: 


cp myapplication.pot sv.po

After translating each of these files you created, merge the translations back into your desktop file by entering: 

intltool-merge /path/to/po myapplication.desktop.in myapplication.desktop

The myapplication.desktop is created with all your translations inside.

Tip:
For more information, see the man pages for intltool-update and intltool-merge.
Note:
intltool also works well with automake. Setting up an automake project is outside the scope of this article, but see the man page for intltoolize for more information.

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.