2 * @defgroup Thumb Thumbnail
5 * @image html thumb_inheritance_tree.png
6 * @image latex thumb_inheritance_tree.eps
8 * @image html img/widget/thumb/preview-00.png
9 * @image latex img/widget/thumb/preview-00.eps
11 * A thumbnail object is used for displaying the thumbnail of an image
12 * or video. You must have compiled Elementary with @c Ethumb_Client
13 * support. Also, Ethumb's DBus service must be present and
14 * auto-activated in order to have thumbnails generated. You must also
15 * have a @b session bus, not a @b system one.
17 * Once the thumbnail object becomes visible, it will check if there
18 * is a previously generated thumbnail image for the file set on
19 * it. If not, it will start generating this thumbnail.
21 * Different configuration settings will cause different thumbnails to
22 * be generated even on the same file.
24 * Generated thumbnails are stored under @c $HOME/.thumbnails/. Check
25 * Ethumb's documentation to change this path, and to see other
26 * configuration options.
28 * This widget emits the following signals:
29 * - @c "clicked" - This is called when a user has clicked the
30 * thumbnail object without dragging it around.
31 * - @c "clicked,double" - This is called when a user has double-clicked
32 * the thumbnail object.
33 * - @c "press" - This is called when a user has pressed down over the
35 * - @c "generate,start" - The thumbnail generation has started.
36 * - @c "generate,stop" - The generation process has stopped.
37 * - @c "generate,error" - The thumbnail generation failed.
38 * - @c "load,error" - The thumbnail image loading failed.
44 * An example of use of thumbnail:
46 * - @ref thumb_example_01
55 * @enum Elm_Thumb_Animation_Setting
56 * @typedef Elm_Thumb_Animation_Setting
58 * Used to set if a video thumbnail is animating or not.
64 ELM_THUMB_ANIMATION_START = 0, /**< Play animation once */
65 ELM_THUMB_ANIMATION_LOOP, /**< Keep playing animation until stop is requested */
66 ELM_THUMB_ANIMATION_STOP, /**< Stop playing the animation */
67 ELM_THUMB_ANIMATION_LAST
68 } Elm_Thumb_Animation_Setting;
71 * Add a new thumb object to the parent.
73 * @param parent The parent object.
74 * @return The new object or NULL if it cannot be created.
76 * @see elm_thumb_file_set()
77 * @see elm_thumb_ethumb_client_get()
81 EAPI Evas_Object *elm_thumb_add(Evas_Object *parent);
84 * Reload thumbnail if it was generated before.
86 * @param obj The thumb object to reload
88 * This is useful if the ethumb client configuration changed, like its
89 * size, aspect or any other property one set in the handle returned
90 * by elm_thumb_ethumb_client_get().
92 * If the options didn't change, the thumbnail won't be generated again, but
93 * the old one will still be used.
95 * @see elm_thumb_file_set()
99 EAPI void elm_thumb_reload(Evas_Object *obj);
102 * Set the file that will be used as thumbnail @b source.
104 * @param obj The thumb object.
105 * @param file The path to file that will be used as thumbnail source.
106 * @param key The key used in case of an EET file.
108 * The file can be an image or a video (in that case, acceptable
109 * extensions are: avi, mp4, ogv, mov, mpg and wmv). To start the
110 * video animation, use the function elm_thumb_animate().
112 * @see elm_thumb_file_get()
113 * @see elm_thumb_reload()
114 * @see elm_thumb_animate()
118 EAPI void elm_thumb_file_set(Evas_Object *obj, const char *file, const char *key);
121 * Get the image or video path and key used to generate the thumbnail.
123 * @param obj The thumb object.
124 * @param file Pointer to filename.
125 * @param key Pointer to key.
127 * @see elm_thumb_file_set()
128 * @see elm_thumb_path_get()
132 EAPI void elm_thumb_file_get(const Evas_Object *obj, const char **file, const char **key);
135 * Get the path and key to the image or video thumbnail generated by ethumb.
137 * One just needs to make sure that the thumbnail was generated before getting
138 * its path; otherwise, the path will be NULL. One way to do that is by asking
139 * for the path when/after the "generate,stop" smart callback is called.
141 * @param obj The thumb object.
142 * @param file Pointer to thumb path.
143 * @param key Pointer to thumb key.
145 * @see elm_thumb_file_get()
149 EAPI void elm_thumb_path_get(const Evas_Object *obj, const char **file, const char **key);
152 * Set the animation state for the thumb object. If its content is an animated
153 * video, you may start/stop the animation or tell it to play continuously and
156 * @param obj The thumb object.
157 * @param s The animation setting.
159 * @see elm_thumb_file_set()
163 EAPI void elm_thumb_animate_set(Evas_Object *obj, Elm_Thumb_Animation_Setting s);
166 * Get the animation state for the thumb object.
168 * @param obj The thumb object.
169 * @return getting The animation setting or @c ELM_THUMB_ANIMATION_LAST,
172 * @see elm_thumb_animate_set()
176 EAPI Elm_Thumb_Animation_Setting elm_thumb_animate_get(const Evas_Object *obj);
179 * Get the ethumb_client handle so custom configuration can be made.
181 * @return Ethumb_Client instance or NULL.
183 * This must be called before the objects are created to be sure no object is
184 * visible and no generation started.
189 * #include <Elementary.h>
190 * #ifndef ELM_LIB_QUICKLAUNCH
192 * elm_main(int argc, char **argv)
194 * Ethumb_Client *client;
200 * client = elm_thumb_ethumb_client_get();
203 * ERR("could not get ethumb_client");
206 * ethumb_client_size_set(client, 100, 100);
207 * ethumb_client_crop_align_set(client, 0.5, 0.5);
210 * // Create elm_thumb objects here
220 * @note There's only one client handle for Ethumb, so once a configuration
221 * change is done to it, any other request for thumbnails (for any thumbnail
222 * object) will use that configuration. Thus, this configuration is global.
226 EAPI void *elm_thumb_ethumb_client_get(void);
229 * Get the ethumb_client connection state.
231 * @return EINA_TRUE if the client is connected to the server or EINA_FALSE
234 EAPI Eina_Bool elm_thumb_ethumb_client_connected_get(void);
237 * Make the thumbnail 'editable'.
239 * @param obj Thumb object.
240 * @param edit Turn on or off editability. Default is @c EINA_FALSE.
242 * This means the thumbnail is a valid drag target for drag and drop, and can be
245 * @see elm_thumb_editable_get()
249 EAPI Eina_Bool elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit);
252 * Make the thumbnail 'editable'.
254 * @param obj Thumb object.
255 * @return Editability.
257 * This means the thumbnail is a valid drag target for drag and drop, and can be
260 * @see elm_thumb_editable_set()
264 EAPI Eina_Bool elm_thumb_editable_get(const Evas_Object *obj);