2 * @defgroup Thumb Thumb
5 * @image html img/widget/thumb/preview-00.png
6 * @image latex img/widget/thumb/preview-00.eps
8 * A thumb object is used for displaying the thumbnail of an image or video.
9 * You must have compiled Elementary with Ethumb_Client support and the DBus
10 * service must be present and auto-activated in order to have thumbnails to
11 * be generated. You must also have a Session bus, not System bus.
13 * Once the thumbnail object becomes visible, it will check if there is a
14 * previously generated thumbnail image for the file set on it. If not, it
15 * will start generating this thumbnail.
17 * Different config settings will cause different thumbnails to be generated
18 * even on the same file.
20 * Generated thumbnails are stored under @c $HOME/.thumbnails/. Check the
21 * Ethumb documentation to change this path, and to see other configuration
24 * Signals that you can add callbacks for are:
26 * - "clicked" - This is called when a user has clicked the thumb without dragging
28 * - "clicked,double" - This is called when a user has double-clicked the thumb.
29 * - "press" - This is called when a user has pressed down the thumb.
30 * - "generate,start" - The thumbnail generation started.
31 * - "generate,stop" - The generation process stopped.
32 * - "generate,error" - The generation failed.
33 * - "load,error" - The thumbnail image loading failed.
39 * An example of use of thumbnail:
41 * - @ref thumb_example_01
50 * @enum _Elm_Thumb_Animation_Setting
51 * @typedef Elm_Thumb_Animation_Setting
53 * Used to set if a video thumbnail is animating or not.
59 ELM_THUMB_ANIMATION_START = 0, /**< Play animation once */
60 ELM_THUMB_ANIMATION_LOOP, /**< Keep playing animation until stop is requested */
61 ELM_THUMB_ANIMATION_STOP, /**< Stop playing the animation */
62 ELM_THUMB_ANIMATION_LAST
63 } Elm_Thumb_Animation_Setting;
66 * Add a new thumb object to the parent.
68 * @param parent The parent object.
69 * @return The new object or NULL if it cannot be created.
71 * @see elm_thumb_file_set()
72 * @see elm_thumb_ethumb_client_get()
76 EAPI Evas_Object *elm_thumb_add(Evas_Object *parent);
79 * Reload thumbnail if it was generated before.
81 * @param obj The thumb object to reload
83 * This is useful if the ethumb client configuration changed, like its
84 * size, aspect or any other property one set in the handle returned
85 * by elm_thumb_ethumb_client_get().
87 * If the options didn't change, the thumbnail won't be generated again, but
88 * the old one will still be used.
90 * @see elm_thumb_file_set()
94 EAPI void elm_thumb_reload(Evas_Object *obj);
97 * Set the file that will be used as thumbnail.
99 * @param obj The thumb object.
100 * @param file The path to file that will be used as thumb.
101 * @param key The key used in case of an EET file.
103 * The file can be an image or a video (in that case, acceptable extensions are:
104 * avi, mp4, ogv, mov, mpg and wmv). To start the video animation, use the
105 * function elm_thumb_animate().
107 * @see elm_thumb_file_get()
108 * @see elm_thumb_reload()
109 * @see elm_thumb_animate()
113 EAPI void elm_thumb_file_set(Evas_Object *obj, const char *file, const char *key);
116 * Get the image or video path and key used to generate the thumbnail.
118 * @param obj The thumb object.
119 * @param file Pointer to filename.
120 * @param key Pointer to key.
122 * @see elm_thumb_file_set()
123 * @see elm_thumb_path_get()
127 EAPI void elm_thumb_file_get(const Evas_Object *obj, const char **file, const char **key);
130 * Get the path and key to the image or video thumbnail generated by ethumb.
132 * One just needs to make sure that the thumbnail was generated before getting
133 * its path; otherwise, the path will be NULL. One way to do that is by asking
134 * for the path when/after the "generate,stop" smart callback is called.
136 * @param obj The thumb object.
137 * @param file Pointer to thumb path.
138 * @param key Pointer to thumb key.
140 * @see elm_thumb_file_get()
144 EAPI void elm_thumb_path_get(const Evas_Object *obj, const char **file, const char **key);
147 * Set the animation state for the thumb object. If its content is an animated
148 * video, you may start/stop the animation or tell it to play continuously and
151 * @param obj The thumb object.
152 * @param s The animation setting.
154 * @see elm_thumb_file_set()
158 EAPI void elm_thumb_animate_set(Evas_Object *obj, Elm_Thumb_Animation_Setting s);
161 * Get the animation state for the thumb object.
163 * @param obj The thumb object.
164 * @return getting The animation setting or @c ELM_THUMB_ANIMATION_LAST,
167 * @see elm_thumb_animate_set()
171 EAPI Elm_Thumb_Animation_Setting elm_thumb_animate_get(const Evas_Object *obj);
174 * Get the ethumb_client handle so custom configuration can be made.
176 * @return Ethumb_Client instance or NULL.
178 * This must be called before the objects are created to be sure no object is
179 * visible and no generation started.
184 * #include <Elementary.h>
185 * #ifndef ELM_LIB_QUICKLAUNCH
187 * elm_main(int argc, char **argv)
189 * Ethumb_Client *client;
195 * client = elm_thumb_ethumb_client_get();
198 * ERR("could not get ethumb_client");
201 * ethumb_client_size_set(client, 100, 100);
202 * ethumb_client_crop_align_set(client, 0.5, 0.5);
205 * // Create elm_thumb objects here
215 * @note There's only one client handle for Ethumb, so once a configuration
216 * change is done to it, any other request for thumbnails (for any thumbnail
217 * object) will use that configuration. Thus, this configuration is global.
221 EAPI void *elm_thumb_ethumb_client_get(void);
224 * Get the ethumb_client connection state.
226 * @return EINA_TRUE if the client is connected to the server or EINA_FALSE
229 EAPI Eina_Bool elm_thumb_ethumb_client_connected_get(void);
232 * Make the thumbnail 'editable'.
234 * @param obj Thumb object.
235 * @param edit Turn on or off editability. Default is @c EINA_FALSE.
237 * This means the thumbnail is a valid drag target for drag and drop, and can be
240 * @see elm_thumb_editable_get()
244 EAPI Eina_Bool elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit);
247 * Make the thumbnail 'editable'.
249 * @param obj Thumb object.
250 * @return Editability.
252 * This means the thumbnail is a valid drag target for drag and drop, and can be
255 * @see elm_thumb_editable_set()
259 EAPI Eina_Bool elm_thumb_editable_get(const Evas_Object *obj);