aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/elementary/src/lib/elm_slideshow.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/elementary/src/lib/elm_slideshow.h')
-rw-r--r--libraries/elementary/src/lib/elm_slideshow.h546
1 files changed, 0 insertions, 546 deletions
diff --git a/libraries/elementary/src/lib/elm_slideshow.h b/libraries/elementary/src/lib/elm_slideshow.h
deleted file mode 100644
index 546b002..0000000
--- a/libraries/elementary/src/lib/elm_slideshow.h
+++ /dev/null
@@ -1,546 +0,0 @@
1/**
2 * @defgroup Slideshow Slideshow
3 * @ingroup Elementary
4 *
5 * @image html img/widget/slideshow/preview-00.png
6 * @image latex img/widget/slideshow/preview-00.eps
7 *
8 * This widget, as the name indicates, is a pre-made image
9 * slideshow panel, with API functions acting on (child) image
10 * items presentation. Between those actions, are:
11 * - advance to next/previous image
12 * - select the style of image transition animation
13 * - set the exhibition time for each image
14 * - start/stop the slideshow
15 *
16 * The transition animations are defined in the widget's theme,
17 * consequently new animations can be added without having to
18 * update the widget's code.
19 *
20 * @section Slideshow_Items Slideshow items
21 *
22 * For slideshow items, just like for @ref Genlist "genlist" ones,
23 * the user defines a @b classes, specifying functions that will be
24 * called on the item's creation and deletion times.
25 *
26 * The #Elm_Slideshow_Item_Class structure contains the following
27 * members:
28 *
29 * - @c func.get - When an item is displayed, this function is
30 * called, and it's where one should create the item object, de
31 * facto. For example, the object can be a pure Evas image object
32 * or an Elementary @ref Photocam "photocam" widget. See
33 * #SlideshowItemGetFunc.
34 * - @c func.del - When an item is no more displayed, this function
35 * is called, where the user must delete any data associated to
36 * the item. See #SlideshowItemDelFunc.
37 *
38 * @section Slideshow_Caching Slideshow caching
39 *
40 * The slideshow provides facilities to have items adjacent to the
41 * one being displayed <b>already "realized"</b> (i.e. loaded) for
42 * you, so that the system does not have to decode image data
43 * anymore at the time it has to actually switch images on its
44 * viewport. The user is able to set the numbers of items to be
45 * cached @b before and @b after the current item, in the widget's
46 * item list.
47 *
48 * Smart events one can add callbacks for are:
49 *
50 * - @c "changed" - when the slideshow switches its view to a new
51 * item. event_info parameter in callback contains the current visible item
52 * - @c "transition,end" - when a slide transition ends. event_info parameter
53 * in callback contains the current visible item
54 *
55 * List of examples for the slideshow widget:
56 * @li @ref slideshow_example
57 */
58
59/**
60 * @addtogroup Slideshow
61 * @{
62 */
63
64typedef struct _Elm_Slideshow_Item_Class Elm_Slideshow_Item_Class; /**< Slideshow item class definition struct */
65typedef struct _Elm_Slideshow_Item_Class_Func Elm_Slideshow_Item_Class_Func; /**< Class functions for slideshow item classes. */
66typedef Evas_Object *(*SlideshowItemGetFunc)(void *data, Evas_Object *obj); /**< Image fetching class function for slideshow item classes. */
67typedef void (*SlideshowItemDelFunc)(void *data, Evas_Object *obj); /**< Deletion class function for slideshow item classes. */
68
69/**
70 * @struct _Elm_Slideshow_Item_Class
71 *
72 * Slideshow item class definition. See @ref Slideshow_Items for
73 * field details.
74 */
75struct _Elm_Slideshow_Item_Class
76{
77 struct _Elm_Slideshow_Item_Class_Func
78 {
79 SlideshowItemGetFunc get;
80 SlideshowItemDelFunc del;
81 } func;
82}; /**< #Elm_Slideshow_Item_Class member definitions */
83
84/**
85 * Add a new slideshow widget to the given parent Elementary
86 * (container) object
87 *
88 * @param parent The parent object
89 * @return A new slideshow widget handle or @c NULL, on errors
90 *
91 * This function inserts a new slideshow widget on the canvas.
92 *
93 * @ingroup Slideshow
94 */
95EAPI Evas_Object *elm_slideshow_add(Evas_Object *parent);
96
97/**
98 * Add (append) a new item in a given slideshow widget.
99 *
100 * @param obj The slideshow object
101 * @param itc The item class for the item
102 * @param data The item's data
103 * @return A handle to the item added or @c NULL, on errors
104 *
105 * Add a new item to @p obj's internal list of items, appending it.
106 * The item's class must contain the function really fetching the
107 * image object to show for this item, which could be an Evas image
108 * object or an Elementary photo, for example. The @p data
109 * parameter is going to be passed to both class functions of the
110 * item.
111 *
112 * @see #Elm_Slideshow_Item_Class
113 * @see elm_slideshow_item_sorted_insert()
114 * @see elm_object_item_data_set()
115 *
116 * @ingroup Slideshow
117 */
118EAPI Elm_Object_Item *elm_slideshow_item_add(Evas_Object *obj, const Elm_Slideshow_Item_Class *itc, const void *data);
119
120/**
121 * Insert a new item into the given slideshow widget, using the @p func
122 * function to sort items (by item handles).
123 *
124 * @param obj The slideshow object
125 * @param itc The item class for the item
126 * @param data The item's data
127 * @param func The comparing function to be used to sort slideshow
128 * items <b>by #Elm_Slideshow_Item item handles</b>
129 * @return Returns The slideshow item handle, on success, or
130 * @c NULL, on errors
131 *
132 * Add a new item to @p obj's internal list of items, in a position
133 * determined by the @p func comparing function. The item's class
134 * must contain the function really fetching the image object to
135 * show for this item, which could be an Evas image object or an
136 * Elementary photo, for example. The @p data parameter is going to
137 * be passed to both class functions of the item.
138 *
139 * @see #Elm_Slideshow_Item_Class
140 * @see elm_slideshow_item_add()
141 *
142 * @ingroup Slideshow
143 */
144EAPI Elm_Object_Item *elm_slideshow_item_sorted_insert(Evas_Object *obj, const Elm_Slideshow_Item_Class *itc, const void *data, Eina_Compare_Cb func);
145
146/**
147 * Display a given slideshow widget's item, programmatically.
148 *
149 * @param it The item to display on @p obj's viewport
150 *
151 * The change between the current item and @p item will use the
152 * transition @p obj is set to use (@see
153 * elm_slideshow_transition_set()).
154 *
155 * @ingroup Slideshow
156 */
157EAPI void elm_slideshow_item_show(Elm_Object_Item *it);
158
159/**
160 * Slide to the @b next item, in a given slideshow widget
161 *
162 * @param obj The slideshow object
163 *
164 * The sliding animation @p obj is set to use will be the
165 * transition effect used, after this call is issued.
166 *
167 * @note If the end of the slideshow's internal list of items is
168 * reached, it'll wrap around to the list's beginning, again.
169 *
170 * @ingroup Slideshow
171 */
172EAPI void elm_slideshow_next(Evas_Object *obj);
173
174/**
175 * Slide to the @b previous item, in a given slideshow widget
176 *
177 * @param obj The slideshow object
178 *
179 * The sliding animation @p obj is set to use will be the
180 * transition effect used, after this call is issued.
181 *
182 * @note If the beginning of the slideshow's internal list of items
183 * is reached, it'll wrap around to the list's end, again.
184 *
185 * @ingroup Slideshow
186 */
187EAPI void elm_slideshow_previous(Evas_Object *obj);
188
189/**
190 * Returns the list of sliding transition/effect names available, for a
191 * given slideshow widget.
192 *
193 * @param obj The slideshow object
194 * @return The list of transitions (list of @b stringshared strings
195 * as data)
196 *
197 * The transitions, which come from @p obj's theme, must be an EDC
198 * data item named @c "transitions" on the theme file, with (prefix)
199 * names of EDC programs actually implementing them.
200 *
201 * The available transitions for slideshows on the default theme are:
202 * - @c "fade" - the current item fades out, while the new one
203 * fades in to the slideshow's viewport.
204 * - @c "black_fade" - the current item fades to black, and just
205 * then, the new item will fade in.
206 * - @c "horizontal" - the current item slides horizontally, until
207 * it gets out of the slideshow's viewport, while the new item
208 * comes from the left to take its place.
209 * - @c "vertical" - the current item slides vertically, until it
210 * gets out of the slideshow's viewport, while the new item comes
211 * from the bottom to take its place.
212 * - @c "square" - the new item starts to appear from the middle of
213 * the current one, but with a tiny size, growing until its
214 * target (full) size and covering the old one.
215 *
216 * @warning The stringshared strings get no new references
217 * exclusive to the user grabbing the list, here, so if you'd like
218 * to use them out of this call's context, you'd better @c
219 * eina_stringshare_ref() them. Also the list is an internal list and
220 * so is only valid for as long as the slideshow object is valid and
221 * has not internally changed its list for some reason, so make a
222 * copy if you need it around.
223 *
224 * @see elm_slideshow_transition_set()
225 *
226 * @ingroup Slideshow
227 */
228EAPI const Eina_List *elm_slideshow_transitions_get(const Evas_Object *obj);
229
230/**
231 * Set the current slide transition/effect in use for a given
232 * slideshow widget
233 *
234 * @param obj The slideshow object
235 * @param transition The new transition's name string
236 *
237 * If @p transition is implemented in @p obj's theme (i.e., is
238 * contained in the list returned by
239 * elm_slideshow_transitions_get()), this new sliding effect will
240 * be used on the widget.
241 *
242 * @see elm_slideshow_transitions_get() for more details
243 *
244 * @ingroup Slideshow
245 */
246EAPI void elm_slideshow_transition_set(Evas_Object *obj, const char *transition);
247
248/**
249 * Get the current slide transition/effect in use for a given
250 * slideshow widget
251 *
252 * @param obj The slideshow object
253 * @return The current transition's name
254 *
255 * @see elm_slideshow_transition_set() for more details
256 *
257 * @ingroup Slideshow
258 */
259EAPI const char *elm_slideshow_transition_get(const Evas_Object *obj);
260
261/**
262 * Set the interval between each image transition on a given
263 * slideshow widget, <b>and start the slideshow, itself</b>
264 *
265 * @param obj The slideshow object
266 * @param timeout The new displaying timeout for images
267 *
268 * After this call, the slideshow widget will start cycling its
269 * view, sequentially and automatically, with the images of the
270 * items it has. The time between each new image displayed is going
271 * to be @p timeout, in @b seconds. If a different timeout was set
272 * previously and an slideshow was in progress, it will continue
273 * with the new time between transitions, after this call.
274 *
275 * @note A value less than or equal to 0 on @p timeout will disable
276 * the widget's internal timer, thus halting any slideshow which
277 * could be happening on @p obj.
278 *
279 * @see elm_slideshow_timeout_get()
280 *
281 * @ingroup Slideshow
282 */
283EAPI void elm_slideshow_timeout_set(Evas_Object *obj, double timeout);
284
285/**
286 * Get the interval set for image transitions on a given slideshow
287 * widget.
288 *
289 * @param obj The slideshow object
290 * @return Returns the timeout set on it
291 *
292 * @see elm_slideshow_timeout_set() for more details
293 *
294 * @ingroup Slideshow
295 */
296EAPI double elm_slideshow_timeout_get(const Evas_Object *obj);
297
298/**
299 * Set if, after a slideshow is started, for a given slideshow
300 * widget, its items should be displayed cyclically or not.
301 *
302 * @param obj The slideshow object
303 * @param loop Use @c EINA_TRUE to make it cycle through items or
304 * @c EINA_FALSE for it to stop at the end of @p obj's internal
305 * list of items
306 *
307 * @note elm_slideshow_next() and elm_slideshow_previous() will @b
308 * ignore what is set by this functions, i.e., they'll @b always
309 * cycle through items. This affects only the "automatic"
310 * slideshow, as set by elm_slideshow_timeout_set().
311 *
312 * @see elm_slideshow_loop_get()
313 *
314 * @ingroup Slideshow
315 */
316EAPI void elm_slideshow_loop_set(Evas_Object *obj, Eina_Bool loop);
317
318/**
319 * Get if, after a slideshow is started, for a given slideshow
320 * widget, its items are to be displayed cyclically or not.
321 *
322 * @param obj The slideshow object
323 * @return @c EINA_TRUE, if the items in @p obj will be cycled
324 * through or @c EINA_FALSE, otherwise
325 *
326 * @see elm_slideshow_loop_set() for more details
327 *
328 * @ingroup Slideshow
329 */
330EAPI Eina_Bool elm_slideshow_loop_get(const Evas_Object *obj);
331
332/**
333 * Remove all items from a given slideshow widget
334 *
335 * @param obj The slideshow object
336 *
337 * This removes (and deletes) all items in @p obj, leaving it
338 * empty.
339 *
340 * @see elm_object_item_del(), to remove just one item.
341 *
342 * @ingroup Slideshow
343 */
344EAPI void elm_slideshow_clear(Evas_Object *obj);
345
346/**
347 * Get the internal list of items in a given slideshow widget.
348 *
349 * @param obj The slideshow object
350 * @return The list of items (#Elm_Object_Item as data) or
351 * @c NULL on errors.
352 *
353 * This list is @b not to be modified in any way and must not be
354 * freed. Use the list members with functions like
355 * elm_object_item_del(), elm_object_item_data_get().
356 *
357 * @warning This list is only valid until @p obj object's internal
358 * items list is changed. It should be fetched again with another
359 * call to this function when changes happen.
360 *
361 * @ingroup Slideshow
362 */
363EAPI const Eina_List *elm_slideshow_items_get(const Evas_Object *obj);
364
365/**
366 * Returns the currently displayed item, in a given slideshow widget
367 *
368 * @param obj The slideshow object
369 * @return A handle to the item being displayed in @p obj or
370 * @c NULL, if none is (and on errors)
371 *
372 * @ingroup Slideshow
373 */
374EAPI Elm_Object_Item *elm_slideshow_item_current_get(const Evas_Object *obj);
375
376/**
377 * Get the real Evas object created to implement the view of a
378 * given slideshow item
379 *
380 * @param it The slideshow item.
381 * @return the Evas object implementing this item's view.
382 *
383 * This returns the actual Evas object used to implement the
384 * specified slideshow item's view. This may be @c NULL, as it may
385 * not have been created or may have been deleted, at any time, by
386 * the slideshow. <b>Do not modify this object</b> (move, resize,
387 * show, hide, etc.), as the slideshow is controlling it. This
388 * function is for querying, emitting custom signals or hooking
389 * lower level callbacks for events on that object. Do not delete
390 * this object under any circumstances.
391 *
392 * @see elm_object_item_data_get()
393 *
394 * @ingroup Slideshow
395 */
396EAPI Evas_Object *elm_slideshow_item_object_get(const Elm_Object_Item *it);
397
398/**
399 * Get the the item, in a given slideshow widget, placed at
400 * position @p nth, in its internal items list
401 *
402 * @param obj The slideshow object
403 * @param nth The number of the item to grab a handle to (0 being
404 * the first)
405 * @return The item stored in @p obj at position @p nth or @c NULL,
406 * if there's no item with that index (and on errors)
407 *
408 * @ingroup Slideshow
409 */
410EAPI Elm_Object_Item *elm_slideshow_item_nth_get(const Evas_Object *obj, unsigned int nth);
411
412/**
413 * Set the current slide layout in use for a given slideshow widget
414 *
415 * @param obj The slideshow object
416 * @param layout The new layout's name string
417 *
418 * If @p layout is implemented in @p obj's theme (i.e., is contained
419 * in the list returned by elm_slideshow_layouts_get()), this new
420 * images layout will be used on the widget.
421 *
422 * @see elm_slideshow_layouts_get() for more details
423 *
424 * @ingroup Slideshow
425 */
426EAPI void elm_slideshow_layout_set(Evas_Object *obj, const char *layout);
427
428/**
429 * Get the current slide layout in use for a given slideshow widget
430 *
431 * @param obj The slideshow object
432 * @return The current layout's name
433 *
434 * @see elm_slideshow_layout_set() for more details
435 *
436 * @ingroup Slideshow
437 */
438EAPI const char *elm_slideshow_layout_get(const Evas_Object *obj);
439
440/**
441 * Returns the list of @b layout names available, for a given
442 * slideshow widget.
443 *
444 * @param obj The slideshow object
445 * @return The list of layouts (list of @b stringshared strings
446 * as data)
447 *
448 * Slideshow layouts will change how the widget is to dispose each
449 * image item in its viewport, with regard to cropping, scaling,
450 * etc.
451 *
452 * The layouts, which come from @p obj's theme, must be an EDC
453 * data item name @c "layouts" on the theme file, with (prefix)
454 * names of EDC programs actually implementing them.
455 *
456 * The available layouts for slideshows on the default theme are:
457 * - @c "fullscreen" - item images with original aspect, scaled to
458 * touch top and down slideshow borders or, if the image's height
459 * is not enough, left and right slideshow borders.
460 * - @c "not_fullscreen" - the same behavior as the @c "fullscreen"
461 * one, but always leaving 10% of the slideshow's dimensions of
462 * distance between the item image's borders and the slideshow
463 * borders, for each axis.
464 *
465 * @warning The stringshared strings get no new references
466 * exclusive to the user grabbing the list, here, so if you'd like
467 * to use them out of this call's context, you'd better @c
468 * eina_stringshare_ref() them.
469 *
470 * @see elm_slideshow_layout_set()
471 *
472 * @ingroup Slideshow
473 */
474EAPI const Eina_List *elm_slideshow_layouts_get(const Evas_Object *obj);
475
476/**
477 * Set the number of items to cache, on a given slideshow widget,
478 * <b>before the current item</b>
479 *
480 * @param obj The slideshow object
481 * @param count Number of items to cache before the current one
482 *
483 * The default value for this property is @c 2. See
484 * @ref Slideshow_Caching "slideshow caching" for more details.
485 *
486 * @see elm_slideshow_cache_before_get()
487 *
488 * @ingroup Slideshow
489 */
490EAPI void elm_slideshow_cache_before_set(Evas_Object *obj, int count);
491
492/**
493 * Retrieve the number of items to cache, on a given slideshow widget,
494 * <b>before the current item</b>
495 *
496 * @param obj The slideshow object
497 * @return The number of items set to be cached before the current one
498 *
499 * @see elm_slideshow_cache_before_set() for more details
500 *
501 * @ingroup Slideshow
502 */
503EAPI int elm_slideshow_cache_before_get(const Evas_Object *obj);
504
505/**
506 * Set the number of items to cache, on a given slideshow widget,
507 * <b>after the current item</b>
508 *
509 * @param obj The slideshow object
510 * @param count Number of items to cache after the current one
511 *
512 * The default value for this property is @c 2. See
513 * @ref Slideshow_Caching "slideshow caching" for more details.
514 *
515 * @see elm_slideshow_cache_after_get()
516 *
517 * @ingroup Slideshow
518 */
519EAPI void elm_slideshow_cache_after_set(Evas_Object *obj, int count);
520
521/**
522 * Retrieve the number of items to cache, on a given slideshow widget,
523 * <b>after the current item</b>
524 *
525 * @param obj The slideshow object
526 * @return The number of items set to be cached after the current one
527 *
528 * @see elm_slideshow_cache_after_set() for more details
529 *
530 * @ingroup Slideshow
531 */
532EAPI int elm_slideshow_cache_after_get(const Evas_Object *obj);
533
534/**
535 * Get the number of items stored in a given slideshow widget
536 *
537 * @param obj The slideshow object
538 * @return The number of items on @p obj, at the moment of this call
539 *
540 * @ingroup Slideshow
541 */
542EAPI unsigned int elm_slideshow_count_get(const Evas_Object *obj);
543
544/**
545 * @}
546 */