extern "C" {
#endif
-enum _Ethumb_Thumb_FDO_Size
-{
- ETHUMB_THUMB_NORMAL,
- ETHUMB_THUMB_LARGE
-};
-
-typedef enum _Ethumb_Thumb_FDO_Size Ethumb_Thumb_FDO_Size;
-
-enum _Ethumb_Thumb_Format
-{
- ETHUMB_THUMB_FDO,
- ETHUMB_THUMB_JPEG,
- ETHUMB_THUMB_EET
-};
-
-typedef enum _Ethumb_Thumb_Format Ethumb_Thumb_Format;
-
-enum _Ethumb_Thumb_Aspect
-{
- ETHUMB_THUMB_KEEP_ASPECT,
- ETHUMB_THUMB_IGNORE_ASPECT,
- ETHUMB_THUMB_CROP
-};
-
-typedef enum _Ethumb_Thumb_Aspect Ethumb_Thumb_Aspect;
-
-typedef struct _Ethumb_Frame Ethumb_Frame;
+/**
+ * @defgroup Ethumb Ethumb
+ *
+ * @{
+ */
+/**
+ * @defgroup Ethumb_Basics Ethumb Basics
+ *
+ * Functions that all users must know of to use Ethumb.
+ *
+ * @{
+ */
+
+/**
+ * @brief thumbnailer handle.
+ *
+ * The handle is returned by ethumb_new() and destroyed by ethumb_free().
+ */
typedef struct _Ethumb Ethumb;
+
+/**
+ * @brief reports results of ethumb_generate().
+ *
+ * @param data extra context given to ethumb_generate().
+ * @param e handle of the current thumbnailer.
+ * @param success @c EINA_TRUE if generated or @c EINA_FALSE on errors.
+ */
typedef void (*Ethumb_Generate_Cb)(void *data, Ethumb *e, Eina_Bool success);
EAPI int ethumb_init(void);
EAPI Ethumb * ethumb_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
EAPI void ethumb_free(Ethumb *e);
-EAPI void ethumb_thumb_fdo_set(Ethumb *e, Ethumb_Thumb_FDO_Size s) EINA_ARG_NONNULL(1);
-
-EAPI void ethumb_thumb_size_set(Ethumb *e, int tw, int th) EINA_ARG_NONNULL(1);
-EAPI void ethumb_thumb_size_get(const Ethumb *e, int *tw, int *th) EINA_ARG_NONNULL(1);
+/**
+ * @}
+ */
-EAPI void ethumb_thumb_format_set(Ethumb *e, Ethumb_Thumb_Format f) EINA_ARG_NONNULL(1);
-EAPI Ethumb_Thumb_Format ethumb_thumb_format_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+/**
+ * @defgroup Ethumb_Setup Ethumb Fine Tune Setup
+ *
+ * How to fine tune thumbnail generation, setting size, aspect,
+ * frames, quality and so on.
+ *
+ * @{
+ */
-EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect a) EINA_ARG_NONNULL(1);
-EAPI Ethumb_Thumb_Aspect ethumb_thumb_aspect_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI Eina_Bool ethumb_frame_set(Ethumb *e, const char *theme_file, const char *group, const char *swallow) EINA_ARG_NONNULL(1);
+EAPI void ethumb_frame_get(const Ethumb *e, const char **theme_file, const char **group, const char **swallow) EINA_ARG_NONNULL(1);
-EAPI void ethumb_thumb_crop_align_set(Ethumb *e, float x, float y) EINA_ARG_NONNULL(1);
-EAPI void ethumb_thumb_crop_align_get(const Ethumb *e, float *x, float *y) EINA_ARG_NONNULL(1);
+EAPI void ethumb_thumb_dir_path_set(Ethumb *e, const char *path) EINA_ARG_NONNULL(1);
+EAPI const char *ethumb_thumb_dir_path_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-EAPI void ethumb_thumb_quality_set(Ethumb *e, int quality) EINA_ARG_NONNULL(1);
-EAPI int ethumb_thumb_quality_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
+EAPI void ethumb_thumb_category_set(Ethumb *e, const char *category) EINA_ARG_NONNULL(1);
+EAPI const char *ethumb_thumb_category_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-EAPI void ethumb_thumb_compress_set(Ethumb *e, int compress) EINA_ARG_NONNULL(1);
-EAPI int ethumb_thumb_compress_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
+EAPI void ethumb_thumb_path_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1);
+EAPI void ethumb_thumb_path_get(Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1);
-EAPI Eina_Bool ethumb_frame_set(Ethumb *e, const char *theme_file, const char *group, const char *swallow) EINA_ARG_NONNULL(1);
-EAPI void ethumb_frame_get(const Ethumb *e, const char **theme_file, const char **group, const char **swallow) EINA_ARG_NONNULL(1);
+typedef enum _Ethumb_Thumb_FDO_Size
+{
+ ETHUMB_THUMB_NORMAL, /**< 128x128 as defined by FreeDesktop.Org standard */
+ ETHUMB_THUMB_LARGE /**< 256x256 as defined by FreeDesktop.Org standard */
+} Ethumb_Thumb_FDO_Size;
-EAPI void ethumb_thumb_dir_path_set(Ethumb *e, const char *path) EINA_ARG_NONNULL(1);
-EAPI const char * ethumb_thumb_dir_path_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+typedef enum _Ethumb_Thumb_Format
+{
+ ETHUMB_THUMB_FDO, /**< PNG as defined by FreeDesktop.Org standard */
+ ETHUMB_THUMB_JPEG, /**< JPEGs are often smaller and faster to read/write */
+ ETHUMB_THUMB_EET /**< EFL's own storage system, supports key parameter */
+} Ethumb_Thumb_Format;
-EAPI void ethumb_thumb_category_set(Ethumb *e, const char *category) EINA_ARG_NONNULL(1);
-EAPI const char * ethumb_thumb_category_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+typedef enum _Ethumb_Thumb_Aspect
+{
+ ETHUMB_THUMB_KEEP_ASPECT, /**< keep original proportion between width and height */
+ ETHUMB_THUMB_IGNORE_ASPECT, /**< ignore aspect and foce it to match thumbnail's width and height */
+ ETHUMB_THUMB_CROP /**< keep aspect but crop (cut) the largest dimension */
+} Ethumb_Thumb_Aspect;
+EAPI void ethumb_thumb_fdo_set(Ethumb *e, Ethumb_Thumb_FDO_Size s) EINA_ARG_NONNULL(1);
-EAPI void ethumb_video_start_set(Ethumb *e, float start) EINA_ARG_NONNULL(1);
-EAPI float ethumb_video_start_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-EAPI void ethumb_video_time_set(Ethumb *e, float time) EINA_ARG_NONNULL(1);
-EAPI float ethumb_video_time_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-EAPI void ethumb_video_interval_set(Ethumb *e, float interval) EINA_ARG_NONNULL(1);
-EAPI float ethumb_video_interval_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-EAPI void ethumb_video_ntimes_set(Ethumb *e, int ntimes) EINA_ARG_NONNULL(1);
-EAPI int ethumb_video_ntimes_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-EAPI void ethumb_video_fps_set(Ethumb *e, int fps) EINA_ARG_NONNULL(1);
-EAPI int ethumb_video_fps_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI void ethumb_thumb_size_set(Ethumb *e, int tw, int th) EINA_ARG_NONNULL(1);
+EAPI void ethumb_thumb_size_get(const Ethumb *e, int *tw, int *th) EINA_ARG_NONNULL(1);
+EAPI void ethumb_thumb_format_set(Ethumb *e, Ethumb_Thumb_Format f) EINA_ARG_NONNULL(1);
+EAPI Ethumb_Thumb_Format ethumb_thumb_format_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-EAPI void ethumb_document_page_set(Ethumb *e, int page) EINA_ARG_NONNULL(1);
-EAPI int ethumb_document_page_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect a) EINA_ARG_NONNULL(1);
+EAPI Ethumb_Thumb_Aspect ethumb_thumb_aspect_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI void ethumb_thumb_crop_align_set(Ethumb *e, float x, float y) EINA_ARG_NONNULL(1);
+EAPI void ethumb_thumb_crop_align_get(const Ethumb *e, float *x, float *y) EINA_ARG_NONNULL(1);
+
+EAPI void ethumb_thumb_quality_set(Ethumb *e, int quality) EINA_ARG_NONNULL(1);
+EAPI int ethumb_thumb_quality_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
+
+EAPI void ethumb_thumb_compress_set(Ethumb *e, int compress) EINA_ARG_NONNULL(1);
+EAPI int ethumb_thumb_compress_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
+
+EAPI void ethumb_video_start_set(Ethumb *e, float start) EINA_ARG_NONNULL(1);
+EAPI float ethumb_video_start_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI void ethumb_video_time_set(Ethumb *e, float time) EINA_ARG_NONNULL(1);
+EAPI float ethumb_video_time_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI void ethumb_video_interval_set(Ethumb *e, float interval) EINA_ARG_NONNULL(1);
+EAPI float ethumb_video_interval_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI void ethumb_video_ntimes_set(Ethumb *e, unsigned int ntimes) EINA_ARG_NONNULL(1);
+EAPI unsigned int ethumb_video_ntimes_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+EAPI void ethumb_video_fps_set(Ethumb *e, unsigned int fps) EINA_ARG_NONNULL(1);
+EAPI unsigned int ethumb_video_fps_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+
+
+EAPI void ethumb_document_page_set(Ethumb *e, unsigned int page) EINA_ARG_NONNULL(1);
+EAPI unsigned int ethumb_document_page_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup Ethumb_Basics Ethumb Basics
+ * @{
+ */
EAPI Eina_Bool ethumb_file_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1, 2);
-EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1);
-EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1);
-EAPI void ethumb_thumb_path_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1);
-EAPI void ethumb_thumb_path_get(Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1);
+EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1);
+EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1);
+
EAPI Eina_Bool ethumb_generate(Ethumb *e, Ethumb_Generate_Cb finished_cb, const void *data, Eina_Free_Cb free_data) EINA_ARG_NONNULL(1, 2);
EAPI Eina_Bool ethumb_exists(Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
+/**
+ * @}
+ */
+
+/**
+ * @}
+ */
#ifdef __cplusplus
}
* @endcond
*/
+/**
+ * @brief Initialize the Ethumb_Client library.
+ *
+ * @return 1 or greater on success, 0 on error.
+ *
+ * This function sets up all the Ethumb_Client module dependencies. It
+ * returns 0 on failure (that is, when one of the dependency fails to
+ * initialize), otherwise it returns the number of times it has
+ * already been called.
+ *
+ * When Ethumb_Client is not used anymore, call
+ * ethumb_client_shutdown() to shut down the Ethumb_Client library.
+ *
+ * @see ethumb_client_shutdown()
+ * @see ethumb_client_connect()
+ * @see @ref tutorial_ethumb_client
+ */
EAPI int
ethumb_client_init(void)
{
return ++_initcount;
}
+/**
+ * @brief Shut down the Ethumb_Client library.
+ *
+ * @return 0 when everything is shut down, 1 or greater if there are
+ * other users of the Ethumb_Client library pending shutdown.
+ *
+ * This function shuts down the Ethumb_Client library. It returns 0
+ * when it has been called the same number of times than
+ * ethumb_client_init(). In that case it shut down all the
+ * Ethumb_Client modules dependencies.
+ *
+ * Once this function succeeds (that is, @c 0 is returned), you must
+ * not call any of the Eina function anymore. You must call
+ * ethumb_client_init() again to use the Ethumb_Client functions
+ * again.
+ */
EAPI int
ethumb_client_shutdown(void)
{
*
* This is the destructor of Ethumb_Client, after it's disconnected
* the client handle is now gone and should not be used.
+ *
+ * @param client client instance to be destroyed. Must @b not be @c
+ * NULL.
*/
EAPI void
ethumb_client_disconnect(Ethumb_Client *client)
dbus_message_iter_append_basic(&viter, DBUS_TYPE_DOUBLE, &video_interval);
_close_variant_iter(viter);
- _open_variant_iter("video_ntimes", "i", viter);
+ _open_variant_iter("video_ntimes", "u", viter);
video_ntimes = ethumb_video_ntimes_get(e);
- dbus_message_iter_append_basic(&viter, DBUS_TYPE_INT32, &video_ntimes);
+ dbus_message_iter_append_basic(&viter, DBUS_TYPE_UINT32, &video_ntimes);
_close_variant_iter(viter);
- _open_variant_iter("video_fps", "i", viter);
+ _open_variant_iter("video_fps", "u", viter);
video_fps = ethumb_video_fps_get(e);
- dbus_message_iter_append_basic(&viter, DBUS_TYPE_INT32, &video_fps);
+ dbus_message_iter_append_basic(&viter, DBUS_TYPE_UINT32, &video_fps);
_close_variant_iter(viter);
- _open_variant_iter("document_page", "i", viter);
+ _open_variant_iter("document_page", "u", viter);
document_page = ethumb_document_page_get(e);
- dbus_message_iter_append_basic(&viter, DBUS_TYPE_INT32, &document_page);
+ dbus_message_iter_append_basic(&viter, DBUS_TYPE_UINT32, &document_page);
_close_variant_iter(viter);
#undef _open_variant_iter
* ~/.thumbnails/SIZE, with size being either normal (128x128) or
* large (256x256).
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param s size identifier, either #ETHUMB_THUMB_NORMAL (0) or
* #ETHUMB_THUMB_LARGE (1).
*
/**
* Configure future request to use custom size.
*
- * @param w width, default is 128.
- * @param h height, default is 128.
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param tw width, default is 128.
+ * @param th height, default is 128.
*/
EAPI void
ethumb_client_size_set(Ethumb_Client *client, int tw, int th)
/**
* Retrieve future request to use custom size.
*
- * @param w where to return width. May be #NULL.
- * @param h where to return height. May be #NULL.
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param tw where to return width. May be @c NULL.
+ * @param th where to return height. May be @c NULL.
*/
EAPI void
ethumb_client_size_get(const Ethumb_Client *client, int *tw, int *th)
/**
* Configure format to use for future requests.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param f format identifier to use, either #ETHUMB_THUMB_FDO (0),
* #ETHUMB_THUMB_JPEG (1) or #ETHUMB_THUMB_EET (2). Default is FDO.
*/
/**
* Retrieve format to use for future requests.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ *
* @return format identifier to use, either #ETHUMB_THUMB_FDO (0),
* #ETHUMB_THUMB_JPEG (1) or #ETHUMB_THUMB_EET (2).
*/
* pixels from left and 250 pixels from right being lost, that is just
* the 500x500 central pixels of image will be considered for scaling.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param a aspect mode identifier, either #ETHUMB_THUMB_KEEP_ASPECT (0),
* #ETHUMB_THUMB_IGNORE_ASPECT (1) or #ETHUMB_THUMB_CROP (2).
*/
/**
* Get current aspect in use for requests.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ *
* @return aspect in use for future requests.
*/
EAPI Ethumb_Thumb_Aspect
/**
* Configure crop alignment in use for future requests.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param x horizontal alignment. 0.0 means left side will be visible
* or right side is being lost. 1.0 means right side will be
* visible or left side is being lost. 0.5 means just center is
/**
* Get current crop alignment in use for requests.
*
- * @param x where to return horizontal alignment. May be #NULL.
- * @param y where to return vertical alignment. May be #NULL.
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param x where to return horizontal alignment. May be @c NULL.
+ * @param y where to return vertical alignment. May be @c NULL.
*/
EAPI void
ethumb_client_crop_align_get(const Ethumb_Client *client, float *x, float *y)
/**
* Configure quality to be used in thumbnails.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param quality value from 0 to 100, default is 80. The effect
* depends on the format being used, PNG will not use it.
*/
/**
* Get quality to be used in thumbnails.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ *
* @return quality value from 0 to 100, default is 80. The effect
* depends on the format being used, PNG will not use it.
*/
/**
* Configure compression level used in requests.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param compress value from 0 to 9, default is 9. The effect
* depends on the format being used, JPEG will not use it.
*/
/**
* Get compression level used in requests.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ *
* @return compress value from 0 to 9, default is 9. The effect
* depends on the format being used, JPEG will not use it.
*/
* of thumbnails, but sometimes it's useful to have it composited and
* avoid runtime overhead.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param file file path to edje.
* @param group group inside edje to use.
* @param swallow name of swallow part.
/**
* Configure where to store thumbnails in future requests.
*
+ * This value will be used to generate thumbnail paths, that is, it
+ * will be used when ethumb_client_thumb_path_set() was not called
+ * after last ethumb_client_file_set().
+ *
* Note that this is the base, a category is added to this path as a
- * sub directory.
+ * sub directory. This is not the final directory where files are
+ * stored, the thumbnail system will account @b category as well, see
+ * ethumb_client_category_set().
*
+ * As other options, this value will only be applied to future
+ * requests.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param path base directory where to store thumbnails. Default is
* ~/.thumbnails
+ *
+ * @see ethumb_client_category_set()
*/
EAPI void
ethumb_client_dir_path_set(Ethumb_Client *client, const char *path)
ethumb_thumb_dir_path_set(client->ethumb, path);
}
+/**
+ * Get base directory path where to store thumbnails.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ *
+ * @return pointer to internal string with current path. This string
+ * should not be modified or freed.
+ *
+ * @see ethumb_client_dir_path_set()
+ */
EAPI const char *
ethumb_client_dir_path_get(const Ethumb_Client *client)
{
/**
* Category directory to store thumbnails.
*
+ * This value will be used to generate thumbnail paths, that is, it
+ * will be used when ethumb_client_thumb_path_set() was not called
+ * after last ethumb_client_file_set().
+ *
+ * This is a sub-directory inside base directory
+ * (ethumb_client_dir_path_set()) that creates a namespace to avoid
+ * different options resulting in the same file.
+ *
+ * As other options, this value will only be applied to future
+ * requests.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param category category sub directory to store thumbnail. Default
* is either "normal" or "large" for FDO compliant thumbnails
* or WIDTHxHEIGHT-ASPECT[-FRAMED]-FORMAT. It can be a string
- * or None to use auto generated names.
+ * or @c NULL to use auto generated names.
+ *
+ * @see ethumb_client_dir_path_set()
*/
EAPI void
ethumb_client_category_set(Ethumb_Client *client, const char *category)
ethumb_thumb_category_set(client->ethumb, category);
}
+/**
+ * Get category sub-directory where to store thumbnails.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ *
+ * @return pointer to internal string with current path. This string
+ * should not be modified or freed.
+ *
+ * @see ethumb_client_category_set()
+ */
EAPI const char *
ethumb_client_category_get(const Ethumb_Client *client)
{
return ethumb_thumb_category_get(client->ethumb);
}
+/**
+ * Set the video time (duration) in seconds.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param time duration (in seconds). Defaults to 3 seconds.
+ */
EAPI void
ethumb_client_video_time_set(Ethumb_Client *client, float time)
{
ethumb_video_time_set(client->ethumb, time);
}
+/**
+ * Set initial video position to start thumbnailing, in percentage.
+ *
+ * This is useful to avoid thumbnailing the company/producer logo or
+ * movie opening.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param start initial video positon to thumbnail, in percentage (0.0
+ * to 1.0, inclusive). Defaults to 10% (0.1).
+ */
EAPI void
ethumb_client_video_start_set(Ethumb_Client *client, float start)
{
EINA_SAFETY_ON_NULL_RETURN(client);
+ EINA_SAFETY_ON_FALSE_RETURN(start >= 0.0);
+ EINA_SAFETY_ON_FALSE_RETURN(start <= 1.0);
client->ethumb_dirty = 1;
ethumb_video_start_set(client->ethumb, start);
}
+/**
+ * Set the video frame interval, in seconds.
+ *
+ * This is useful for animated thumbnail and will define skip time
+ * before going to the next frame. Note that video backends might not
+ * be able to precisely skip that amount as it will depend on various
+ * factors, including video encoding.
+ *
+ * Although this seems similar to ethumb_client_video_fps_set(), this
+ * one is the time that will be used to seek. The math is simple, for
+ * each new frame the video position will be set to:
+ * ((video_length * start_time) + (interval * current_frame_number)).
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param interval time between frames, in seconds. Defaults to 0.05
+ * seconds.
+ */
EAPI void
ethumb_client_video_interval_set(Ethumb_Client *client, float interval)
{
ethumb_video_interval_set(client->ethumb, interval);
}
+/**
+ * Set the number of frames to thumbnail.
+ *
+ * This is useful for animated thumbnail and will define how many
+ * frames the generated file will have.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param ntimes number of times, must be greater than zero.
+ * Defaults to 3.
+ */
EAPI void
-ethumb_client_video_ntimes_set(Ethumb_Client *client, int ntimes)
+ethumb_client_video_ntimes_set(Ethumb_Client *client, unsigned int ntimes)
{
EINA_SAFETY_ON_NULL_RETURN(client);
+ EINA_SAFETY_ON_FALSE_RETURN(ntimes > 0);
client->ethumb_dirty = 1;
ethumb_video_ntimes_set(client->ethumb, ntimes);
}
+/**
+ * Set the number of frames per second to thumbnail the video.
+ *
+ * This configures the number of times per seconds the thumbnail will
+ * use to create thumbnails.
+ *
+ * Although this is similar to ethumb_client_video_interval_set(), it
+ * is the delay used between calling functions thata generates frames,
+ * while the other is the time used to skip inside the video.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param fps number of frames per second to thumbnail. Must be greater
+ * than zero. Defaults to 10.
+ */
EAPI void
-ethumb_client_video_fps_set(Ethumb_Client *client, int fps)
+ethumb_client_video_fps_set(Ethumb_Client *client, unsigned int fps)
{
EINA_SAFETY_ON_NULL_RETURN(client);
+ EINA_SAFETY_ON_FALSE_RETURN(fps > 0);
client->ethumb_dirty = 1;
ethumb_video_fps_set(client->ethumb, fps);
}
+/**
+ * Set the page number to thumbnail in paged documents.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param page page number, defaults to 0 (first).
+ */
EAPI void
-ethumb_client_document_page_set(Ethumb_Client *client, int page)
+ethumb_client_document_page_set(Ethumb_Client *client, unsigned int page)
{
EINA_SAFETY_ON_NULL_RETURN(client);
* from. This is only used for formats that allow multiple
* resources in one file, like EET or Edje (group name).
*
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
*/
EAPI Eina_Bool
ethumb_client_file_set(Ethumb_Client *client, const char *path, const char *key)
/**
* Get values set with ethumb_client_file_get()
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param path where to return configured path. May be @c NULL. If
+ * not @c NULL, then it will be a pointer to a stringshared
+ * instance, but @b no references are added (do it with
+ * eina_stringshare_ref())!
+ * @param key where to return configured key. May be @c NULL.If not @c
+ * NULL, then it will be a pointer to a stringshared instance,
+ * but @b no references are added (do it with
+ * eina_stringshare_ref())!
*/
EAPI void
ethumb_client_file_get(Ethumb_Client *client, const char **path, const char **key)
*
* Set these to @c NULL to forget previously given values. After
* ethumb_client_file_set() these values will be reset to @c NULL.
+ *
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
+ * @param path force generated thumbnail to the exact given path. If
+ * @c NULL, then reverts back to auto-generation.
+ * @param key force generated thumbnail to the exact given key. If
+ * @c NULL, then reverts back to auto-generation.
*/
EAPI void
ethumb_client_thumb_path_set(Ethumb_Client *client, const char *path, const char *key)
* This returns the value set with ethumb_client_thumb_path_set() or
* auto-generated by ethumb_client_thumb_exists() if it was not set.
*
+ * @param client the client instance to use. Must @b not be @c
+ * NULL. May be pending connected (can be called before @c
+ * connected_cb)
* @param path where to return configured path. May be @c NULL. If
* there was no path configured with
* ethumb_client_thumb_path_set() and
* @param client client instance. Must @b not be @c NULL and client
* must be configured with ethumb_client_file_set().
*
- * @return #EINA_TRUE if it exists, #EINA_FALSE otherwise.
+ * @return @c EINA_TRUE if it exists, @c EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ethumb_client_thumb_exists(Ethumb_Client *client)
#endif
/**
- * @defgroup Ethumb_Client Client
+ * @defgroup Ethumb_Client Ethumb Client
+ *
+ * @{
+ */
+
+/**
+ * @defgroup Ethumb_Client_Basics Ethumb Client Basics
+ *
+ * Functions that all users must know of to use Ethumb_Client.
*
* @{
*/
*
* @param data extra context given to ethumb_client_connect().
* @param client handle of the current connection to server.
- * @param success #EINA_TRUE if connected or #EINA_FALSE if it was not possible.
+ * @param success @c EINA_TRUE if connected or @c EINA_FALSE if it was
+ * not possible.
*/
typedef void (*Ethumb_Client_Connect_Cb)(void *data, Ethumb_Client *client, Eina_Bool success);
* @param client handle of the current connection to server.
* @param id identifier returned by ethumb_client_generate().
* @param file path set with ethumb_client_file_set().
- * @param key value set with ethumb_client_file_set() or #NULL.
+ * @param key value set with ethumb_client_file_set() or @c NULL.
* @param thumb_path where thumbnail was stored, either set with
* ethumb_client_thumb_path_set() or automatically calculated
* using parameters.
- * @param thumb_key key inside thumb_path where thumbnail was stored or #NULL.
- * @param success #EINA_TRUE if generated or #EINA_FALSE on errors.
+ * @param thumb_key key inside thumb_path where thumbnail was stored or @c NULL.
+ * @param success @c EINA_TRUE if generated or @c EINA_FALSE on errors.
*/
typedef void (*Ethumb_Client_Generate_Cb)(void *data, Ethumb_Client *client, int id, const char *file, const char *key, const char *thumb_path, const char *thumb_key, Eina_Bool success);
EAPI void ethumb_client_disconnect(Ethumb_Client *client);
EAPI void ethumb_client_on_server_die_callback_set(Ethumb_Client *client, Ethumb_Client_Die_Cb server_die_cb, const void *data, Eina_Free_Cb free_data);
+/**
+ * @}
+ */
+
+/**
+ * @defgroup Ethumb_Client_Setup Ethumb Client Fine Tune Setup
+ *
+ * How to fine tune thumbnail generation, setting size, aspect,
+ * frames, quality and so on.
+ *
+ * @{
+ */
+
EAPI void ethumb_client_fdo_set(Ethumb_Client *client, Ethumb_Thumb_FDO_Size s);
EAPI void ethumb_client_size_set(Ethumb_Client *client, int tw, int th);
EAPI void ethumb_client_size_get(const Ethumb_Client *client, int *tw, int *th);
EAPI void ethumb_client_video_time_set(Ethumb_Client *client, float time);
EAPI void ethumb_client_video_start_set(Ethumb_Client *client, float start);
EAPI void ethumb_client_video_interval_set(Ethumb_Client *client, float interval);
-EAPI void ethumb_client_video_ntimes_set(Ethumb_Client *client, int ntimes);
-EAPI void ethumb_client_video_fps_set(Ethumb_Client *client, int fps);
-EAPI void ethumb_client_document_page_set(Ethumb_Client *client, int page);
+EAPI void ethumb_client_video_ntimes_set(Ethumb_Client *client, unsigned int ntimes);
+EAPI void ethumb_client_video_fps_set(Ethumb_Client *client, unsigned int fps);
+EAPI void ethumb_client_document_page_set(Ethumb_Client *client, unsigned int page);
EAPI void ethumb_client_ethumb_setup(Ethumb_Client *client);
+EAPI void ethumb_client_thumb_path_set(Ethumb_Client *client, const char *path, const char *key);
+EAPI void ethumb_client_thumb_path_get(Ethumb_Client *client, const char **path, const char **key);
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup Ethumb_Client_Basics Ethumb Client Basics
+ * @{
+ */
EAPI Eina_Bool ethumb_client_file_set(Ethumb_Client *client, const char *path, const char *key);
EAPI void ethumb_client_file_get(Ethumb_Client *client, const char **path, const char **key);
EAPI void ethumb_client_file_free(Ethumb_Client *client);
-EAPI void ethumb_client_thumb_path_set(Ethumb_Client *client, const char *path, const char *key);
-EAPI void ethumb_client_thumb_path_get(Ethumb_Client *client, const char **path, const char **key);
EAPI Eina_Bool ethumb_client_thumb_exists(Ethumb_Client *client);
EAPI int ethumb_client_generate(Ethumb_Client *client, Ethumb_Client_Generate_Cb generated_cb, const void *data, Eina_Free_Cb free_data);
EAPI void ethumb_client_generate_cancel(Ethumb_Client *client, int id, Ethumb_Client_Generate_Cancel_Cb cancel_cb, const void *data, Eina_Free_Cb free_data);
EAPI void ethumb_client_generate_cancel_all(Ethumb_Client *client);
+/**
+ * @}
+ */
/**
* @}
projects / framework / uifw / ethumb.git / commitdiff