3 * @defgroup Slideshow Slideshow
4 * @ingroup elm_widget_group
6 * @image html slideshow_inheritance_tree.png
7 * @image latex slideshow_inheritance_tree.eps
9 * @image html img/widget/slideshow/preview-00.png
10 * @image latex img/widget/slideshow/preview-00.eps
12 * @brief A Slideshow provide a slideshow for pre-made images.
14 * This widget, as the name indicates, is a pre-made image
15 * slideshow panel, with API functions acting on the (child) image
16 * items presentation. Between those actions, are:
17 * - advance to next/previous image.
18 * - select the style of image transition animation.
19 * - set the exhibition time for each image,
20 * - start/stop the slideshow.
22 * The transition animations are defined in the widget's theme.
23 * Consequently, new animations can be added without having to
24 * update the widget's code.
26 * @section Slideshow_Items Slideshow items
28 * For slideshow items, just like for @ref Genlist "genlist" ones,
29 * the user defines @b classes, specifying functions that are
30 * called on the item's creation and deletion times.
32 * The #Elm_Slideshow_Item_Class structure contains the following
35 * - @c func.get - When an item is displayed, this function is
36 * called, and it's where one should create the item object, de
37 * facto. For example, the object can be a pure Evas image object
38 * or an Elementary @ref Photocam "photocam" widget.
39 * See #SlideshowItemGetFunc.
40 * - @c func.del - When an item is no more displayed, this function
41 * is called, where the user must delete any data associated to
42 * the item. See #SlideshowItemDelFunc.
44 * @section Slideshow_Caching Slideshow caching
46 * The slideshow provides facilities to have items adjacent to the
47 * one being displayed <b>already "realized"</b> (i.e. loaded) for
48 * you, so that the system does not have to decode the image data
49 * anymore when it has to actually switch images on its
50 * viewport. The user is able to set the number of items to be
51 * cached @b before and @b after the current item, in the widget's
54 * This widget inherits from the @ref Layout one, so that all the
55 * functions acting on it also work for slideshow objects.
57 * This widget emits the following signals, besides the ones sent from
59 * - @c "changed" - When the slideshow switches its view to a new
60 * item. The @a event_info parameter in the callback contains the current visible item
61 * - @c "transition,end" - When a slide transition ends. The @a event_info parameter
62 * in the callback contains the current visible item.
68 * @brief typedef to struct _Elm_Slideshow_Item_Class
70 typedef struct _Elm_Slideshow_Item_Class Elm_Slideshow_Item_Class;
71 typedef struct _Elm_Slideshow_Item_Class_Func Elm_Slideshow_Item_Class_Func; /**< Class functions for slideshow item classes */
72 typedef Evas_Object *(*SlideshowItemGetFunc)(void *data, Evas_Object *obj); /**< Image fetching class function for slideshow item classes */
73 typedef void (*SlideshowItemDelFunc)(void *data, Evas_Object *obj); /**< Deletion class function for slideshow item classes */
77 * @struct _Elm_Slideshow_Item_Class
79 * @brief The structure type for slideshow item class definition. See @ref Slideshow_Items for
82 struct _Elm_Slideshow_Item_Class
84 struct _Elm_Slideshow_Item_Class_Func
86 SlideshowItemGetFunc get;
87 SlideshowItemDelFunc del;
92 * @brief Adds a new slideshow widget to the given parent Elementary
95 * @details This function inserts a new slideshow widget on the canvas.
97 * @param[in] parent The parent object
98 * @return A new slideshow widget handle, otherwise @c NULL in case of an error
100 EAPI Evas_Object *elm_slideshow_add(Evas_Object *parent);
103 * @brief Adds (appends) a new item to a given slideshow widget.
105 * @details This adds a new item to the @a obj internal list of items, appending it.
106 * The item's class must contain the function that really fetches the
107 * image object to show for this item, which could be an Evas image
108 * object or an Elementary photo, for example. The @a data
109 * parameter is going to be passed to both class functions of the
112 * @param[in] obj The slideshow object
113 * @param[in] itc The item class for the item
114 * @param[in] data The item's data
115 * @return A handle to the item added, otherwise @c NULL in case of an error
117 * @see #Elm_Slideshow_Item_Class
118 * @see elm_slideshow_item_sorted_insert()
119 * @see elm_object_item_data_set()
121 EAPI Elm_Object_Item *elm_slideshow_item_add(Evas_Object *obj, const Elm_Slideshow_Item_Class *itc, const void *data);
124 * @brief Inserts a new item into the given slideshow widget, using the @a func
125 * function to sort items (by item handles).
127 * @remarks It adds a new item to the @a obj internal list of items, in a position
128 * determined by the @a func comparing function. The item's class
129 * must contain the function that really fetches the image object to
130 * show for this item, which could be an Evas image object or an
131 * Elementary photo, for example. The @a data parameter is going to
132 * be passed to both class functions of the item.
134 * @param[in] obj The slideshow object
135 * @param[in] itc The item class for the item
136 * @param[in] data The item data
137 * @param[in] func The comparing function to be used to sort the slideshow
138 * items <b>by #Elm_Slideshow_Item_Class item handles</b>
139 * @return The slideshow item handle on success,
140 * otherwise @c NULL in case of an error
142 * @see #Elm_Slideshow_Item_Class
143 * @see elm_slideshow_item_add()
145 EAPI Elm_Object_Item *elm_slideshow_item_sorted_insert(Evas_Object *obj, const Elm_Slideshow_Item_Class *itc, const void *data, Eina_Compare_Cb func);
148 * @brief Displays a given slideshow widget's item, programmatically.
150 * @remarks The change between the current item and @a it uses the
151 * transition @a obj that is set to use (@see
152 * elm_slideshow_transition_set()).
154 * @param[in] it The item to display on the @a obj viewport
156 EAPI void elm_slideshow_item_show(Elm_Object_Item *it);
159 * @brief Slides to the @b next item, in a given slideshow widget.
161 * @remarks The sliding animation @a obj is set to use the
162 * transition effect that is used after this call is issued.
164 * @remarks If the end of the slideshow's internal list of items is
165 * reached, it wraps around the list's beginning, again.
167 * @param[in] obj The slideshow object
169 EAPI void elm_slideshow_next(Evas_Object *obj);
172 * @brief Slides to the @b previous item, in a given slideshow widget.
174 * @remarks The sliding animation @a obj is set to use the
175 * transition effect used after this call is issued.
177 * @remarks If the beginning of the slideshow's internal list of items
178 * is reached, it wraps around the list's end, again.
180 * @param[in] obj The slideshow object
182 EAPI void elm_slideshow_previous(Evas_Object *obj);
185 * @brief Returns the list of sliding transition/effect names available, for a
186 * given slideshow widget.
188 * @remarks The transitions, which come from the @a obj theme, must be an EDC
189 * data item named @c "transitions" on the theme file, with (prefix)
190 * names of EDC programs actually implementing them.
192 * @remarks The available transitions for slideshows on the default theme are:
193 * - @c "fade" - The current item fades out, while the new one
194 * fades in to the slideshow's viewport.
195 * - @c "black_fade" - The current item fades to black, and just
196 * then, the new item fades in.
197 * - @c "horizontal" - The current item slides horizontally, until
198 * it gets out of the slideshow's viewport, while the new item
199 * comes from the left to take its place.
200 * - @c "vertical" - The current item slides vertically, until it
201 * gets out of the slideshow's viewport, while the new item comes
202 * from the bottom to take its place.
203 * - @c "square" - The new item starts to appear from the middle of
204 * the current one, but with a tiny size, growing until its
205 * target (full) size and covering the old one.
207 * @remarks The stringshared strings get no new references
208 * exclusive to the user grabbing the list, here, so if you would like
209 * to use them out of this call's context, you would better
210 * eina_stringshare_ref() them. Also the list is an internal list and
211 * is only valid for as long as the slideshow object is valid, and
212 * has not internally changed its list for some reason, so make a
213 * copy if you need it.
215 * @param[in] obj The slideshow object
216 * @return The list of transitions (list of @b stringshared strings
219 * @see elm_slideshow_transition_set()
221 EAPI const Eina_List *elm_slideshow_transitions_get(const Evas_Object *obj);
224 * @brief Sets the current slide transition/effect in use for a given
227 * @remarks If @a transition is implemented in the @a obj theme (i.e., is
228 * contained in the list returned by
229 * elm_slideshow_transitions_get()), this new sliding effect is
230 * used on the widget.
232 * @param[in] obj The slideshow object
233 * @param[in] transition The new transition's name string
235 * @see elm_slideshow_transitions_get()
237 EAPI void elm_slideshow_transition_set(Evas_Object *obj, const char *transition);
240 * @brief Gets the current slide transition/effect in use for a given
243 * @param[in] obj The slideshow object
244 * @return The current transition's name
246 * @see elm_slideshow_transition_set()
248 EAPI const char *elm_slideshow_transition_get(const Evas_Object *obj);
251 * @brief Sets the interval between each image transition on a given
252 * slideshow widget, <b>and the start of the slideshow, itself</b>
254 * @remarks After this call, the slideshow widget starts cycling its
255 * view, sequentially and automatically, with the images of the
256 * items that it has. The time between each new image displayed is going
257 * to be @a timeout, in @b seconds. If a different timeout is set
258 * previously and a slideshow is in progress, it continues
259 * with the new time between transitions, after this call.
261 * @remarks A value less than or equal to @c 0 on @a timeout disables
262 * the widget's internal timer, thus halting any slideshow which
263 * could be happening on @a obj.
265 * @param[in] obj The slideshow object
266 * @param[in] timeout The new displaying timeout for images
268 * @see elm_slideshow_timeout_get()
270 EAPI void elm_slideshow_timeout_set(Evas_Object *obj, double timeout);
273 * @brief Gets the interval set for image transitions on a given slideshow
276 * @param[in] obj The slideshow object
277 * @return The timeout set on it, otherwise @c -1.0 in case of an error
279 * @see elm_slideshow_timeout_set()
281 EAPI double elm_slideshow_timeout_get(const Evas_Object *obj);
284 * @brief Sets whether after a slideshow is started, for a given slideshow
285 * widget, its items should be displayed cyclically.
287 * @remarks elm_slideshow_next() and elm_slideshow_previous() @b
288 * ignore what is set by this functions, i.e., they @b always
289 * cycle through items. This affects only the "automatic"
290 * slideshow, as set by elm_slideshow_timeout_set().
292 * @param[in] obj The slideshow object
293 * @param[in] loop If @c EINA_TRUE it cycles through items,
294 * otherwise @c EINA_FALSE for it to stop at the end of the @a obj internal
297 * @see elm_slideshow_loop_get()
299 EAPI void elm_slideshow_loop_set(Evas_Object *obj, Eina_Bool loop);
302 * @brief Gets whether after a slideshow is started, for a given slideshow
303 * widget, its items are to be displayed cyclically.
305 * @param[in] obj The slideshow object
306 * @return @c EINA_TRUE if the items in @a obj are cycled,
307 * otherwise @c EINA_FALSE
309 * @see elm_slideshow_loop_set()
311 EAPI Eina_Bool elm_slideshow_loop_get(const Evas_Object *obj);
314 * @brief Removes all items from a given slideshow widget.
316 * @details This removes (and deletes) all items in @a obj, leaving it
319 * @param[in] obj The slideshow object
321 * @see elm_object_item_del(), to remove just one item.
323 EAPI void elm_slideshow_clear(Evas_Object *obj);
326 * @brief Gets the internal list of items in a given slideshow widget.
328 * @remarks This list is @b not to be modified in any way and must not be
329 * freed. Use the list members with functions like
330 * elm_object_item_del() and elm_object_item_data_get().
332 * @remarks This list is only valid until @a obj object's internal
333 * items list is changed. It should be fetched again with another
334 * call to this function when changes happen.
336 * @param[in] obj The slideshow object
337 * @return The list of items (#Elm_Object_Item as data),
338 * otherwise @c NULL in case of an error
340 EAPI const Eina_List *elm_slideshow_items_get(const Evas_Object *obj);
343 * @brief Returns the currently displayed item, in a given slideshow widget.
345 * @param[in] obj The slideshow object
346 * @return A handle to the item being displayed in @a obj,
347 * otherwise @c NULL, if none are present (and on errors)
349 EAPI Elm_Object_Item *elm_slideshow_item_current_get(const Evas_Object *obj);
352 * @brief Gets the real Evas object created to implement the view of a
353 * given slideshow item.
355 * @details This returns the actual Evas object used to implement the
356 * specified slideshow item's view. This may be @c NULL, as it may
357 * not have been created or may have been deleted, at any time, by
358 * the slideshow. <b>Do not modify this object</b> (move, resize,
359 * show, hide, etc.), as the slideshow is controlling it. This
360 * function is for querying, emitting custom signals, or hooking
361 * lower level callbacks for events on that object. Do not delete
362 * this object under any circumstances.
364 * @param[in] it The slideshow item
365 * @return The Evas object implementing this item's view
367 * @see elm_object_item_data_get()
369 EAPI Evas_Object *elm_slideshow_item_object_get(const Elm_Object_Item *it);
372 * @brief Gets the item, in a given slideshow widget, placed at
373 * position @a nth, in its internal items list.
375 * @param[in] obj The slideshow object
376 * @param[in] nth The number of the item to grab as a handle (@c 0 being
378 * @return The item stored in @a obj at position @a nth, otherwise @c NULL,
379 * if there's no item with that index (and on errors)
381 EAPI Elm_Object_Item *elm_slideshow_item_nth_get(const Evas_Object *obj, unsigned int nth);
384 * @brief Sets the current slide layout in use for a given slideshow widget.
386 * @remarks If @p layout is implemented in the @a obj theme (i.e., it is contained
387 * in the list returned by elm_slideshow_layouts_get()), this new
388 * images layout is used on the widget.
390 * @param[in] obj The slideshow object
391 * @param[in] layout The new layout's name string
393 * @see elm_slideshow_layouts_get()
395 EAPI void elm_slideshow_layout_set(Evas_Object *obj, const char *layout);
398 * @brief Gets the current slide layout in use for a given slideshow widget
400 * @param[in] obj The slideshow object
401 * @return The current layout's name
403 * @see elm_slideshow_layout_set()
405 EAPI const char *elm_slideshow_layout_get(const Evas_Object *obj);
408 * @brief Returns the list of @b layout names available, for a given
411 * @remarks Slideshow layouts change how the widget is to dispose each
412 * image item in its viewport, with regards to cropping, scaling,
415 * @remarks The layouts, which come from the @a obj theme, must be an EDC
416 * data item name @c "layouts" on the theme file, with (prefix)
417 * names of EDC programs actually implementing them.
419 * @remarks The available layouts for slideshows on the default theme are:
420 * - @c "fullscreen" - Item images with original aspect, scaled to
421 * touch top and down slideshow borders or, if the image's height
422 * is not enough, left and right slideshow borders.
423 * - @c "not_fullscreen" - The same behavior as the @c "fullscreen"
424 * one, but always leaves 10% of the slideshow's dimensions of the
425 * distance between the item image's borders and the slideshow
426 * borders, for each axis.
428 * @remarks The stringshared strings get no new references
429 * exclusive to the user grabbing the list, here, so if you would like
430 * to use them out of this call's context, you would better
431 * eina_stringshare_ref() them.
433 * @param[in] obj The slideshow object
434 * @return The list of layouts (list of @b stringshared strings
437 * @see elm_slideshow_layout_set()
439 EAPI const Eina_List *elm_slideshow_layouts_get(const Evas_Object *obj);
442 * @brief Sets the number of items to cache, on a given slideshow widget,
443 * <b>before the current item</b>.
445 * @remarks The default value for this property is @c 2. See
446 * @ref Slideshow_Caching "slideshow caching" for more details.
448 * @param[in] obj The slideshow object
449 * @param[in] count The number of items to cache before the current one
451 * @see elm_slideshow_cache_before_get()
453 EAPI void elm_slideshow_cache_before_set(Evas_Object *obj, int count);
456 * @brief Retrieves the number of items to cache, on a given slideshow widget,
457 * <b>before the current item</b>.
459 * @param[in] obj The slideshow object
460 * @return The number of items set to be cached before the current one
462 * @see elm_slideshow_cache_before_set()
464 EAPI int elm_slideshow_cache_before_get(const Evas_Object *obj);
467 * @brief Sets the number of items to cache, on a given slideshow widget,
468 * <b>after the current item</b>.
470 * @remarks The default value for this property is @c 2. See
471 * @ref Slideshow_Caching "slideshow caching" for more details.
473 * @param[in] obj The slideshow object
474 * @param[in] count The number of items to cache after the current one
476 * @see elm_slideshow_cache_after_get()
478 EAPI void elm_slideshow_cache_after_set(Evas_Object *obj, int count);
481 * @brief Retrieves the number of items to cache, on a given slideshow widget,
482 * <b>after the current item</b>.
484 * @param[in] obj The slideshow object
485 * @return The number of items set to be cached after the current one
487 * @see elm_slideshow_cache_after_set()
489 EAPI int elm_slideshow_cache_after_get(const Evas_Object *obj);
492 * @brief Gets the number of items stored in a given slideshow widget.
494 * @param[in] obj The slideshow object
495 * @return The number of items on @a obj at the time of this call
497 EAPI unsigned int elm_slideshow_count_get(const Evas_Object *obj);