GNOME Desktop Library Reference Manual: GnomeDesktopThumbnailFactory

GnomeDesktopThumbnailFactory

GnomeDesktopThumbnailFactory — Generates and looks up thumbnails of files and directories

Stability Level

Unstable, unless otherwise indicated

Functions

GnomeDesktopThumbnailFactory *	gnome_desktop_thumbnail_factory_new ()
char *	gnome_desktop_thumbnail_factory_lookup ()
gboolean	gnome_desktop_thumbnail_factory_has_valid_failed_thumbnail ()
gboolean	gnome_desktop_thumbnail_factory_can_thumbnail ()
GdkPixbuf *	gnome_desktop_thumbnail_factory_generate_thumbnail ()
void	gnome_desktop_thumbnail_factory_save_thumbnail ()
void	gnome_desktop_thumbnail_factory_create_failed_thumbnail ()
gboolean	gnome_desktop_thumbnail_has_uri ()
gboolean	gnome_desktop_thumbnail_is_valid ()
char *	gnome_desktop_thumbnail_md5 ()
char *	gnome_desktop_thumbnail_path_for_uri ()
GdkPixbuf *	gnome_desktop_thumbnail_scale_down_pixbuf ()

Types and Values

enum	GnomeDesktopThumbnailSize
struct	GnomeDesktopThumbnailFactory
struct	GnomeDesktopThumbnailFactoryClass
	GnomeDesktopThumbnailFactoryPrivate

Object Hierarchy

    GObject
    ╰── GnomeDesktopThumbnailFactory

Includes

#include <libgnome-desktop/gnome-desktop-thumbnail.h>

Description

GnomeDesktopThumbnailFactory allows generation and loading of thumbnails for local and remote files and directories. It uses a collection of programs called thumbnailers, each one generating thumbnails for a specific set of content-types of files. For example,

totem-video-thumbnailer generates thumbnails for

video files using GStreamer; evince-thumbnailer generates thumbnails for PDFs and other document files. If no specific thumbnailer exists for a file, or if the thumbnailer fails, gdk-pixbuf is used as a fallback.

To generate a thumbnail, an appropriate thumbnailer program is selected then executed, passing it the URI of the file to thumbnail, plus a path to write the thumbnail image to. If thumbnailing succeeds, the thumbnailer should have written the image to disk before terminating; but if thumbnailing fails, no image should be written, and the thumbnailer should return a non-zero exit status. GnomeDesktopThumbnailFactory will then fall back to using gdk-pixbuf to generate a thumbnail, if possible.

Thumbnailers are chosen by examining a series of .thumbnailer files in $PREFIX/share/thumbnailers. Each is in a simple key-file format:

[Thumbnailer Entry]
TryExec=evince-thumbnailer
Exec=evince-thumbnailer -s %s %u %o
MimeType=application/pdf;application/x-bzpdf;application/x-gzpdf;

The .thumbnailer format supports three keys:

`TryExec`	Optional. The name of the the thumbnailer program in the current `$PATH`. This allows the calling code to quickly check whether the thumbnailer exists before trying to execute it.
`Exec`	Required. The command to execute the thumbnailer. It supports a few different parameters which are replaced before calling the thumbnailer: `u` is the URI of the file being thumbnailed; `i` is its path; `o` is the path of the image file to be written to; `s` is the maximum desired size of the thumbnail image (the maximum width or height, in pixels); and `%%` is a literal percent character.
`MimeType`	Required. A semicolon-separated list of MIME types which the thumbnailer supports generating thumbnails for.

So in the example .thumbnailer file above, the command passes the requested thumbnail size, then the input file’s URI, then the path for the output image file to

evince-thumbnailer.

The code to examine and call a thumbnailer is contained in GnomeDesktopThumbnailFactory, which handles looking up the right thumbnailer script, building and executing the command for it, and loading the resulting thumbnail image into a GdkPixbuf.

Thumbnail caching is also supported by GnomeDesktopThumbnailFactory. When calling a thumbnailer, the path passed for the output image file is in $XDG_CACHE_HOME/thumbnails/ $SIZE/. The cached image file is given a (probably) unique filename, generated by hashing the original file’s URI, so the thumbnail can be looked up in future. GnomeDesktopThumbnailFactory supports two sizes of thumbnails: GNOME_DESKTOP_THUMBNAIL_SIZE_NORMAL and GNOME_DESKTOP_THUMBNAIL_SIZE_LARGE. Normal thumbnails are up to 128×128 pixels, whereas large thumbnails are up to 256×256 pixels. Thumbnails which are larger than this are scaled down before being cached, and non-square thumbnails are scaled so their largest dimension is at most 128 or 256 pixels.

GnomeDesktopThumbnailFactory also handles failed thumbnails. If a thumbnailer can’t generate a thumbnail for a file (e.g. because the file is corrupt or because the right video codecs aren’t available), it returns a non-zero exit status. The thumbnail factory then writes an entry to $XDG_CACHE_HOME/thumbnails/fail/ gnome-thumbnail-factory/ which is named after the hash of the input file URI (just like a successful cached thumbnail). For future queries for thumbnails for that file, GnomeDesktopThumbnailFactory can immediately return an error after looking up the fail entry.

If a file changes content, GnomeDesktopThumbnailFactory will generate a new thumbnail because each cached image has associated metadata (stored as PNG tEXt keys) storing the full URI of the thumbnailed file (to check for hash collisions) and its last modification time at the point of thumbnailing. If the stored modification time doesn’t match the file’s current one, a new thumbnail is generated.

Functions

gnome_desktop_thumbnail_factory_new ()

GnomeDesktopThumbnailFactory *
gnome_desktop_thumbnail_factory_new (GnomeDesktopThumbnailSize size);

Creates a new GnomeDesktopThumbnailFactory.

This function must be called on the main thread.

Parameters

size

The thumbnail size to use

Returns

a new GnomeDesktopThumbnailFactory

Since 2.2

gnome_desktop_thumbnail_factory_lookup ()

char *
gnome_desktop_thumbnail_factory_lookup
                               (GnomeDesktopThumbnailFactory *factory,
                                const char *uri,
                                time_t mtime);

Tries to locate an existing thumbnail for the file specified.

Usage of this function is threadsafe.

Parameters

factory	a GnomeDesktopThumbnailFactory
uri	the uri of a file
mtime	the mtime of the file

Returns

The absolute path of the thumbnail, or NULL if none exist.

Since 2.2

gnome_desktop_thumbnail_factory_has_valid_failed_thumbnail ()

gboolean
gnome_desktop_thumbnail_factory_has_valid_failed_thumbnail
                               (GnomeDesktopThumbnailFactory *factory,
                                const char *uri,
                                time_t mtime);

Tries to locate an failed thumbnail for the file specified. Writing and looking for failed thumbnails is important to avoid to try to thumbnail e.g. broken images several times.

Usage of this function is threadsafe.

Parameters

factory	a GnomeDesktopThumbnailFactory
uri	the uri of a file
mtime	the mtime of the file

Returns

TRUE if there is a failed thumbnail for the file.

Since 2.2

gnome_desktop_thumbnail_factory_can_thumbnail ()

gboolean
gnome_desktop_thumbnail_factory_can_thumbnail
                               (GnomeDesktopThumbnailFactory *factory,
                                const char *uri,
                                const char *mime_type,
                                time_t mtime);

Returns TRUE if this GnomeIconFactory can (at least try) to thumbnail this file. Thumbnails or files with failed thumbnails won't be thumbnailed.

Usage of this function is threadsafe.

Parameters

factory	a GnomeDesktopThumbnailFactory
uri	the uri of a file
mime_type	the mime type of the file
mtime	the mtime of the file

Returns

TRUE if the file can be thumbnailed.

Since 2.2

gnome_desktop_thumbnail_factory_generate_thumbnail ()

GdkPixbuf *
gnome_desktop_thumbnail_factory_generate_thumbnail
                               (GnomeDesktopThumbnailFactory *factory,
                                const char *uri,
                                const char *mime_type);

Tries to generate a thumbnail for the specified file. If it succeeds it returns a pixbuf that can be used as a thumbnail.

Usage of this function is threadsafe.

Parameters

factory	a GnomeDesktopThumbnailFactory
uri	the uri of a file
mime_type	the mime type of the file

Returns

thumbnail pixbuf if thumbnailing succeeded, NULL otherwise.

[transfer full]

Since 2.2

gnome_desktop_thumbnail_factory_save_thumbnail ()

void
gnome_desktop_thumbnail_factory_save_thumbnail
                               (GnomeDesktopThumbnailFactory *factory,
                                GdkPixbuf *thumbnail,
                                const char *uri,
                                time_t original_mtime);

Saves thumbnail at the right place. If the save fails a failed thumbnail is written.

Usage of this function is threadsafe.

Parameters

factory	a GnomeDesktopThumbnailFactory
thumbnail	the thumbnail as a pixbuf
uri	the uri of a file
original_mtime	the modification time of the original file

Since 2.2

gnome_desktop_thumbnail_factory_create_failed_thumbnail ()

void
gnome_desktop_thumbnail_factory_create_failed_thumbnail
                               (GnomeDesktopThumbnailFactory *factory,
                                const char *uri,
                                time_t mtime);

Creates a failed thumbnail for the file so that we don't try to re-thumbnail the file later.

Usage of this function is threadsafe.

Parameters

factory	a GnomeDesktopThumbnailFactory
uri	the uri of a file
mtime	the modification time of the file

Since 2.2

gnome_desktop_thumbnail_has_uri ()

gboolean
gnome_desktop_thumbnail_has_uri (GdkPixbuf *pixbuf,
                                 const char *uri);

Returns whether the thumbnail has the correct uri embedded in the Thumb::URI option in the png.

Parameters

pixbuf	an loaded thumbnail pixbuf
uri	a uri

Returns

TRUE if the thumbnail is for uri

Since 2.2

gnome_desktop_thumbnail_is_valid ()

gboolean
gnome_desktop_thumbnail_is_valid (GdkPixbuf *pixbuf,
                                  const char *uri,
                                  time_t mtime);

Returns whether the thumbnail has the correct uri and mtime embedded in the png options.

Parameters

pixbuf	an loaded thumbnail GdkPixbuf
uri	a uri
mtime	the mtime

Returns

TRUE if the thumbnail has the right uri and mtime

Since 2.2

gnome_desktop_thumbnail_md5 ()

char *
gnome_desktop_thumbnail_md5 (const char *uri);

gnome_desktop_thumbnail_md5 has been deprecated since version 2.22 and should not be used in newly-written code.

Use GChecksum instead

Calculates the MD5 checksum of the uri. This can be useful if you want to manually handle thumbnail files.

Parameters

uri

an uri

Returns

A string with the MD5 digest of the uri string.

Since 2.2

gnome_desktop_thumbnail_path_for_uri ()

char *
gnome_desktop_thumbnail_path_for_uri (const char *uri,
                                      GnomeDesktopThumbnailSize size);

Returns the filename that a thumbnail of size size for uri would have.

Parameters

uri	an uri
size	a thumbnail size

Returns

an absolute filename

Since 2.2

gnome_desktop_thumbnail_scale_down_pixbuf ()

GdkPixbuf *
gnome_desktop_thumbnail_scale_down_pixbuf
                               (GdkPixbuf *pixbuf,
                                int dest_width,
                                int dest_height);

Scales the pixbuf to the desired size. This function is a lot faster than gdk-pixbuf when scaling down by large amounts.

Parameters

pixbuf	a GdkPixbuf
dest_width	the desired new width
dest_height	the desired new height

Returns

a scaled pixbuf.

[transfer full]

Since 2.2

Types and Values

enum GnomeDesktopThumbnailSize

Members

GNOME_DESKTOP_THUMBNAIL_SIZE_NORMAL
GNOME_DESKTOP_THUMBNAIL_SIZE_LARGE

struct GnomeDesktopThumbnailFactory

struct GnomeDesktopThumbnailFactory;

struct GnomeDesktopThumbnailFactoryClass

struct GnomeDesktopThumbnailFactoryClass {
	GObjectClass parent;
};

GnomeDesktopThumbnailFactoryPrivate

typedef struct _GnomeDesktopThumbnailFactoryPrivate GnomeDesktopThumbnailFactoryPrivate;