src/lib/elm_slideshow.h

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