FmThumbnailLoader

## FmThumbnailLoader FmThumbnailLoader — A thumbnails cache loader and generator. |

## Synopsis

                        FmThumbnailLoader;
    struct              FmThumbnailLoaderBackend;
    void                (*FmThumbnailLoaderCallback)        (FmThumbnailLoader *req,
                                                             gpointer data);
    void                fm_thumbnail_loader_cancel          (FmThumbnailLoader *req);
    GObject *           fm_thumbnail_loader_get_data        (FmThumbnailLoader *req);
    FmFileInfo *        fm_thumbnail_loader_get_file_info   (FmThumbnailLoader *req);
    guint               fm_thumbnail_loader_get_size        (FmThumbnailLoader *req);
    FmThumbnailLoader * fm_thumbnail_loader_load            (FmFileInfo *src_file,
                                                             guint size,
                                                             FmThumbnailLoaderCallback callback,
                                                             gpointer user_data);
    gboolean            fm_thumbnail_loader_set_backend     (FmThumbnailLoaderBackend *_backend);

## Description

`include`: libfm/fm.h

This API allows to generate thumbnails for files and save them on disk then use that cache next time to display them.

## Details

### FmThumbnailLoader

    typedef struct _FmThumbnailLoader FmThumbnailLoader;

### struct FmThumbnailLoaderBackend

    struct FmThumbnailLoaderBackend {
        GObject* (*read_image_from_file)(const char* filename);
        GObject* (*read_image_from_stream)(GInputStream* stream, guint64 len, GCancellable* cancellable);
        gboolean (*write_image)(GObject* image, const char* filename);
        GObject* (*scale_image)(GObject* ori_pix, int new_width, int new_height);
        GObject* (*rotate_image)(GObject* image, int degree);
        int (*get_image_width)(GObject* image);
        int (*get_image_height)(GObject* image);
        char* (*get_image_text)(GObject* image, const char* key);
        gboolean (*set_image_text)(GObject* image, const char* key, const char* val);
        // const char* (*get_image_orientation)(GObject* image);
        // GObject* (*apply_orientation)(GObject* image);
    };

Abstract backend callbacks list.

`read_image_from_file` () | callback to read image by file path
`read_image_from_stream` () | callback to read image by opened GInputStream
`write_image` () | callback to write thumbnail file from image
`scale_image` () | callback to change image sizes
`rotate_image` () | callback to change image orientation
`get_image_width` () | callback to retrieve width from image
`get_image_height` () | callback to retrieve height from image
`get_image_text` () | callback to retrieve custom attributes text from image
`set_image_text` () | callback to set custom attributes text into image

### FmThumbnailLoaderCallback ()

    void                (*FmThumbnailLoaderCallback)        (FmThumbnailLoader *req,
                                                             gpointer data);

The callback to requestor when thumbnail is ready. Note that this call is done outside of GTK loop so if the callback wants to use any GTK API it should call `gdk_threads_enter()` and `gdk_threads_leave()` for safety.

`req` : | request descriptor
`data` : | user data provided when request was made

Since 1.2.0

### fm_thumbnail_loader_cancel ()

    void                fm_thumbnail_loader_cancel          (FmThumbnailLoader *req);

Cancels request. After return from this call the `req` becomes invalid and cannot be used. Caller will never get callback for cancelled request either.

`req` : | the request descriptor

Since 1.2.0

### fm_thumbnail_loader_get_data ()

    GObject *           fm_thumbnail_loader_get_data        (FmThumbnailLoader *req);

Retrieves loaded thumbnail. Returned data are owned by `req` and should be not freed by caller.

`req` : | request descriptor
Returns : | thumbnail. [transfer none]

Since 1.2.0

### fm_thumbnail_loader_get_file_info ()

    FmFileInfo *        fm_thumbnail_loader_get_file_info   (FmThumbnailLoader *req);

Retrieves file descriptor that request is for. Returned data are owned by `req` and should be not freed by caller.

`req` : | request descriptor
Returns : | file descriptor. [transfer none]

Since 1.2.0

### fm_thumbnail_loader_get_size ()

    guint               fm_thumbnail_loader_get_size        (FmThumbnailLoader *req);

Retrieves thumbnail size that request is for.

`req` : | request descriptor
Returns : | size in pixels.

Since 1.2.0

### fm_thumbnail_loader_load ()

    FmThumbnailLoader * fm_thumbnail_loader_load            (FmFileInfo *src_file,
                                                             guint size,
                                                             FmThumbnailLoaderCallback callback,
                                                             gpointer user_data);

Schedules loading/generation of thumbnail for `src_file`. If the request isn't cancelled then ready thumbnail will be given to the requestor in `callback`. Returned descriptor can be used to cancel the job.

`src_file` : | an image file
`size` : | thumbnail size
`callback` : | callback to requestor
`user_data` : | data provided for `callback`
Returns : | request descriptor. [transfer none]

Since 1.2.0

### fm_thumbnail_loader_set_backend ()

    gboolean            fm_thumbnail_loader_set_backend     (FmThumbnailLoaderBackend *_backend);

Sets callbacks list for further usage by thumbnail loader. Callbacks should implement operations with image representation for application specific model. This function can be called only once per application and every subsequent call will return `FALSE` and change nothing.

`_backend` : | callbacks list to set
Returns : | `TRUE` in case of success.

Since 1.2.0