## GimpThumbnail

GimpThumbnail — The GimpThumbnail object

## Synopsis

    struct      GimpThumbnail;
    GimpThumbnail* gimp_thumbnail_new           (void);
    void        gimp_thumbnail_set_uri          (GimpThumbnail *thumbnail,
                                                 const gchar *uri);
    gboolean    gimp_thumbnail_set_filename     (GimpThumbnail *thumbnail,
                                                 const gchar *filename,
                                                 GError **error);
    gboolean    gimp_thumbnail_set_from_thumb   (GimpThumbnail *thumbnail,
                                                 const gchar *filename,
                                                 GError **error);
    GimpThumbState gimp_thumbnail_peek_image    (GimpThumbnail *thumbnail);
    GimpThumbState gimp_thumbnail_peek_thumb    (GimpThumbnail *thumbnail,
                                                 GimpThumbSize size);
    GdkPixbuf*  gimp_thumbnail_load_thumb       (GimpThumbnail *thumbnail,
                                                 GimpThumbSize size,
                                                 GError **error);
    gboolean    gimp_thumbnail_save_thumb       (GimpThumbnail *thumbnail,
                                                 GdkPixbuf *pixbuf,
                                                 const gchar *software,
                                                 GError **error);
    gboolean    gimp_thumbnail_save_failure     (GimpThumbnail *thumbnail,
                                                 const gchar *software,
                                                 GError **error);

## Object Hierarchy

      GObject
       +----GimpThumbnail

## Properties

      "image-filesize"       gint64               : Read / Write
      "image-height"         gint                 : Read / Write
      "image-mtime"          gint64               : Read / Write
      "image-num-layers"     gint                 : Read / Write
      "image-state"          GimpThumbState       : Read / Write
      "image-type"           gchararray           : Read / Write
      "image-uri"            gchararray           : Read / Write
      "image-width"          gint                 : Read / Write
      "thumb-state"          GimpThumbState       : Read / Write

## Description

## Details

### struct GimpThumbnail

    struct GimpThumbnail;

All members of GimpThumbnail are private and should only be accessed using object properties.

### gimp_thumbnail_new ()

    GimpThumbnail* gimp_thumbnail_new           (void);

Creates a new GimpThumbnail object.

Returns : | a newly allocated GimpThumbnail object

### gimp_thumbnail_set_uri ()

    void        gimp_thumbnail_set_uri          (GimpThumbnail *thumbnail,
                                                 const gchar *uri);

Sets the location of the image file associated with the thumbnail.

All informations stored in the GimpThumbnail are reset.

`thumbnail` : | a GimpThumbnail object
`uri` : | an escaped URI in UTF-8 encoding

### gimp_thumbnail_set_filename ()

    gboolean    gimp_thumbnail_set_filename     (GimpThumbnail *thumbnail,
                                                 const gchar *filename,
                                                 GError **error);

Sets the location of the image file associated with the thumbnail.

`thumbnail` : | a GimpThumbnail object
`filename` : | a local filename in the encoding of the filesystem
`error` : | return location for possible errors
Returns : | `TRUE` if the filename was successfully set, `FALSE` otherwise

### gimp_thumbnail_set_from_thumb ()

    gboolean    gimp_thumbnail_set_from_thumb   (GimpThumbnail *thumbnail,
                                                 const gchar *filename,
                                                 GError **error);

This function tries to load the thumbnail file pointed to by `filename` and retrieves the URI of the original image file from it. This allows you to find the image file associated with a thumbnail file.

`thumbnail` : | a GimpThumbnail object
`filename` : | filename of a local thumbnail file
`error` : | return location for possible errors
Returns : | `TRUE` if the pixbuf could be loaded, `FALSE` otherwise

### gimp_thumbnail_peek_image ()

    GimpThumbState gimp_thumbnail_peek_image    (GimpThumbnail *thumbnail);

Checks the image file associated with the `thumbnail` and updates information such as state, filesize and modification time.

`thumbnail` : | a GimpThumbnail object
Returns : | the image's GimpThumbState after the update

### gimp_thumbnail_peek_thumb ()

    GimpThumbState gimp_thumbnail_peek_thumb    (GimpThumbnail *thumbnail,
                                                 GimpThumbSize size);

Checks if a thumbnail file for the `thumbnail` exists. It doesn't load the thumbnail image and thus cannot check if the thumbnail is valid and uptodate for the image file asosciated with the `thumbnail`.

`thumbnail` : | a GimpThumbnail object
`size` : | the preferred size of the thumbnail image
Returns : | the thumbnail's GimpThumbState after the update

### gimp_thumbnail_load_thumb ()

    GdkPixbuf*  gimp_thumbnail_load_thumb       (GimpThumbnail *thumbnail,
                                                 GimpThumbSize size,
                                                 GError **error);

Attempts to load a thumbnail preview for the image associated with `thumbnail`. Before you use this function you need need to set an image location using `gimp_thumbnail_set_uri()` or `gimp_thumbnail_set_filename()`. You can also peek at the thumb before loading it using gimp_thumbnail_peek_thumb.

This function will return the best matching pixbuf for the specified `size`. It returns the pixbuf as loaded from disk. It is left to the caller to scale it to the desired size. The returned pixbuf may also represent an outdated preview of the image file. In order to verify if the preview is uptodate, you should check the "thumb_state" property after calling this function.

`thumbnail` : | a GimpThumbnail object
`size` : | the preferred GimpThumbSize for the preview
`error` : | return location for possible errors
Returns : | a preview pixbuf or `NULL` if no thumbnail was found

### gimp_thumbnail_save_thumb ()

    gboolean    gimp_thumbnail_save_thumb       (GimpThumbnail *thumbnail,
                                                 GdkPixbuf *pixbuf,
                                                 const gchar *software,
                                                 GError **error);

Saves a preview thumbnail for the image associated with `thumbnail`.

The caller is responsible for setting the image file location, it's filesize, modification time. One way to set this info is to is to call `gimp_thumbnail_set_uri()` followed by `gimp_thumbnail_peek_image()`. Since this won't work for remote images, it is left to the user of `gimp_thumbnail_save_thumb()` to do this or to set the information using the `thumbnail` object properties.

The image format type and the number of layers can optionally be set in order to be stored with the preview image.

`thumbnail` : | a GimpThumbnail object
`pixbuf` : | a GdkPixbuf representing the preview thumbnail
`software` : | a string describing the software saving the thumbnail
`error` : | return location for possible errors
Returns : | `TRUE` if a thumbnail was successfully written, `FALSE` otherwise

### gimp_thumbnail_save_failure ()

    gboolean    gimp_thumbnail_save_failure     (GimpThumbnail *thumbnail,
                                                 const gchar *software,
                                                 GError **error);

Saves a failure thumbnail for the image associated with `thumbnail`. This is an empty pixbuf that indicates that an attempt to create a preview for the image file failed. It should be used to prevent the software from further attempts to create this thumbnail.

`thumbnail` : | a GimpThumbnail object
`software` : | a string describing the software saving the thumbnail
`error` : | return location for possible errors
Returns : | `TRUE` if a failure thumbnail was successfully written, `FALSE` otherwise

## Properties

"`image-filesize`" (gint64 : Read / Write) | Size of the image file in bytes.
"`image-height`" (gint : Read / Write) | Height of the image in pixels.
"`image-mtime`" (gint64 : Read / Write) | Modification time of the image file in seconds since the Epoch.
"`image-num-layers`" (gint : Read / Write) | The number of layers in the image.
"`image-state`" (GimpThumbState : Read / Write) | State of the image associated to the thumbnail object.
"`image-type`" (gchararray : Read / Write) | String describing the type of the image format.
"`image-uri`" (gchararray : Read / Write) | URI of the image file.
"`image-width`" (gint : Read / Write) | Width of the image in pixels.
"`thumb-state`" (GimpThumbState : Read / Write) | State of the thumbnail file.