src/lib/elm_slideshow.h

   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
  64 typedef struct _Elm_Slideshow_Item_Class      Elm_Slideshow_Item_Class; /**< Slideshow item class definition struct */
  65 typedef struct _Elm_Slideshow_Item_Class_Func Elm_Slideshow_Item_Class_Func;    /**< Class functions for slideshow item classes. */
  66 typedef Evas_Object                        *(*SlideshowItemGetFunc)(void *data, Evas_Object *obj); /**< Image fetching class function for slideshow item classes. */
  67 typedef 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  */
  75 struct _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  */
  95 EAPI 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  */
 118 EAPI 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  */
 144 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);
 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  */
 157 EAPI 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  */
 172 EAPI 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  */
 187 EAPI 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  */
 228 EAPI 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  */
 246 EAPI 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  */
 259 EAPI 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  */
 283 EAPI 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  */
 296 EAPI 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  */
 316 EAPI 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  */
 330 EAPI 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  */
 344 EAPI 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  */
 363 EAPI 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  */
 374 EAPI 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  */
 396 EAPI 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  */
 410 EAPI 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  */
 426 EAPI 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  */
 438 EAPI 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  */
 474 EAPI 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  */
 490 EAPI 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  */
 503 EAPI 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  */
 519 EAPI 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  */
 532 EAPI 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  */
 542 EAPI unsigned int          elm_slideshow_count_get(const Evas_Object *obj);
 543
 544 /**
 545  * @}
 546  */