Integrating Applications Into the GNOME 2.0 Deskto

Integrating Applications Into the GNOME 2.0 Desktop

How Do I Integrate My Application Within the GNOME 2.0 Desktop?

There are three things you need to do to have GNOME recognize your application:

1. Add a menu entry for launching your application.
2. Add a MIME type sniffer/file name association for any new MIME types and provide human-readable names for your MIME types.
3. Add a MIME type binding between your application and the MIME type(s) it handles.

1) Adding a New Menu Entry for Your Application

To have your application appear in the GNOME Applications menu (located at the top left of the top panel), you need to write an application-specific '.desktop' file; and install it in the correct location.

The full format of this file is defined as the Desktop Entry Standard on the freedesktop.org web site:

The most basic information you need to specify in your application's .desktop file are the following fields:

Name=
Comment=
Exec=
TryExec=
Terminal=
Type=
Icon=
Categories=

The Name and Comment field should have translated entries associated with the locale.

Name[ca]=
Name[es]=
Comment[ca]=
(and so on)

The icon referred to in the Icon field must be stored in the /usr/share/pixmaps/ directory. The recommended size is 48x48 pixels. (For user installations -- that is, not root installations -- the icon should be placed in the ~/.icons/gnome//apps/ directory, where represents the dimensions of the icon, for example, 48x48.)

GNOME also supports several icon themes for users with special visual needs; application icons crafted for these themes should be placed in the following directories:

/usr/share/icons/HighContrast//apps/
/usr/share/icons/HighContrastInverse//apps/
/usr/share/icons/HighContrastLargePrint//apps/
/usr/share/icons/HighContrastLargePrintInverse//apps/
/usr/share/icons/LargePrint//apps/
/usr/share/icons/LowContrast//apps/
/usr/share/icons/LowContrastLargePrint//apps/

In this case, represents the dimensions of the icon. It is recommended that you supply 16x16 and 48x48 icons for these themes. (For user installations, the icons should be placed in the subdirectories of ~/.icons/gnome/ rather than /usr/share/icons/.)

Use the Categories section to define where you want the menu entry to go. For example, use Categories=Application;System; for system utilities, or use Categories=Application;Game; for games.

See the file /etc/gnome/gnome-vfs-2.0/vfolders/applications-all-users.vfolder-info for the system definition of the menu structure and how it uses these category keywords.

Once you have defined this simple file, you need to install it to:

/usr/share/applications/

This is the default location for application .desktop files. (For user installations, put the file in the ~/.gnome2/vfolders/applications/ directory.)

Here is an example of the Eye of GNOME application .desktop file. The translated names and comments have been stripped out. Notice the %U argument on the Exec line; it means that the application will accept one or more URLs passed to it. Another common argument is %F, which means one or more files. Specifying these arguments allows a user to open documents by dragging and dropping them on a launcher that was created by dragging the item in the Applications menu hierarchy corresponding to your .desktop file to a panel or to the desktop.

------eog.desktop---------------------------
[Desktop Entry]
Name=Eye of Gnome Image Viewer
Comment=View many different types of images
Exec=eog %U
TryExec=eog
Icon=gnome-eog.png
Terminal=false
Type=Application
Categories=GNOME;Application;Graphics;RasterGraphics;Viewer;
-------------------------------------------

2) Add a MIME Type Sniffer/File Name Association for Any New MIME Types

It is important that the GNOME MIME type registry knows about your application and the MIME types it can handle. This is so that the Nautilus file manager can detect the file types, display a descriptive string for it, use an appropriate icon to represent it in a folder view, and offer the user a default and extra list of applications to launch to edit/view this file type.

There are two ways you can specify new file-to-MIME-type associations in GNOME.

a) Provide a file content sniffer to identify the MIME type:

Take a look at the file /etc/gnome/gnome-vfs-mime-magic.

This file contains the default file content sniffers for identifying MIME types. Some good documentation of the file format is available in the header of the file, but here is a simple breakdown of the fields in each single line record:

• The first column is the offset into the file that the sniffer should 'sniff' from.
• The second column is the pattern type (currently, only string is supported).
• The third column is the actual pattern the sniffer should look for.
• The fourth column is the pattern mask (same length as the pattern).
• And the final column is the name of the valid MIME type that should be associated with sniffed files that match this entry.

Here is an example of the GIF image file format sniffer:

0       string          GIF8               image/gif

So the sniffer looks for a pattern match of the string 'GIF8' right at the start of the file. There is no pattern mask, and the associated MIME type is image/gif.

b) Provide a file name pattern/extension detection of the MIME type:

If a file's MIME type is not identified by one of the sniffers described above, GNOME will then start looking at the following files to see if it can match the file name to a MIME type:

/usr/share/gnome/mime-info/*.mime

Again, there is some good documentation of the .mime file format at the top of the /usr/share/gnome/mime-info/gnome-vfs.mime file, but here is a short description:

mime-type
        ext:    list of extensions for this mime-type
        regex:  a regular expression that matches the filename

And here's an example:

audio/x-mp3
        ext: mp3

You must specify the ext or regex field (or both). Each can have multiple entries separated by space characters.

audio/x-real-audio
        ext: rm ra ram

New applications that handle new MIME types (that is, those not already defined) normally would create a new file '.mime' with the MIME type matcher and put it into the /usr/share/gnome/mime-info/ directory. For user installations, put the file in the ~/.gnome/mime-info/ directory. New applications don't generally add new file sniffers.

Just a note now on the priority of MIME type matching. The sniffers take priority over the file name/pattern matchers. The sniffer priority is determined by the order in which they appear in the file. The file name/pattern matchers are prioritized with an extra , suffix to the ext or regex fields. See /usr/share/gnome/mime-info/gnome-vfs.mime for more information.

Once you have defined any new MIME types you handle and given GNOME some idea of how to detect them, you now need to provide human-readable names and an icon that should be associated with them. To do this, you need to create a '' file in the same /usr/share/gnome/mime-info/ directory. (For user installations, put the file in the ~/.gnome/mime-info/ directory.)

The file format is similar to the .mime file with a mime-type and then a list of tab-indented key-value pairs.

For example:

application/x-myapp-file:
        description=Myapp data file
        icon_filename=i-myappdata.png
        default_action_type=application
        short_list_application_ids_for_novice_user_level=myapp
        category=Documents/Diagram

This entry defines an association between the mime type application/x-myapp-file and a human-readable description, an icon, the default application to use when the icon is double clicked in the file manager, and a MIME type category.

The icon referred to in the icon_filename field must be stored in the /usr/share/pixmaps/document-icons/ directory. The recommended size is 48x48 pixels. (For user installations, put the icon file in the ~/.icons/gnome//mimetypes/ directory, where represents the dimensions of the icon, for example, 48x48.)

GNOME also supports several icon themes for users with special visual needs; MIME type icons crafted for these themes should be placed in the following directories:

 
  /usr/share/icons/HighContrast//mimetypes/
  /usr/share/icons/HighContrastInverse//mimetypes/
  /usr/share/icons/HighContrastLargePrint//mimetypes/
  /usr/share/icons/HighContrastLargePrintInverse//mimetypes/
  /usr/share/icons/LargePrint//mimetypes/
  /usr/share/icons/LowContrast//mimetypes/
  /usr/share/icons/LowContrastLargePrint//mimetypes/

In this case, represents the dimensions of the icon. It is recommended that you supply 16x16 and 48x48 icons for these themes. (For user installations, the icons should be placed in the subdirectories of ~/.icons/gnome/ rather than /usr/share/icons/.)

The other values for default_action_type should be ignored unless you are writing Bonobo or Nautilus view components.

The short_list_application entry defines an application name that appears in the application registry, so you now need to create an entry for your application there as well.

The category entry allows the MIME type to be organized conveniently in the Files Types and Programs preferences panel. See this panel for the standard category names. Subcategory names can also be specified, separated from their parent category by a "/" character, as in the preceding example.

3) Add a MIME Type Binding Between Your Application and the MIME Types It Handles

Create a file called '.applications' and install it to /usr/share/gnome/application-registry. (For user installations, put the file in ~/.gnome/application-info/.)

Take a look at /usr/share/gnome/application-registry/gnome-vfs.applications for an example of the format of this file.

Here is the example for the eog (Eye of GNOME) image viewer application:

eog
        command=eog
        name=Eye of Gnome
        can_open_multiple_files=true
        expects_uris=false
        requires_terminal=false
        mime_types=image/bmp,image/gif,image/jpeg,image/png,
		image/tiff,im= age/x-xpixmap,image/x-bmp,image/x-png,image/
		x-portable-anymap,
image/x-porta=
ble-bitmap,image/x-portable-graymap,image/x-portable-pixmap

The first line is the application id in the registry (which is matched by short_list_application* entries in the .keys files).

The command field is the command line that should be used to invoke the application; here you may specify particular options that are required for opening files passed to the command line, and so on.

The name field is the human-readable name for the application that will appear in the Open With context menu in Nautilus.

The expects_uris field lets Nautilus know if your application can accept uris. For example, Netscape can accept http: ftp: etc uris to open at the command line. If expects_uris is true, then you should have a supported_uri_schemes entry to list the uri schemes your application supports.

The requires_terminal field is normally set to false although something like vi would need a terminal and would set this field to true.

The mime_types field lists the MIME-type names of all the file formats that the application can handle.

Summary and Example

This summary offers a really simple example for everyone who just got confused about all of the above.

And here are the steps to follow to integrate the application "Steve Viewer", which handles the MIME type "image/steve", with GNOME (assuming a root installation):

1) Install .desktop file

------steve-viewer.desktop----------
[Desktop Entry]
Name=Steve Viewer
Comment=View Steve image files
Exec=steve-viewer
TryExec=steve-viewer
Icon=steve-viewer.png
Terminal=false
Type=Application
Categories=Application;Graphics;
-----------------------------------

This file should be installed to /usr/share/applications/. Remember it is the Categories that you define that determine where in the menu structure your menu entry will appear.

This file alone will give GNOME users access to your application by means of the GNOME menu. If you do not install any new MIME types or need to tell GNOME about any MIME types you can handle, then you can stop here.

2) Install application icon

steve-viewer.png (mentioned in the .desktop file) should be installed to /usr/share/pixmaps/ and should be 48x48 pixels in size. As noted, you should also install other icons to support users with special visual needs.

3) Install .mime file

-------steve-viewer.mime------------
image/steve
        ext: steve stephen stv
------------------------------------

This file should be installed to /usr/share/gnome/mime-info/.

This file just defines the new MIME-type image/steve and makes an association to all files named *.steve, *.stephen, and *.stv.

4) Install .keys file

-------steve-viewer.keys------------
image/steve
        description=Steve Image file
        icon_filename=i-steve.png
        default_action=application
        short_list_application_ids_for_novice_user_level=steve-viewer
        category=Images
-----------------------------------

This file should be installed to /usr/share/gnome/mime-info/.

Here we now have some more human-consumable information about the new MIME-type, which Nautilus can use to display in its folder views.

5) Install file type icon

i-steve.png should be 48x48 pixels and installed to /usr/share/pixmaps/document-icons/. Icons crafted for themes designed for users with special visual needs should also be installed in the following locations:

  
  /usr/share/icons/HighContrast//mimetypes/
  /usr/share/icons/HighContrastInverse//mimetypes/
  /usr/share/icons/HighContrastLargePrint//mimetypes/
  /usr/share/icons/HighContrastLargePrintInverse//mimetypes/
  /usr/share/icons/LargePrint//mimetypes/
  /usr/share/icons/LowContrast//mimetypes/
  /usr/share/icons/LowContrastLargePrint//mimetypes/

As with application icons, file type icons for these themes should be provided in two sizes, 16x16 and 48x48.

6) Install .applications file

----steve-viewer.applications------
steve-viewer
        command=steve-viewer -f
        name=Steve Viewer
        expects_uris=false
        requires_terminal=false
        mime_types=image/steve
-----------------------------------

This file should be installed to /usr/share/gnome/application-registry/.

Now Nautilus will know all it needs to know to offer Steve Viewer as an application in the Open With menu, and combined with the preceding .keys file, it will know to use steve-viewer as the default application for the image/steve MIME-type.