aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/ethumb/Ethumb.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/ethumb/Ethumb.h')
-rw-r--r--src/lib/ethumb/Ethumb.h453
1 files changed, 48 insertions, 405 deletions
diff --git a/src/lib/ethumb/Ethumb.h b/src/lib/ethumb/Ethumb.h
index 5d1fb0c31c..d506be2996 100644
--- a/src/lib/ethumb/Ethumb.h
+++ b/src/lib/ethumb/Ethumb.h
@@ -2,7 +2,6 @@
#define __ETHUMB_H__ 1
#include <Eina.h>
-#include <Efl_Config.h>
#ifdef EAPI
# undef EAPI
@@ -34,94 +33,31 @@
extern "C" {
#endif
-#define ETHUMB_VERSION_MAJOR EFL_VERSION_MAJOR
-#define ETHUMB_VERSION_MINOR EFL_VERSION_MINOR
- /**
- * @typedef Ethumb_Version
- * Represents the current version of Ethumb
- */
+#define ETHUMB_VERSION_MAJOR 1
+#define ETHUMB_VERSION_MINOR 8
+
typedef struct _Ethumb_Version
{
- int major; /** < major (binary or source incompatible changes) */
- int minor; /** < minor (new features, bugfixes, major improvements version) */
- int micro; /** < micro (bugfix, internal improvements, no new features version) */
- int revision; /** < git revision (0 if a proper release or the git revision number Ethumb is built from) */
+ int major;
+ int minor;
+ int micro;
+ int revision;
} Ethumb_Version;
-
+
EAPI extern Ethumb_Version *ethumb_version;
-
-/**
- * @page ethumb_main Ethumb
- *
- * @date 2009 (created)
- *
- * @section toc Table of Contents
- *
- * @li @ref ethumb_main_intro
- * @li @ref ethumb_main_compiling
- * @li @ref ethumb_main_next_steps
- *
- * @section ethumb_main_intro Introduction
- *
- * Ethumb will use @ref Evas to generate thumbnail images of given
- * files. The API allows great customization of the generated files
- * and also helps compling to FreeDesktop.Org Thumbnail Specification
- * (http://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html)
- *
- * However, thumbnailing can be an expensive process that will impact
- * your application experience, blocking animations and user
- * interaction during the generation. Another problem is that one
- * should try to cache the thumbnails in a place that other
- * applications can benefit from the file.
- *
- * @ref Ethumb_Client exists to solve this. It will communicate with a
- * server using standard D-Bus protocol. The server will use @ref
- * Ethumb itself to generate the thumbnail images and cache them using
- * FreeDesktop.Org standard. It is recommended that most applications
- * use @ref Ethumb_Client instead of @ref Ethumb directly.
- *
- * @section ethumb_main_compiling How to compile
- *
- * Ethumb is a library your application links to. The procedure for
- * this is very simple. Note that usually you want the D-Bus client
- * library. You simply have to compile your application with the
- * appropriate compiler flags that the @c pkg-config script
- * outputs. For example:
- *
- * Compiling C or C++ files into object files:
- *
- * @verbatim
- gcc -c -o main.o main.c `pkg-config --cflags ethumb_client`
- @endverbatim
- *
- * Linking object files into a binary executable:
- *
- * @verbatim
- gcc -o my_application main.o `pkg-config --libs ethumb_client`
- @endverbatim
- *
- * See @ref pkgconfig
- *
- * @section ethumb_main_next_steps Next Steps
- *
- * After you understood what Ethumb is and installed it in your system
- * you should proceed understanding the programming interface.
- *
- * Recommended reading:
- *
- * @li @ref Ethumb_Client to generate thumbnails using a server
- * (recommended).
- * @li @ref Ethumb to generate thumbnails in the local process.
- *
- */
-
+
/**
- * @defgroup Ethumb Ethumb
+ * @internal
+ * @defgroup Ethumb_Group Ethumb
+ * @ingroup EFL_Group
*
* @{
*/
+
/**
- * @defgroup Ethumb_Basics Ethumb Basics
+ * @internal
+ * @defgroup Ethumb_Basics_Group Ethumb Basics
+ * @ingroup Ethumb_Group
*
* Functions that all users must know of to use Ethumb.
*
@@ -144,34 +80,34 @@ typedef struct _Ethumb Ethumb;
*/
typedef void (*Ethumb_Generate_Cb)(void *data, Ethumb *e, Eina_Bool success);
-/**
- * @brief Initialize ethumb.
- * @return 1 or greater on success, 0 otherwise.
- */
EAPI int ethumb_init(void);
-/**
- * @brief Shutdown ethumb, unloading all currently-loaded modules.
- * @return 0 if ethumb shuts down, an integer greater than 0 otherwise.
- */
EAPI int ethumb_shutdown(void);
-/**
- * @brief Create a new ethumb object.
- * return The newly-created ethumb object
- */
EAPI Ethumb * ethumb_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Free an ethumb object.
- */
EAPI void ethumb_free(Ethumb *e);
+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 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;
+
+EAPI Ethumb *ethumb_dup(const Ethumb *e) EINA_ARG_NONNULL(1);
+EAPI Eina_Bool ethumb_cmp(const Ethumb *e1, const Ethumb *e2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE;
+EAPI int ethumb_hash(const void *key, int key_length) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
+EAPI int ethumb_key_cmp(const void *key1, int key1_length,
+ const void *key2, int key2_length) EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT EINA_PURE;
+EAPI unsigned int ethumb_length(const void *key) EINA_PURE EINA_WARN_UNUSED_RESULT;
+
/**
* @}
*/
/**
- * @defgroup Ethumb_Setup Ethumb Fine Tune Setup
+ * @internal
+ * @defgroup Ethumb_Setup_Group Ethumb Fine Tune Setup
+ * @ingroup Ethumb_Group
*
* How to fine tune thumbnail generation, setting size, aspect,
* frames, quality and so on.
@@ -179,64 +115,13 @@ EAPI void ethumb_free(Ethumb *e);
* @{
*/
-/**
- *
- * @brief Set the Ethumb Frame
- *
- * This can be used to simulate wood frames in the Thumbnails
- *
- * @param e handle of the current thumbnailer.
- * @param theme_file the edje theme file
- * @param group the edje group in theme
- * @param swallow the edje swallow in theme
- *
- * @return EINA_TRUE on success and EINA_FALSE on failure
- */
EAPI Eina_Bool ethumb_frame_set(Ethumb *e, const char *theme_file, const char *group, const char *swallow) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Retreives the current ethumb frame of and Ethumb instance.
- *
- * @param e handle of the current thumbnailer.
- * @param theme_file will be setted with the edje theme
- * @param group will be setted with the edje group
- * @param swallow will be setted with the edje swallow
- */
EAPI void ethumb_frame_get(const Ethumb *e, const char **theme_file, const char **group, const char **swallow) EINA_ARG_NONNULL(1);
-/**
- * @brief Set the ethumb thumbnails path
- *
- * @param e handle of the current thumbnailer.
- * @param path The thumbnails path
- *
- */
EAPI void ethumb_thumb_dir_path_set(Ethumb *e, const char *path) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Get the ethumb thumbnails path
- *
- * @param e handle of the current thumbnailer.
- *
- * @return The thumbnails path for the current thumbnailer
- */
EAPI const char *ethumb_thumb_dir_path_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-/**
- * @brief Set the thumbnails category
- *
- * @param e handle of the current thumbnailer.
- * @param category the category to set
- */
EAPI void ethumb_thumb_category_set(Ethumb *e, const char *category) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Get the thumbnails category
- *
- * @param e handle of the current thumbnailer
- *
- * @return the current thumbnailer thumbnails category
- */
EAPI const char *ethumb_thumb_category_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI void ethumb_thumb_path_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1);
@@ -244,12 +129,18 @@ EAPI void ethumb_thumb_path_get(Ethumb *e, const char **path, const char
EAPI void ethumb_thumb_hash(Ethumb *e) EINA_ARG_NONNULL(1);
EAPI void ethumb_thumb_hash_copy(Ethumb *dst, const Ethumb *src) EINA_ARG_NONNULL(1, 2);
+/**
+ * @brief Enumeration of Ethumb thumb FDO size
+ */
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;
+/**
+ * @brief Enumeration of Ethumb thumb format type
+ */
typedef enum _Ethumb_Thumb_Format
{
ETHUMB_THUMB_FDO, /**< PNG as defined by FreeDesktop.Org standard */
@@ -257,6 +148,9 @@ typedef enum _Ethumb_Thumb_Format
ETHUMB_THUMB_EET /**< EFL's own storage system, supports key parameter */
} Ethumb_Thumb_Format;
+/**
+ * @brief Enumeration of Ethumb thumb aspect type
+ */
typedef enum _Ethumb_Thumb_Aspect
{
ETHUMB_THUMB_KEEP_ASPECT, /**< keep original proportion between width and height */
@@ -264,6 +158,9 @@ typedef enum _Ethumb_Thumb_Aspect
ETHUMB_THUMB_CROP /**< keep aspect but crop (cut) the largest dimension */
} Ethumb_Thumb_Aspect;
+/**
+ * @brief Enumeration of Ethumb orientation type
+ */
typedef enum _Ethumb_Thumb_Orientation
{
ETHUMB_THUMB_ORIENT_NONE, /**< keep orientation as pixel data is */
@@ -279,300 +176,46 @@ typedef enum _Ethumb_Thumb_Orientation
EAPI void ethumb_thumb_fdo_set(Ethumb *e, Ethumb_Thumb_FDO_Size s) EINA_ARG_NONNULL(1);
-/**
- * @brief Set the size of thumbnails.
- *
- * @param e A pointer to an Ethumb object.
- * @param tw Thumbnail width.
- * @param th Thumbnail height.
- */
EAPI void ethumb_thumb_size_set(Ethumb *e, int tw, int th) EINA_ARG_NONNULL(1);
-/**
- * @brief Get the size of thumbnails.
- *
- * @param e A pointer to an Ethumb object.
- * @param[out] tw Pointer to an int to store the thumbnail width.
- * @param[out] th Pointer to an int to store the thumbnail height.
- */
EAPI void ethumb_thumb_size_get(const Ethumb *e, int *tw, int *th) EINA_ARG_NONNULL(1);
-/**
- * @brief Set the fileformat of the thumbnails
- *
- * Thumbnails are sent compressed; possible formats are PNG, JPEG and EET.
- *
- * @param e A pointer to an Ethumb object.
- */
EAPI void ethumb_thumb_format_set(Ethumb *e, Ethumb_Thumb_Format f) EINA_ARG_NONNULL(1);
-/**
- * @brief Get the fileformat of the thumbnails
- *
- * @param e A pointer to an Ethumb object.
- * @return The thumbnail fileformat
- *
- * @see ethumb_thumb_format_set
- */
EAPI Ethumb_Thumb_Format ethumb_thumb_format_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-/**
- * @brief Set the aspect ratio policy.
- *
- * When the source and thumbnail aspect ratios don't match, this policy sets
- * how to adapt from the former to the latter: resize keeping source aspect
- * ratio, resize ignoring it or crop.
- *
- * @param e A pointer to an Ethumb object.
- * @param aspect The new aspect ratio policy.
- */
-EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect aspect) EINA_ARG_NONNULL(1);
-/**
- * @brief Get the aspect ratio policy.
- *
- * @param e A pointer to an Ethumb object.
- * @return The aspect ratio policy.
- */
+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;
-/**
- * @brief Set the thumbnail rotation or flip.
- *
- * @param e A pointer to an Ethumb object.
- * @param orientation The new orientation.
- */
-EAPI void ethumb_thumb_orientation_set(Ethumb *e, Ethumb_Thumb_Orientation orientation) EINA_ARG_NONNULL(1);
-/**
- * @brief Get the thumbnail rotation.
- *
- * @param e A pointer to an Ethumb object.
- * @return The current rotation.
- */
+EAPI void ethumb_thumb_orientation_set(Ethumb *e, Ethumb_Thumb_Orientation o) EINA_ARG_NONNULL(1);
EAPI Ethumb_Thumb_Orientation ethumb_thumb_orientation_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);
-/**
- * @brief Set the thumbnail compression quality.
- *
- * @param e A pointer to an Ethumb object.
- * @param quality Compression quality (from 0 to 100, 100 being the best; default is 80)
- */
EAPI void ethumb_thumb_quality_set(Ethumb *e, int quality) EINA_ARG_NONNULL(1);
-/**
- * @brief Get the thumbnail compression quality.
- *
- * @param e A pointer to an Ethumb object.
- * @return The current compression quality (from 0 to 100, 100 being the best)
- */
EAPI int ethumb_thumb_quality_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
-/**
- * @brief Set the compression rate
- *
- * @param e handle of the current thumbnailer.
- * @param compress the compression rate (in percentage)
- *
- */
EAPI void ethumb_thumb_compress_set(Ethumb *e, int compress) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Get the compression rate
- *
- * @param e handle of the current thumbnailer.
- *
- * @return the compression rate (in percentage)
- */
EAPI int ethumb_thumb_compress_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
-/**
- * @brief set the video play start point
- *
- * Set the start point of video thumbnail
- *
- * @param e handle of the current thumbnailer.
- * @param start the start point (float from 0.0 to 1.0)
- */
EAPI void ethumb_video_start_set(Ethumb *e, float start) EINA_ARG_NONNULL(1);
-
-/**
- * @brief get the video play start point
- *
- * Get the start point of video thumbnail
- *
- * @param e handle of the current thumbnailer.
- *
- * @return the start point (float from 0.0 to 1.0)
- */
EAPI float ethumb_video_start_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-
-/**
- * @brief Set the video time (duration) in seconds.
- *
- * @param e handle of the current thumbnailer.
- * @param time the video duration in seconds
- */
EAPI void ethumb_video_time_set(Ethumb *e, float time) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Get the video time (duration) in seconds.
- *
- * @param e handle of the current thumbnailer.
- * @return the video duration in seconds
- */
EAPI float ethumb_video_time_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-
-/**
- * @brief 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.
- *
- * @param e handle of the current thumbnailer.
- * @param interval the frame display interval in seconds
- */
EAPI void ethumb_video_interval_set(Ethumb *e, float interval) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Get the video frame interval, in seconds
- *
- * @param e handle of the current thumbnailer.
- * @return the frame display interval in seconds
- */
EAPI float ethumb_video_interval_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-
-/**
- * @brief Set the number of times the video loops (if applicable).
- *
- * @param e A pointer to an Ethumb object.
- * @param ntimes The number of times the video loops.
- */
EAPI void ethumb_video_ntimes_set(Ethumb *e, unsigned int ntimes) EINA_ARG_NONNULL(1);
-/**
- * @brief Get the number of times the video loops (if applicable).
- *
- * @param e A pointer to an Ethumb object.
- * @return The number of times the video loops.
- */
EAPI unsigned int ethumb_video_ntimes_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-
-/**
- * @brief Set the thumbnail framerate.
- *
- * @param e A pointer to an Ethumb object.
- * @param fps New framerate of the thumbnail (default 10).
- */
EAPI void ethumb_video_fps_set(Ethumb *e, unsigned int fps) EINA_ARG_NONNULL(1);
-/**
- * @brief Get the thumbnail framerate.
- *
- * @param e A pointer to an Ethumb object.
- * @return Current framerate of the thumbnail.
- */
EAPI unsigned int ethumb_video_fps_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-/**
- * @brief Set the page number to thumbnail in paged documents
- *
- * @param e handle of the current thumbnailer.
- * @param page the page number.
- */
-EAPI void ethumb_document_page_set(Ethumb *e, unsigned int page) EINA_ARG_NONNULL(1);
-/**
- * @brief Get the page number thumbnailed in paged documents
- *
- * @param e handle of the current thumbnailer.
- * @return the page number.
- */
+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
- * @{
- */
-
-/**
- * @brief Set the file for which to generate thumbnails.
- *
- * @param e A pointer to an Ethumb object.
- * @param path The file to use.
- * @param key If @a path allows storing multiple resources in a single file
- * (EET or Edje for instance), @a key is the key used to locate the
- * right resource inside the file. NULL if not applicable.
- */
-EAPI Eina_Bool ethumb_file_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1, 2);
-/**
- * @brief Get the file for which to generate thumbnails.
- *
- * @param e A pointer to an Ethumb object.
- * @param[out] path The file being used.
- * @param[out] key The key used to locate the right resource in case the file
- * can store several of them. NULL if not applicable.
- * @see ethumb_file_set
- */
-EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Reset the source file information.
- *
- * @param e A pointer to an Ethumb object.
- */
-EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Generate the thumbnail.
- *
- * @param e handle of the current thumbnailer.
- * @param finished_cb The callback function to run on opertaion end
- * @param free_data The callback function to run on free data.
- *
- * @return EINA_TRUE on success and EINA_FALSE on failure
- */
-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);
-
-/**
- * @brief test if the thumbnailer exists
- *
- * @param e handle of the thumbnailer to test.
- *
- * @return EINA_TRUE if thumbnailer exists and EINA_FALSE otherwise.
- */
-EAPI Eina_Bool ethumb_exists(Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
-
-/**
- * @brief Duplicate an thumbnailer
- *
- * @param e Handle of the thumbnailer to duplicate
- *
- * @return a new allocated copy of the thumbnailer.
- */
-EAPI Ethumb *ethumb_dup(const Ethumb *e) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Compare two thumbnailers.
- *
- * @param e1 First handle of thumbnailer to compare
- * @param e2 Second handle of thumbnailer to compare
- *
- * @return EINA_TRUE if the thumbnailers are equal and EINA_FALSE otherwise
- */
-EAPI Eina_Bool ethumb_cmp(const Ethumb *e1, const Ethumb *e2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE;
-
-EAPI int ethumb_hash(const void *key, int key_length) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE;
-EAPI int ethumb_key_cmp(const void *key1, int key1_length,
- const void *key2, int key2_length) EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT EINA_PURE;
-EAPI unsigned int ethumb_length(const void *key) EINA_PURE EINA_WARN_UNUSED_RESULT;
-
- /**
- * @}
- */
-
-/**
* @}
*/