| Top | |
|
|
|
GnomeDesktopThumbnailFactoryGnomeDesktopThumbnailFactory — Generates and looks up thumbnails of files and directories |
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 forvideo 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
1 2 3 |
[Thumbnailer Entry] Exec=evince-thumbnailer -s %s %u %o MimeType=application/pdf;application/x-bzpdf;application/x-gzpdf; |
The .thumbnailer format supports three keys:
|
Required. The command to execute the thumbnailer. It supports a few different
parameters which are replaced before calling the thumbnailer:
|
|
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
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/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/
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.
GnomeDesktopThumbnailFactory *
gnome_desktop_thumbnail_factory_new (GnomeDesktopThumbnailSize size);
Creates a new GnomeDesktopThumbnailFactory.
This function must be called on the main thread and is non-blocking.
Since: 2.2
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 and does blocking I/O.
Since: 2.2
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 and does blocking I/O.
Since: 2.2
gboolean gnome_desktop_thumbnail_factory_can_thumbnail (GnomeDesktopThumbnailFactory *factory,const char *uri,const char *mime_type,time_t mtime);
Returns TRUE if this GnomeDesktopThumbnailFactory can (at least try) to thumbnail this file. Thumbnails or files with failed thumbnails won't be thumbnailed.
Usage of this function is threadsafe and does blocking I/O.
factory |
||
uri |
the uri of a file |
|
mime_type |
the mime type of the file |
|
mtime |
the mtime of the file |
Since: 2.2
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 and does blocking I/O.
Since: 2.2
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 and does blocking I/O.
factory |
||
thumbnail |
the thumbnail as a pixbuf |
|
uri |
the uri of a file |
|
original_mtime |
the modification time of the original file |
Since: 2.2
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 and does blocking I/O.
Since: 2.2
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. This function is threadsafe and does no blocking I/O.
Since: 2.2
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.
This function is threadsafe and does no blocking I/O.
Since: 2.2