2 * @defgroup Thumb Thumb
4 * @image html img/widget/thumb/preview-00.png
5 * @image latex img/widget/thumb/preview-00.eps
7 * A thumb object is used for displaying the thumbnail of an image or video.
8 * You must have compiled Elementary with Ethumb_Client support and the DBus
9 * service must be present and auto-activated in order to have thumbnails to
12 * Once the thumbnail object becomes visible, it will check if there is a
13 * previously generated thumbnail image for the file set on it. If not, it
14 * will start generating this thumbnail.
16 * Different config settings will cause different thumbnails to be generated
17 * even on the same file.
19 * Generated thumbnails are stored under @c $HOME/.thumbnails/. Check the
20 * Ethumb documentation to change this path, and to see other configuration
23 * Signals that you can add callbacks for are:
25 * - "clicked" - This is called when a user has clicked the thumb without dragging
27 * - "clicked,double" - This is called when a user has double-clicked the thumb.
28 * - "press" - This is called when a user has pressed down the thumb.
29 * - "generate,start" - The thumbnail generation started.
30 * - "generate,stop" - The generation process stopped.
31 * - "generate,error" - The generation failed.
32 * - "load,error" - The thumbnail image loading failed.
38 * An example of use of thumbnail:
40 * - @ref thumb_example_01
49 * @enum _Elm_Thumb_Animation_Setting
50 * @typedef Elm_Thumb_Animation_Setting
52 * Used to set if a video thumbnail is animating or not.
56 typedef enum _Elm_Thumb_Animation_Setting
58 ELM_THUMB_ANIMATION_START = 0, /**< Play animation once */
59 ELM_THUMB_ANIMATION_LOOP, /**< Keep playing animation until stop is requested */
60 ELM_THUMB_ANIMATION_STOP, /**< Stop playing the animation */
61 ELM_THUMB_ANIMATION_LAST
62 } Elm_Thumb_Animation_Setting;
65 * Add a new thumb object to the parent.
67 * @param parent The parent object.
68 * @return The new object or NULL if it cannot be created.
70 * @see elm_thumb_file_set()
71 * @see elm_thumb_ethumb_client_get()
75 EAPI Evas_Object *elm_thumb_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
78 * Reload thumbnail if it was generated before.
80 * @param obj The thumb object to reload
82 * This is useful if the ethumb client configuration changed, like its
83 * size, aspect or any other property one set in the handle returned
84 * by elm_thumb_ethumb_client_get().
86 * If the options didn't change, the thumbnail won't be generated again, but
87 * the old one will still be used.
89 * @see elm_thumb_file_set()
93 EAPI void elm_thumb_reload(Evas_Object *obj) EINA_ARG_NONNULL(1);
96 * Set the file that will be used as thumbnail.
98 * @param obj The thumb object.
99 * @param file The path to file that will be used as thumb.
100 * @param key The key used in case of an EET file.
102 * The file can be an image or a video (in that case, acceptable extensions are:
103 * avi, mp4, ogv, mov, mpg and wmv). To start the video animation, use the
104 * function elm_thumb_animate().
106 * @see elm_thumb_file_get()
107 * @see elm_thumb_reload()
108 * @see elm_thumb_animate()
112 EAPI void elm_thumb_file_set(Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
115 * Get the image or video path and key used to generate the thumbnail.
117 * @param obj The thumb object.
118 * @param file Pointer to filename.
119 * @param key Pointer to key.
121 * @see elm_thumb_file_set()
122 * @see elm_thumb_path_get()
126 EAPI void elm_thumb_file_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1);
129 * Get the path and key to the image or video generated by ethumb.
131 * One just need to make sure that the thumbnail was generated before getting
132 * its path; otherwise, the path will be NULL. One way to do that is by asking
133 * for the path when/after the "generate,stop" smart callback is called.
135 * @param obj The thumb object.
136 * @param file Pointer to thumb path.
137 * @param key Pointer to thumb key.
139 * @see elm_thumb_file_get()
143 EAPI void elm_thumb_path_get(const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1);
146 * Set the animation state for the thumb object. If its content is an animated
147 * video, you may start/stop the animation or tell it to play continuously and
150 * @param obj The thumb object.
151 * @param setting The animation setting.
153 * @see elm_thumb_file_set()
157 EAPI void elm_thumb_animate_set(Evas_Object *obj, Elm_Thumb_Animation_Setting s) EINA_ARG_NONNULL(1);
160 * Get the animation state for the thumb object.
162 * @param obj The thumb object.
163 * @return getting The animation setting or @c ELM_THUMB_ANIMATION_LAST,
166 * @see elm_thumb_animate_set()
170 EAPI Elm_Thumb_Animation_Setting elm_thumb_animate_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
173 * Get the ethumb_client handle so custom configuration can be made.
175 * @return Ethumb_Client instance or NULL.
177 * This must be called before the objects are created to be sure no object is
178 * visible and no generation started.
183 * #include <Elementary.h>
184 * #ifndef ELM_LIB_QUICKLAUNCH
186 * elm_main(int argc, char **argv)
188 * Ethumb_Client *client;
194 * client = elm_thumb_ethumb_client_get();
197 * ERR("could not get ethumb_client");
200 * ethumb_client_size_set(client, 100, 100);
201 * ethumb_client_crop_align_set(client, 0.5, 0.5);
204 * // Create elm_thumb objects here
214 * @note There's only one client handle for Ethumb, so once a configuration
215 * change is done to it, any other request for thumbnails (for any thumbnail
216 * object) will use that configuration. Thus, this configuration is global.
220 EAPI void *elm_thumb_ethumb_client_get(void);
223 * Get the ethumb_client connection state.
225 * @return EINA_TRUE if the client is connected to the server or EINA_FALSE
228 EAPI Eina_Bool elm_thumb_ethumb_client_connected(void);
231 * Make the thumbnail 'editable'.
233 * @param obj Thumb object.
234 * @param set Turn on or off editability. Default is @c EINA_FALSE.
236 * This means the thumbnail is a valid drag target for drag and drop, and can be
239 * @see elm_thumb_editable_get()
243 EAPI Eina_Bool elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit) EINA_ARG_NONNULL(1);
246 * Make the thumbnail 'editable'.
248 * @param obj Thumb object.
249 * @return Editability.
251 * This means the thumbnail is a valid drag target for drag and drop, and can be
254 * @see elm_thumb_editable_set()
258 EAPI Eina_Bool elm_thumb_editable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);