GimpThumbnail: GIMP Thumbnail Library Reference Manual

## GimpThumbnail GimpThumbnail — The GimpThumbnail object |

## Functions

GimpThumbnail * | gimp_thumbnail_new ()
void | gimp_thumbnail_set_uri ()
gboolean | gimp_thumbnail_set_filename ()
gboolean | gimp_thumbnail_set_from_thumb ()
GimpThumbState | gimp_thumbnail_peek_image ()
GimpThumbState | gimp_thumbnail_peek_thumb ()
GimpThumbState | gimp_thumbnail_check_thumb ()
GdkPixbuf * | gimp_thumbnail_load_thumb ()
gboolean | gimp_thumbnail_save_thumb ()
gboolean | gimp_thumbnail_save_thumb_local ()
gboolean | gimp_thumbnail_save_failure ()
void | gimp_thumbnail_delete_failure ()
void | gimp_thumbnail_delete_others ()
gboolean | gimp_thumbnail_has_failed ()

## Properties

gint64 | image-filesize | Read / Write
gint | image-height | Read / Write
gchar * | image-mimetype | Read / Write
gint64 | image-mtime | Read / Write
gint | image-num-layers | Read / Write
GimpThumbState | image-state | Read / Write
gchar * | image-type | Read / Write
gchar * | image-uri | Read / Write
gint | image-width | Read / Write
GimpThumbState | thumb-state | Read / Write

## Types and Values

| GimpThumbnail

## Object Hierarchy

        GObject
        ╰── GimpThumbnail

## Description

The GimpThumbnail object

## Functions

### 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 information stored in the GimpThumbnail is reset.

#### Parameters

thumbnail | a GimpThumbnail object |
uri | an escaped URI |

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

#### Parameters

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.

This will only work with thumbnails from the global thumbnail directory that contain a valid Thumb::URI tag.

#### Parameters

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.

#### Parameters

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

If you want to check the thumbnail, either attempt to load it using `gimp_thumbnail_load_thumb()`, or, if you don't need the resulting thumbnail pixbuf, use `gimp_thumbnail_check_thumb()`.

#### Parameters

thumbnail | a GimpThumbnail object |
size | the preferred size of the thumbnail image |

#### Returns

the thumbnail's GimpThumbState after the update

### gimp_thumbnail_check_thumb ()

    GimpThumbState
    gimp_thumbnail_check_thumb (GimpThumbnail *thumbnail,
                                GimpThumbSize size);

Checks if a thumbnail file for the `thumbnail` exists, loads it and verifies it is valid and uptodate for the image file asosciated with the `thumbnail` .

#### Parameters

thumbnail | a GimpThumbnail object |
size | the preferred size of the thumbnail image |

#### Returns

the thumbnail's GimpThumbState after the update

Since: 2.2

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

#### Parameters

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` . to the global thumbnail repository.

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.

#### Parameters

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_thumb_local ()

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

Saves a preview thumbnail for the image associated with `thumbnail` to the local thumbnail repository. Local thumbnails have been added with version 0.7 of the spec.

Please see also `gimp_thumbnail_save_thumb()`. The notes made there apply here as well.

#### Parameters

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

Since: 2.2

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

#### Parameters

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

### gimp_thumbnail_delete_failure ()

    void
    gimp_thumbnail_delete_failure (GimpThumbnail *thumbnail);

Removes a failure thumbnail if one exists. This function should be used after a thumbnail has been successfully created.

#### Parameters

thumbnail | a GimpThumbnail object |

Since: 2.2

### gimp_thumbnail_delete_others ()

    void
    gimp_thumbnail_delete_others (GimpThumbnail *thumbnail,
                                  GimpThumbSize size);

Removes all other thumbnails from the global thumbnail repository. Only the thumbnail for `size` is not deleted. This function should be used after a thumbnail has been successfully updated. See the spec for a more detailed description on when to delete thumbnails.

#### Parameters

thumbnail | a GimpThumbnail object |
size | the thumbnail size which should not be deleted |

Since: 2.2

### gimp_thumbnail_has_failed ()

    gboolean
    gimp_thumbnail_has_failed (GimpThumbnail *thumbnail);

Checks if a valid failure thumbnail for the given thumbnail exists in the global thumbnail repository. This may be the case even if `gimp_thumbnail_peek_thumb()` doesn't return `GIMP_THUMB_STATE_FAILED` since there might be a real thumbnail and a failure thumbnail for the same image file.

The application should not attempt to create the thumbnail if a valid failure thumbnail exists.

#### Parameters

thumbnail | a GimpThumbnail object |

#### Returns

`TRUE` if a failure thumbnail exists or

Since: 2.2

## Types and Values

### GimpThumbnail

    typedef struct _GimpThumbnail GimpThumbnail;

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

## Property Details

### The `“image-filesize”` property

      “image-filesize”           gint64

Size of the image file in bytes.

Owner: GimpThumbnail

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“image-height”` property

      “image-height”             gint

Height of the image in pixels.

Owner: GimpThumbnail

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“image-mimetype”` property

      “image-mimetype”           gchar *

Image mimetype.

Owner: GimpThumbnail

Flags: Read / Write

Default value: NULL

### The `“image-mtime”` property

      “image-mtime”              gint64

Modification time of the image file in seconds since the Epoch.

Owner: GimpThumbnail

Flags: Read / Write

Default value: 0

### The `“image-num-layers”` property

      “image-num-layers”         gint

The number of layers in the image.

Owner: GimpThumbnail

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“image-state”` property

      “image-state”              GimpThumbState

State of the image associated to the thumbnail object.

Owner: GimpThumbnail

Flags: Read / Write

Default value: GIMP_THUMB_STATE_UNKNOWN

### The `“image-type”` property

      “image-type”               gchar *

String describing the type of the image format.

Owner: GimpThumbnail

Flags: Read / Write

Default value: NULL

### The `“image-uri”` property

      “image-uri”                gchar *

URI of the image file.

Owner: GimpThumbnail

Flags: Read / Write

Default value: NULL

### The `“image-width”` property

      “image-width”              gint

Width of the image in pixels.

Owner: GimpThumbnail

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“thumb-state”` property

      “thumb-state”              GimpThumbState

State of the thumbnail file.

Owner: GimpThumbnail

Flags: Read / Write

Default value: GIMP_THUMB_STATE_UNKNOWN