src/lib/elm_slideshow.h

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