2 * @defgroup Slideshow Slideshow
5 * @image html slideshow_inheritance_tree.png
6 * @image latex slideshow_inheritance_tree.eps
8 * @image html img/widget/slideshow/preview-00.png
9 * @image latex img/widget/slideshow/preview-00.eps
11 * This widget, as the name indicates, is a pre-made image
12 * slideshow panel, with API functions acting on (child) image
13 * items presentation. Between those actions, are:
14 * - advance to next/previous image
15 * - select the style of image transition animation
16 * - set the exhibition time for each image
17 * - start/stop the slideshow
19 * The transition animations are defined in the widget's theme,
20 * consequently new animations can be added without having to
21 * update the widget's code.
23 * @section Slideshow_Items Slideshow items
25 * For slideshow items, just like for @ref Genlist "genlist" ones,
26 * the user defines a @b classes, specifying functions that will be
27 * called on the item's creation and deletion times.
29 * The #Elm_Slideshow_Item_Class structure contains the following
32 * - @c func.get - When an item is displayed, this function is
33 * called, and it's where one should create the item object, de
34 * facto. For example, the object can be a pure Evas image object
35 * or an Elementary @ref Photocam "photocam" widget.
36 * See #SlideshowItemGetFunc.
37 * - @c func.del - When an item is no more displayed, this function
38 * is called, where the user must delete any data associated to
39 * the item. See #SlideshowItemDelFunc.
41 * @section Slideshow_Caching Slideshow caching
43 * The slideshow provides facilities to have items adjacent to the
44 * one being displayed <b>already "realized"</b> (i.e. loaded) for
45 * you, so that the system does not have to decode image data
46 * anymore at the time it has to actually switch images on its
47 * viewport. The user is able to set the numbers of items to be
48 * cached @b before and @b after the current item, in the widget's
51 * This widget inherits from the @ref Layout one, so that all the
52 * functions acting on it also work for slideshow objects.
54 * This widget emits the following signals, besides the ones sent from
56 * - @c "changed" - when the slideshow switches its view to a new
57 * item. event_info parameter in callback contains the current visible item
58 * - @c "transition,end" - when a slide transition ends. event_info parameter
59 * in callback contains the current visible item
61 * List of examples for the slideshow widget:
62 * @li @ref slideshow_example
66 * @addtogroup Slideshow
70 typedef struct _Elm_Slideshow_Item_Class Elm_Slideshow_Item_Class; /**< Slideshow item class definition struct */
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. */
76 * @struct _Elm_Slideshow_Item_Class
78 * Slideshow item class definition. See @ref Slideshow_Items for
81 struct _Elm_Slideshow_Item_Class
83 struct _Elm_Slideshow_Item_Class_Func
85 SlideshowItemGetFunc get;
86 SlideshowItemDelFunc del;
88 }; /**< member definitions of #Elm_Slideshow_Item_Class */
91 * Add a new slideshow widget to the given parent Elementary
94 * @param parent The parent object
95 * @return A new slideshow widget handle or @c NULL, on errors
97 * This function inserts a new slideshow widget on the canvas.
101 EAPI Evas_Object *elm_slideshow_add(Evas_Object *parent);
104 * Add (append) a new item in a given slideshow widget.
106 * @param obj The slideshow object
107 * @param itc The item class for the item
108 * @param data The item's data
109 * @return A handle to the item added or @c NULL, on errors
111 * Add a new item to @p obj's internal list of items, appending it.
112 * The item's class must contain the function really fetching the
113 * image object to show for this item, which could be an Evas image
114 * object or an Elementary photo, for example. The @p data
115 * parameter is going to be passed to both class functions of the
118 * @see #Elm_Slideshow_Item_Class
119 * @see elm_slideshow_item_sorted_insert()
120 * @see elm_object_item_data_set()
124 EAPI Elm_Object_Item *elm_slideshow_item_add(Evas_Object *obj, const Elm_Slideshow_Item_Class *itc, const void *data);
127 * Insert a new item into the given slideshow widget, using the @p func
128 * function to sort items (by item handles).
130 * @param obj The slideshow object
131 * @param itc The item class for the item
132 * @param data The item's data
133 * @param func The comparing function to be used to sort slideshow
134 * items <b>by #Elm_Slideshow_Item_Class item handles</b>
135 * @return Returns The slideshow item handle, on success, or
138 * Add a new item to @p obj's internal list of items, in a position
139 * determined by the @p func comparing function. The item's class
140 * must contain the function really fetching the image object to
141 * show for this item, which could be an Evas image object or an
142 * Elementary photo, for example. The @p data parameter is going to
143 * be passed to both class functions of the item.
145 * @see #Elm_Slideshow_Item_Class
146 * @see elm_slideshow_item_add()
150 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);
153 * Display a given slideshow widget's item, programmatically.
155 * @param it The item to display on @p obj's viewport
157 * The change between the current item and @p item will use the
158 * transition @p obj is set to use (@see
159 * elm_slideshow_transition_set()).
163 EAPI void elm_slideshow_item_show(Elm_Object_Item *it);
166 * Slide to the @b next item, in a given slideshow widget
168 * @param obj The slideshow object
170 * The sliding animation @p obj is set to use will be the
171 * transition effect used, after this call is issued.
173 * @note If the end of the slideshow's internal list of items is
174 * reached, it'll wrap around to the list's beginning, again.
178 EAPI void elm_slideshow_next(Evas_Object *obj);
181 * Slide to the @b previous item, in a given slideshow widget
183 * @param obj The slideshow object
185 * The sliding animation @p obj is set to use will be the
186 * transition effect used, after this call is issued.
188 * @note If the beginning of the slideshow's internal list of items
189 * is reached, it'll wrap around to the list's end, again.
193 EAPI void elm_slideshow_previous(Evas_Object *obj);
196 * Returns the list of sliding transition/effect names available, for a
197 * given slideshow widget.
199 * @param obj The slideshow object
200 * @return The list of transitions (list of @b stringshared strings
203 * The transitions, which come from @p obj's theme, must be an EDC
204 * data item named @c "transitions" on the theme file, with (prefix)
205 * names of EDC programs actually implementing them.
207 * The available transitions for slideshows on the default theme are:
208 * - @c "fade" - the current item fades out, while the new one
209 * fades in to the slideshow's viewport.
210 * - @c "black_fade" - the current item fades to black, and just
211 * then, the new item will fade in.
212 * - @c "horizontal" - the current item slides horizontally, until
213 * it gets out of the slideshow's viewport, while the new item
214 * comes from the left to take its place.
215 * - @c "vertical" - the current item slides vertically, until it
216 * gets out of the slideshow's viewport, while the new item comes
217 * from the bottom to take its place.
218 * - @c "square" - the new item starts to appear from the middle of
219 * the current one, but with a tiny size, growing until its
220 * target (full) size and covering the old one.
222 * @warning The stringshared strings get no new references
223 * exclusive to the user grabbing the list, here, so if you'd like
224 * to use them out of this call's context, you'd better @c
225 * eina_stringshare_ref() them. Also the list is an internal list and
226 * so is only valid for as long as the slideshow object is valid and
227 * has not internally changed its list for some reason, so make a
228 * copy if you need it around.
230 * @see elm_slideshow_transition_set()
234 EAPI const Eina_List *elm_slideshow_transitions_get(const Evas_Object *obj);
237 * Set the current slide transition/effect in use for a given
240 * @param obj The slideshow object
241 * @param transition The new transition's name string
243 * If @p transition is implemented in @p obj's theme (i.e., is
244 * contained in the list returned by
245 * elm_slideshow_transitions_get()), this new sliding effect will
246 * be used on the widget.
248 * @see elm_slideshow_transitions_get() for more details
252 EAPI void elm_slideshow_transition_set(Evas_Object *obj, const char *transition);
255 * Get the current slide transition/effect in use for a given
258 * @param obj The slideshow object
259 * @return The current transition's name
261 * @see elm_slideshow_transition_set() for more details
265 EAPI const char *elm_slideshow_transition_get(const Evas_Object *obj);
268 * Set the interval between each image transition on a given
269 * slideshow widget, <b>and start the slideshow, itself</b>
271 * @param obj The slideshow object
272 * @param timeout The new displaying timeout for images
274 * After this call, the slideshow widget will start cycling its
275 * view, sequentially and automatically, with the images of the
276 * items it has. The time between each new image displayed is going
277 * to be @p timeout, in @b seconds. If a different timeout was set
278 * previously and an slideshow was in progress, it will continue
279 * with the new time between transitions, after this call.
281 * @note A value less than or equal to 0 on @p timeout will disable
282 * the widget's internal timer, thus halting any slideshow which
283 * could be happening on @p obj.
285 * @see elm_slideshow_timeout_get()
289 EAPI void elm_slideshow_timeout_set(Evas_Object *obj, double timeout);
292 * Get the interval set for image transitions on a given slideshow
295 * @param obj The slideshow object
296 * @return Returns the timeout set on it or -1.0, on errors
298 * @see elm_slideshow_timeout_set() for more details
302 EAPI double elm_slideshow_timeout_get(const Evas_Object *obj);
305 * Set if, after a slideshow is started, for a given slideshow
306 * widget, its items should be displayed cyclically or not.
308 * @param obj The slideshow object
309 * @param loop Use @c EINA_TRUE to make it cycle through items or
310 * @c EINA_FALSE for it to stop at the end of @p obj's internal
313 * @note elm_slideshow_next() and elm_slideshow_previous() will @b
314 * ignore what is set by this functions, i.e., they'll @b always
315 * cycle through items. This affects only the "automatic"
316 * slideshow, as set by elm_slideshow_timeout_set().
318 * @see elm_slideshow_loop_get()
322 EAPI void elm_slideshow_loop_set(Evas_Object *obj, Eina_Bool loop);
325 * Get if, after a slideshow is started, for a given slideshow
326 * widget, its items are to be displayed cyclically or not.
328 * @param obj The slideshow object
329 * @return @c EINA_TRUE, if the items in @p obj will be cycled
330 * through or @c EINA_FALSE, otherwise
332 * @see elm_slideshow_loop_set() for more details
336 EAPI Eina_Bool elm_slideshow_loop_get(const Evas_Object *obj);
339 * Remove all items from a given slideshow widget
341 * @param obj The slideshow object
343 * This removes (and deletes) all items in @p obj, leaving it
346 * @see elm_object_item_del(), to remove just one item.
350 EAPI void elm_slideshow_clear(Evas_Object *obj);
353 * Get the internal list of items in a given slideshow widget.
355 * @param obj The slideshow object
356 * @return The list of items (#Elm_Object_Item as data) or
359 * This list is @b not to be modified in any way and must not be
360 * freed. Use the list members with functions like
361 * elm_object_item_del(), elm_object_item_data_get().
363 * @warning This list is only valid until @p obj object's internal
364 * items list is changed. It should be fetched again with another
365 * call to this function when changes happen.
369 EAPI const Eina_List *elm_slideshow_items_get(const Evas_Object *obj);
372 * Returns the currently displayed item, in a given slideshow widget
374 * @param obj The slideshow object
375 * @return A handle to the item being displayed in @p obj or
376 * @c NULL, if none is (and on errors)
380 EAPI Elm_Object_Item *elm_slideshow_item_current_get(const Evas_Object *obj);
383 * Get the real Evas object created to implement the view of a
384 * given slideshow item
386 * @param it The slideshow item.
387 * @return the Evas object implementing this item's view.
389 * This returns the actual Evas object used to implement the
390 * specified slideshow item's view. This may be @c NULL, as it may
391 * not have been created or may have been deleted, at any time, by
392 * the slideshow. <b>Do not modify this object</b> (move, resize,
393 * show, hide, etc.), as the slideshow is controlling it. This
394 * function is for querying, emitting custom signals or hooking
395 * lower level callbacks for events on that object. Do not delete
396 * this object under any circumstances.
398 * @see elm_object_item_data_get()
402 EAPI Evas_Object *elm_slideshow_item_object_get(const Elm_Object_Item *it);
405 * Get the the item, in a given slideshow widget, placed at
406 * position @p nth, in its internal items list
408 * @param obj The slideshow object
409 * @param nth The number of the item to grab a handle to (0 being
411 * @return The item stored in @p obj at position @p nth or @c NULL,
412 * if there's no item with that index (and on errors)
416 EAPI Elm_Object_Item *elm_slideshow_item_nth_get(const Evas_Object *obj, unsigned int nth);
419 * Set the current slide layout in use for a given slideshow widget
421 * @param obj The slideshow object
422 * @param layout The new layout's name string
424 * If @p layout is implemented in @p obj's theme (i.e., is contained
425 * in the list returned by elm_slideshow_layouts_get()), this new
426 * images layout will be used on the widget.
428 * @see elm_slideshow_layouts_get() for more details
432 EAPI void elm_slideshow_layout_set(Evas_Object *obj, const char *layout);
435 * Get the current slide layout in use for a given slideshow widget
437 * @param obj The slideshow object
438 * @return The current layout's name
440 * @see elm_slideshow_layout_set() for more details
444 EAPI const char *elm_slideshow_layout_get(const Evas_Object *obj);
447 * Returns the list of @b layout names available, for a given
450 * @param obj The slideshow object
451 * @return The list of layouts (list of @b stringshared strings
454 * Slideshow layouts will change how the widget is to dispose each
455 * image item in its viewport, with regard to cropping, scaling,
458 * The layouts, which come from @p obj's theme, must be an EDC
459 * data item name @c "layouts" on the theme file, with (prefix)
460 * names of EDC programs actually implementing them.
462 * The available layouts for slideshows on the default theme are:
463 * - @c "fullscreen" - item images with original aspect, scaled to
464 * touch top and down slideshow borders or, if the image's height
465 * is not enough, left and right slideshow borders.
466 * - @c "not_fullscreen" - the same behavior as the @c "fullscreen"
467 * one, but always leaving 10% of the slideshow's dimensions of
468 * distance between the item image's borders and the slideshow
469 * borders, for each axis.
471 * @warning The stringshared strings get no new references
472 * exclusive to the user grabbing the list, here, so if you'd like
473 * to use them out of this call's context, you'd better @c
474 * eina_stringshare_ref() them.
476 * @see elm_slideshow_layout_set()
480 EAPI const Eina_List *elm_slideshow_layouts_get(const Evas_Object *obj);
483 * Set the number of items to cache, on a given slideshow widget,
484 * <b>before the current item</b>
486 * @param obj The slideshow object
487 * @param count Number of items to cache before the current one
489 * The default value for this property is @c 2. See
490 * @ref Slideshow_Caching "slideshow caching" for more details.
492 * @see elm_slideshow_cache_before_get()
496 EAPI void elm_slideshow_cache_before_set(Evas_Object *obj, int count);
499 * Retrieve the number of items to cache, on a given slideshow widget,
500 * <b>before the current item</b>
502 * @param obj The slideshow object
503 * @return The number of items set to be cached before the current one
505 * @see elm_slideshow_cache_before_set() for more details
509 EAPI int elm_slideshow_cache_before_get(const Evas_Object *obj);
512 * Set the number of items to cache, on a given slideshow widget,
513 * <b>after the current item</b>
515 * @param obj The slideshow object
516 * @param count Number of items to cache after the current one
518 * The default value for this property is @c 2. See
519 * @ref Slideshow_Caching "slideshow caching" for more details.
521 * @see elm_slideshow_cache_after_get()
525 EAPI void elm_slideshow_cache_after_set(Evas_Object *obj, int count);
528 * Retrieve the number of items to cache, on a given slideshow widget,
529 * <b>after the current item</b>
531 * @param obj The slideshow object
532 * @return The number of items set to be cached after the current one
534 * @see elm_slideshow_cache_after_set() for more details
538 EAPI int elm_slideshow_cache_after_get(const Evas_Object *obj);
541 * Get the number of items stored in a given slideshow widget
543 * @param obj The slideshow object
544 * @return The number of items on @p obj, at the moment of this call
548 EAPI unsigned int elm_slideshow_count_get(const Evas_Object *obj);