EFL migration revision 67547
[framework/uifw/elementary.git] / src / lib / elm_thumb.h
1 /**
2  * @defgroup Thumb Thumb
3  *
4  * @image html img/widget/thumb/preview-00.png
5  * @image latex img/widget/thumb/preview-00.eps
6  *
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
10  * be generated.
11  *
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.
15  *
16  * Different config settings will cause different thumbnails to be generated
17  * even on the same file.
18  *
19  * Generated thumbnails are stored under @c $HOME/.thumbnails/. Check the
20  * Ethumb documentation to change this path, and to see other configuration
21  * options.
22  *
23  * Signals that you can add callbacks for are:
24  *
25  * - "clicked" - This is called when a user has clicked the thumb without dragging
26  *             around.
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.
33  *
34  * available styles:
35  * - default
36  * - noframe
37  *
38  * An example of use of thumbnail:
39  *
40  * - @ref thumb_example_01
41  */
42
43 /**
44  * @addtogroup Thumb
45  * @{
46  */
47
48 /**
49  * @enum _Elm_Thumb_Animation_Setting
50  * @typedef Elm_Thumb_Animation_Setting
51  *
52  * Used to set if a video thumbnail is animating or not.
53  *
54  * @ingroup Thumb
55  */
56 typedef enum
57 {
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;
63
64 /**
65  * Add a new thumb object to the parent.
66  *
67  * @param parent The parent object.
68  * @return The new object or NULL if it cannot be created.
69  *
70  * @see elm_thumb_file_set()
71  * @see elm_thumb_ethumb_client_get()
72  *
73  * @ingroup Thumb
74  */
75 EAPI Evas_Object                *elm_thumb_add(Evas_Object *parent);
76
77 /**
78  * Reload thumbnail if it was generated before.
79  *
80  * @param obj The thumb object to reload
81  *
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().
85  *
86  * If the options didn't change, the thumbnail won't be generated again, but
87  * the old one will still be used.
88  *
89  * @see elm_thumb_file_set()
90  *
91  * @ingroup Thumb
92  */
93 EAPI void                        elm_thumb_reload(Evas_Object *obj);
94
95 /**
96  * Set the file that will be used as thumbnail.
97  *
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.
101  *
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().
105  *
106  * @see elm_thumb_file_get()
107  * @see elm_thumb_reload()
108  * @see elm_thumb_animate()
109  *
110  * @ingroup Thumb
111  */
112 EAPI void                        elm_thumb_file_set(Evas_Object *obj, const char *file, const char *key);
113
114 /**
115  * Get the image or video path and key used to generate the thumbnail.
116  *
117  * @param obj The thumb object.
118  * @param file Pointer to filename.
119  * @param key Pointer to key.
120  *
121  * @see elm_thumb_file_set()
122  * @see elm_thumb_path_get()
123  *
124  * @ingroup Thumb
125  */
126 EAPI void                        elm_thumb_file_get(const Evas_Object *obj, const char **file, const char **key);
127
128 /**
129  * Get the path and key to the image or video generated by ethumb.
130  *
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.
134  *
135  * @param obj The thumb object.
136  * @param file Pointer to thumb path.
137  * @param key Pointer to thumb key.
138  *
139  * @see elm_thumb_file_get()
140  *
141  * @ingroup Thumb
142  */
143 EAPI void                        elm_thumb_path_get(const Evas_Object *obj, const char **file, const char **key);
144
145 /**
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
148  * looping.
149  *
150  * @param obj The thumb object.
151  * @param setting The animation setting.
152  *
153  * @see elm_thumb_file_set()
154  *
155  * @ingroup Thumb
156  */
157 EAPI void                        elm_thumb_animate_set(Evas_Object *obj, Elm_Thumb_Animation_Setting s);
158
159 /**
160  * Get the animation state for the thumb object.
161  *
162  * @param obj The thumb object.
163  * @return getting The animation setting or @c ELM_THUMB_ANIMATION_LAST,
164  * on errors.
165  *
166  * @see elm_thumb_animate_set()
167  *
168  * @ingroup Thumb
169  */
170 EAPI Elm_Thumb_Animation_Setting elm_thumb_animate_get(const Evas_Object *obj);
171
172 /**
173  * Get the ethumb_client handle so custom configuration can be made.
174  *
175  * @return Ethumb_Client instance or NULL.
176  *
177  * This must be called before the objects are created to be sure no object is
178  * visible and no generation started.
179  *
180  * Example of usage:
181  *
182  * @code
183  * #include <Elementary.h>
184  * #ifndef ELM_LIB_QUICKLAUNCH
185  * EAPI_MAIN int
186  * elm_main(int argc, char **argv)
187  * {
188  *    Ethumb_Client *client;
189  *
190  *    elm_need_ethumb();
191  *
192  *    // ... your code
193  *
194  *    client = elm_thumb_ethumb_client_get();
195  *    if (!client)
196  *      {
197  *         ERR("could not get ethumb_client");
198  *         return 1;
199  *      }
200  *    ethumb_client_size_set(client, 100, 100);
201  *    ethumb_client_crop_align_set(client, 0.5, 0.5);
202  *    // ... your code
203  *
204  *    // Create elm_thumb objects here
205  *
206  *    elm_run();
207  *    elm_shutdown();
208  *    return 0;
209  * }
210  * #endif
211  * ELM_MAIN()
212  * @endcode
213  *
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.
217  *
218  * @ingroup Thumb
219  */
220 EAPI void                       *elm_thumb_ethumb_client_get(void);
221
222 /**
223  * Get the ethumb_client connection state.
224  *
225  * @return EINA_TRUE if the client is connected to the server or EINA_FALSE
226  * otherwise.
227  */
228 EAPI Eina_Bool                   elm_thumb_ethumb_client_connected(void);
229
230 /**
231  * Make the thumbnail 'editable'.
232  *
233  * @param obj Thumb object.
234  * @param set Turn on or off editability. Default is @c EINA_FALSE.
235  *
236  * This means the thumbnail is a valid drag target for drag and drop, and can be
237  * cut or pasted too.
238  *
239  * @see elm_thumb_editable_get()
240  *
241  * @ingroup Thumb
242  */
243 EAPI Eina_Bool                   elm_thumb_editable_set(Evas_Object *obj, Eina_Bool edit);
244
245 /**
246  * Make the thumbnail 'editable'.
247  *
248  * @param obj Thumb object.
249  * @return Editability.
250  *
251  * This means the thumbnail is a valid drag target for drag and drop, and can be
252  * cut or pasted too.
253  *
254  * @see elm_thumb_editable_set()
255  *
256  * @ingroup Thumb
257  */
258 EAPI Eina_Bool                   elm_thumb_editable_get(const Evas_Object *obj);
259
260 /**
261  * @}
262  */