GimpThumbnail

GimpThumbnail — The GimpThumbnail object

Synopsis

                    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);
GimpThumbState      gimp_thumbnail_check_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_thumb_local     (GimpThumbnail *thumbnail,
                                                         GdkPixbuf *pixbuf,
                                                         const gchar *software,
                                                         GError **error);
gboolean            gimp_thumbnail_save_failure         (GimpThumbnail *thumbnail,
                                                         const gchar *software,
                                                         GError **error);
void                gimp_thumbnail_delete_failure       (GimpThumbnail *thumbnail);
void                gimp_thumbnail_delete_others        (GimpThumbnail *thumbnail,
                                                         GimpThumbSize size);
gboolean            gimp_thumbnail_has_failed           (GimpThumbnail *thumbnail);

Object Hierarchy

  GObject
   +----GimpThumbnail

Properties

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

Description

The GimpThumbnail object

Details

GimpThumbnail

typedef struct _GimpThumbnail 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

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.

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

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.

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

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.

thumbnail :

a GimpThumbnail object

size :

the preferred size of the thumbnail image

Returns :

the thumbnail's GimpThumbState after the update

Since GIMP 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.

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.

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.

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

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.

thumbnail :

a GimpThumbnail object

Since GIMP 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.

thumbnail :

a GimpThumbnail object

size :

the thumbnail size which should not be deleted

Since GIMP 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.

thumbnail :

a GimpThumbnail object

Returns :

TRUE if a failure thumbnail exists or

Since GIMP 2.2

Property Details

The "image-filesize" property

  "image-filesize"           gint64                : Read / Write

Size of the image file in bytes.

Allowed values: >= 0

Default value: 0


The "image-height" property

  "image-height"             gint                  : Read / Write

Height of the image in pixels.

Allowed values: >= 0

Default value: 0


The "image-mimetype" property

  "image-mimetype"           gchar*                : Read / Write

Image mimetype.

Default value: NULL


The "image-mtime" property

  "image-mtime"              gint64                : Read / Write

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

Default value: 0


The "image-num-layers" property

  "image-num-layers"         gint                  : Read / Write

The number of layers in the image.

Allowed values: >= 0

Default value: 0


The "image-state" property

  "image-state"              GimpThumbState        : Read / Write

State of the image associated to the thumbnail object.

Default value: GIMP_THUMB_STATE_UNKNOWN


The "image-type" property

  "image-type"               gchar*                : Read / Write

String describing the type of the image format.

Default value: NULL


The "image-uri" property

  "image-uri"                gchar*                : Read / Write

URI of the image file.

Default value: NULL


The "image-width" property

  "image-width"              gint                  : Read / Write

Width of the image in pixels.

Allowed values: >= 0

Default value: 0


The "thumb-state" property

  "thumb-state"              GimpThumbState        : Read / Write

State of the thumbnail file.

Default value: GIMP_THUMB_STATE_UNKNOWN