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:


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


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.

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