Commit f5561d74 authored by Philip Withnall's avatar Philip Withnall

thumbnailer: Add documentation on thumbnailers and .thumbnailer files

https://bugzilla.gnome.org/show_bug.cgi?id=711604
parent b0414e29
......@@ -24,6 +24,108 @@
* Author: Alexander Larsson <alexl@redhat.com>
*/
/**
* SECTION:gnome-desktop-thumbnail
* @short_description: Generates and looks up thumbnails of files and
* directories
* @stability: Unstable
* @include: libgnome-desktop/gnome-desktop-thumbnail.h
*
* #GnomeDesktopThumbnailFactory allows generation and loading of thumbnails for
* local and remote files and directories. It uses a collection of programs
* called <firstterm>thumbnailers</firstterm>, each one generating thumbnails
* for a specific set of content-types of files. For example,
* <application>totem-video-thumbnailer</application> generates thumbnails for
* video files using GStreamer; <application>evince-thumbnailer</application>
* 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
* <filename>.thumbnailer</filename> files in
* <filename><replaceable>$PREFIX</replaceable>/share/thumbnailers</filename>.
* Each is in a simple key-file format:
* <informalexample><programlisting>
* [Thumbnailer Entry]
* TryExec=evince-thumbnailer
* Exec=evince-thumbnailer -s %s %u %o
* MimeType=application/pdf;application/x-bzpdf;application/x-gzpdf;
* </programlisting></informalexample>
*
* The <filename>.thumbnailer</filename> format supports three keys:
* <variablelist>
* <varlistentry><term><code>TryExec</code></term><listitem><para>
* Optional. The name of the the thumbnailer program in the current
* <envar>$PATH</envar>. This allows the calling code to quickly check whether
* the thumbnailer exists before trying to execute it.
* </para></listitem></varlistentry>
* <varlistentry><term><code>Exec</code></term><listitem><para>
* Required. The command to execute the thumbnailer. It supports a few different
* parameters which are replaced before calling the thumbnailer:
* <replaceable>%u</replaceable> is the URI of the file being thumbnailed;
* <replaceable>%i</replaceable> is its path; <replaceable>%o</replaceable>
* is the path of the image file to be written to;
* <replaceable>%s</replaceable> is the maximum desired size of the thumbnail
* image (the maximum width or height, in pixels); and
* <replaceable>%%</replaceable> is a literal percent character.
* </para></listitem></varlistentry>
* <varlistentry><term><code>MimeType</code></term><listitem><para>
* Required. A semicolon-separated list of MIME types which the thumbnailer
* supports generating thumbnails for.
* </para></listitem></varlistentry>
* </variablelist>
*
* So in the example <filename>.thumbnailer</filename> file above, the command
* passes the requested thumbnail size, then the input file’s URI, then the
* path for the output image file to
* <application>evince-thumbnailer</application>.
*
* 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
* <filename><envar>$XDG_CACHE_HOME</envar>/thumbnails/
* <replaceable>$SIZE</replaceable>/</filename>. 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
* <filename><envar>$XDG_CACHE_HOME</envar>/thumbnails/fail/
* gnome-thumbnail-factory/</filename> 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.
*
* Since: 2.2
*/
#include <config.h>
#include <sys/types.h>
#include <sys/stat.h>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment