src/lib/elm_slideshow.h

   1 /**
   2  * @defgroup Slideshow Slideshow
   3  * @ingroup Elementary
   4  *
   5  * @image html slideshow_inheritance_tree.png
   6  * @image latex slideshow_inheritance_tree.eps
   7  *
   8  * @image html img/widget/slideshow/preview-00.png
   9  * @image latex img/widget/slideshow/preview-00.eps
  10  *
  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
  18  *
  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.
  22  *
  23  * @section Slideshow_Items Slideshow items
  24  *
  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.
  28  *
  29  * The #Elm_Slideshow_Item_Class structure contains the following
  30  * members:
  31  *
  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.
  40  *
  41  * @section Slideshow_Caching Slideshow caching
  42  *
  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
  49  * item list.
  50  *
  51  * This widget inherits from the @ref Layout one, so that all the
  52  * functions acting on it also work for slideshow objects.
  53  *
  54  * This widget emits the following signals, besides the ones sent from
  55  * @ref Layout:
  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
  60  *
  61  * List of examples for the slideshow widget:
  62  * @li @ref slideshow_example
  63  */
  64
  65 /**
  66  * @addtogroup Slideshow
  67  * @{
  68  */
  69
  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. */
  74
  75 /**
  76  * @struct _Elm_Slideshow_Item_Class
  77  *
  78  * Slideshow item class definition. See @ref Slideshow_Items for
  79  * field details.
  80  */
  81 struct _Elm_Slideshow_Item_Class
  82 {
  83    struct _Elm_Slideshow_Item_Class_Func
  84      {
  85         SlideshowItemGetFunc get;
  86         SlideshowItemDelFunc del;
  87      } func;
  88 };   /**< member definitions of #Elm_Slideshow_Item_Class */
  89
  90 /**
  91  * Add a new slideshow widget to the given parent Elementary
  92  * (container) object
  93  *
  94  * @param parent The parent object
  95  * @return A new slideshow widget handle or @c NULL, on errors
  96  *
  97  * This function inserts a new slideshow widget on the canvas.
  98  *
  99  * @ingroup Slideshow
 100  */
 101 EAPI Evas_Object          *elm_slideshow_add(Evas_Object *parent);
 102
 103 /**
 104  * Add (append) a new item in a given slideshow widget.
 105  *
 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
 110  *
 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
 116  * item.
 117  *
 118  * @see #Elm_Slideshow_Item_Class
 119  * @see elm_slideshow_item_sorted_insert()
 120  * @see elm_object_item_data_set()
 121  *
 122  * @ingroup Slideshow
 123  */
 124 EAPI Elm_Object_Item      *elm_slideshow_item_add(Evas_Object *obj, const Elm_Slideshow_Item_Class *itc, const void *data);
 125
 126 /**
 127  * Insert a new item into the given slideshow widget, using the @p func
 128  * function to sort items (by item handles).
 129  *
 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
 136  * @c NULL, on errors
 137  *
 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.
 144  *
 145  * @see #Elm_Slideshow_Item_Class
 146  * @see elm_slideshow_item_add()
 147  *
 148  * @ingroup Slideshow
 149  */
 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);
 151
 152 /**
 153  * Display a given slideshow widget's item, programmatically.
 154  *
 155  * @param it The item to display on @p obj's viewport
 156  *
 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()).
 160  *
 161  * @ingroup Slideshow
 162  */
 163 EAPI void                  elm_slideshow_item_show(Elm_Object_Item *it);
 164
 165 /**
 166  * Slide to the @b next item, in a given slideshow widget
 167  *
 168  * @param obj The slideshow object
 169  *
 170  * The sliding animation @p obj is set to use will be the
 171  * transition effect used, after this call is issued.
 172  *
 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.
 175  *
 176  * @ingroup Slideshow
 177  */
 178 EAPI void                  elm_slideshow_next(Evas_Object *obj);
 179
 180 /**
 181  * Slide to the @b previous item, in a given slideshow widget
 182  *
 183  * @param obj The slideshow object
 184  *
 185  * The sliding animation @p obj is set to use will be the
 186  * transition effect used, after this call is issued.
 187  *
 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.
 190  *
 191  * @ingroup Slideshow
 192  */
 193 EAPI void                  elm_slideshow_previous(Evas_Object *obj);
 194
 195 /**
 196  * Returns the list of sliding transition/effect names available, for a
 197  * given slideshow widget.
 198  *
 199  * @param obj The slideshow object
 200  * @return The list of transitions (list of @b stringshared strings
 201  * as data)
 202  *
 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.
 206  *
 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.
 221  *
 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.
 229  *
 230  * @see elm_slideshow_transition_set()
 231  *
 232  * @ingroup Slideshow
 233  */
 234 EAPI const Eina_List      *elm_slideshow_transitions_get(const Evas_Object *obj);
 235
 236 /**
 237  * Set the current slide transition/effect in use for a given
 238  * slideshow widget
 239  *
 240  * @param obj The slideshow object
 241  * @param transition The new transition's name string
 242  *
 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.
 247  *
 248  * @see elm_slideshow_transitions_get() for more details
 249  *
 250  * @ingroup Slideshow
 251  */
 252 EAPI void                  elm_slideshow_transition_set(Evas_Object *obj, const char *transition);
 253
 254 /**
 255  * Get the current slide transition/effect in use for a given
 256  * slideshow widget
 257  *
 258  * @param obj The slideshow object
 259  * @return The current transition's name
 260  *
 261  * @see elm_slideshow_transition_set() for more details
 262  *
 263  * @ingroup Slideshow
 264  */
 265 EAPI const char           *elm_slideshow_transition_get(const Evas_Object *obj);
 266
 267 /**
 268  * Set the interval between each image transition on a given
 269  * slideshow widget, <b>and start the slideshow, itself</b>
 270  *
 271  * @param obj The slideshow object
 272  * @param timeout The new displaying timeout for images
 273  *
 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.
 280  *
 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.
 284  *
 285  * @see elm_slideshow_timeout_get()
 286  *
 287  * @ingroup Slideshow
 288  */
 289 EAPI void                  elm_slideshow_timeout_set(Evas_Object *obj, double timeout);
 290
 291 /**
 292  * Get the interval set for image transitions on a given slideshow
 293  * widget.
 294  *
 295  * @param obj The slideshow object
 296  * @return Returns the timeout set on it or -1.0, on errors
 297  *
 298  * @see elm_slideshow_timeout_set() for more details
 299  *
 300  * @ingroup Slideshow
 301  */
 302 EAPI double                elm_slideshow_timeout_get(const Evas_Object *obj);
 303
 304 /**
 305  * Set if, after a slideshow is started, for a given slideshow
 306  * widget, its items should be displayed cyclically or not.
 307  *
 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
 311  * list of items
 312  *
 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().
 317  *
 318  * @see elm_slideshow_loop_get()
 319  *
 320  * @ingroup Slideshow
 321  */
 322 EAPI void                  elm_slideshow_loop_set(Evas_Object *obj, Eina_Bool loop);
 323
 324 /**
 325  * Get if, after a slideshow is started, for a given slideshow
 326  * widget, its items are to be displayed cyclically or not.
 327  *
 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
 331  *
 332  * @see elm_slideshow_loop_set() for more details
 333  *
 334  * @ingroup Slideshow
 335  */
 336 EAPI Eina_Bool             elm_slideshow_loop_get(const Evas_Object *obj);
 337
 338 /**
 339  * Remove all items from a given slideshow widget
 340  *
 341  * @param obj The slideshow object
 342  *
 343  * This removes (and deletes) all items in @p obj, leaving it
 344  * empty.
 345  *
 346  * @see elm_object_item_del(), to remove just one item.
 347  *
 348  * @ingroup Slideshow
 349  */
 350 EAPI void                  elm_slideshow_clear(Evas_Object *obj);
 351
 352 /**
 353  * Get the internal list of items in a given slideshow widget.
 354  *
 355  * @param obj The slideshow object
 356  * @return The list of items (#Elm_Object_Item as data) or
 357  * @c NULL on errors.
 358  *
 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().
 362  *
 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.
 366  *
 367  * @ingroup Slideshow
 368  */
 369 EAPI const Eina_List      *elm_slideshow_items_get(const Evas_Object *obj);
 370
 371 /**
 372  * Returns the currently displayed item, in a given slideshow widget
 373  *
 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)
 377  *
 378  * @ingroup Slideshow
 379  */
 380 EAPI Elm_Object_Item      *elm_slideshow_item_current_get(const Evas_Object *obj);
 381
 382 /**
 383  * Get the real Evas object created to implement the view of a
 384  * given slideshow item
 385  *
 386  * @param it The slideshow item.
 387  * @return the Evas object implementing this item's view.
 388  *
 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.
 397  *
 398  * @see elm_object_item_data_get()
 399  *
 400  * @ingroup Slideshow
 401  */
 402 EAPI Evas_Object          *elm_slideshow_item_object_get(const Elm_Object_Item *it);
 403
 404 /**
 405  * Get the the item, in a given slideshow widget, placed at
 406  * position @p nth, in its internal items list
 407  *
 408  * @param obj The slideshow object
 409  * @param nth The number of the item to grab a handle to (0 being
 410  * the first)
 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)
 413  *
 414  * @ingroup Slideshow
 415  */
 416 EAPI Elm_Object_Item      *elm_slideshow_item_nth_get(const Evas_Object *obj, unsigned int nth);
 417
 418 /**
 419  * Set the current slide layout in use for a given slideshow widget
 420  *
 421  * @param obj The slideshow object
 422  * @param layout The new layout's name string
 423  *
 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.
 427  *
 428  * @see elm_slideshow_layouts_get() for more details
 429  *
 430  * @ingroup Slideshow
 431  */
 432 EAPI void                  elm_slideshow_layout_set(Evas_Object *obj, const char *layout);
 433
 434 /**
 435  * Get the current slide layout in use for a given slideshow widget
 436  *
 437  * @param obj The slideshow object
 438  * @return The current layout's name
 439  *
 440  * @see elm_slideshow_layout_set() for more details
 441  *
 442  * @ingroup Slideshow
 443  */
 444 EAPI const char           *elm_slideshow_layout_get(const Evas_Object *obj);
 445
 446 /**
 447  * Returns the list of @b layout names available, for a given
 448  * slideshow widget.
 449  *
 450  * @param obj The slideshow object
 451  * @return The list of layouts (list of @b stringshared strings
 452  * as data)
 453  *
 454  * Slideshow layouts will change how the widget is to dispose each
 455  * image item in its viewport, with regard to cropping, scaling,
 456  * etc.
 457  *
 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.
 461  *
 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.
 470  *
 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.
 475  *
 476  * @see elm_slideshow_layout_set()
 477  *
 478  * @ingroup Slideshow
 479  */
 480 EAPI const Eina_List      *elm_slideshow_layouts_get(const Evas_Object *obj);
 481
 482 /**
 483  * Set the number of items to cache, on a given slideshow widget,
 484  * <b>before the current item</b>
 485  *
 486  * @param obj The slideshow object
 487  * @param count Number of items to cache before the current one
 488  *
 489  * The default value for this property is @c 2. See
 490  * @ref Slideshow_Caching "slideshow caching" for more details.
 491  *
 492  * @see elm_slideshow_cache_before_get()
 493  *
 494  * @ingroup Slideshow
 495  */
 496 EAPI void                  elm_slideshow_cache_before_set(Evas_Object *obj, int count);
 497
 498 /**
 499  * Retrieve the number of items to cache, on a given slideshow widget,
 500  * <b>before the current item</b>
 501  *
 502  * @param obj The slideshow object
 503  * @return The number of items set to be cached before the current one
 504  *
 505  * @see elm_slideshow_cache_before_set() for more details
 506  *
 507  * @ingroup Slideshow
 508  */
 509 EAPI int                   elm_slideshow_cache_before_get(const Evas_Object *obj);
 510
 511 /**
 512  * Set the number of items to cache, on a given slideshow widget,
 513  * <b>after the current item</b>
 514  *
 515  * @param obj The slideshow object
 516  * @param count Number of items to cache after the current one
 517  *
 518  * The default value for this property is @c 2. See
 519  * @ref Slideshow_Caching "slideshow caching" for more details.
 520  *
 521  * @see elm_slideshow_cache_after_get()
 522  *
 523  * @ingroup Slideshow
 524  */
 525 EAPI void                  elm_slideshow_cache_after_set(Evas_Object *obj, int count);
 526
 527 /**
 528  * Retrieve the number of items to cache, on a given slideshow widget,
 529  * <b>after the current item</b>
 530  *
 531  * @param obj The slideshow object
 532  * @return The number of items set to be cached after the current one
 533  *
 534  * @see elm_slideshow_cache_after_set() for more details
 535  *
 536  * @ingroup Slideshow
 537  */
 538 EAPI int                   elm_slideshow_cache_after_get(const Evas_Object *obj);
 539
 540 /**
 541  * Get the number of items stored in a given slideshow widget
 542  *
 543  * @param obj The slideshow object
 544  * @return The number of items on @p obj, at the moment of this call
 545  *
 546  * @ingroup Slideshow
 547  */
 548 EAPI unsigned int          elm_slideshow_count_get(const Evas_Object *obj);
 549
 550 /**
 551  * @}
 552  */