path: root/src/lib/elementary/elm_slideshow.eo

type Elm_Slideshow_Item_Class: __undefined_type; [[Elementary slideshow item class type]]

class Elm.Slideshow (Efl.Ui.Layout, Efl.Access.Widget.Action)
{
   [[Elementary slideshow class]]
   eo_prefix: elm_obj_slideshow;
   legacy_prefix: elm_slideshow;
   event_prefix: elm_slideshow;
   methods {
      @property cache_after {
         set {
            [[Set the number of items to cache, on a given slideshow widget,
              after the current item.

              The default value for this property is 2. See
              \@ref Slideshow_Caching "slideshow caching" for more details.
            ]]
         }
         get {
            [[Get the number of items to cache, on a given slideshow widget,
              after the current item.
            ]]
         }
         values {
            count: int; [[Number of items to cache after the current one.]]
         }
      }
      @property cache_before {
         set {
            [[Set the number of items to cache, on a given slideshow widget,
              before the current item.

              The default value for this property is 2. See
              \@ref Slideshow_Caching "slideshow caching" for more details.
            ]]
         }
         get {
            [[Get the number of items to cache, on a given slideshow widget,
              before the current item.
            ]]
         }
         values {
            count: int; [[Number of items to cache before the current one.]]
         }
      }
      @property layout {
         set {
            [[Set the current slide layout in use for a given slideshow widget

              If $layout is implemented in $obj's theme (i.e., is contained
              in the list returned by elm_slideshow_layouts_get()), this new
              images layout will be used on the widget.

              See @.layouts.get for more details.
            ]]
         }
         get {
            [[Get the current slide layout in use for a given slideshow widget.]]
         }
         values {
            layout: string; [[The new layout's name string.]]
         }
      }
      @property transition {
         set {
            [[Set the current slide transition/effect in use for a given
              slideshow widget.

              If $transition is implemented in $obj's theme (i.e., is
              contained in the list returned by @.transitions.get), this
              new sliding effect will be used on the widget.
            ]]
         }
         get {
            [[Get the current slide transition/effect in use for a given
              slideshow widget.
            ]]
         }
         values {
            transition: string @nullable; [[The new transition's name string.]]
         }
      }
      @property loop {
         set {
            [[Set if the slideshow items should be displayed cyclically or not,
              so when the end is reached it will restart from the first item.

              Note: This will affect the "automatic" slidshow behaviour and the
              @.next and @.previous functions as well.
            ]]
         }
         get {
            [[Get if, after a slideshow is started, for a given slideshow
              widget, its items are to be displayed cyclically or not.
            ]]
         }
         values {
            loop: bool; [[Use $true to make it cycle through items or
                          $false for it to stop at the end of $obj's
                          internal list of items.]]
         }
      }
      @property timeout {
         set {
            [[Set the interval between each image transition on a given
              slideshow widget and start the slideshow itself.

              After this call, the slideshow widget will start cycling its
              view, sequentially and automatically, with the images of the
              items it has. The time between each new image displayed is
              going to be $timeout, in seconds. If a different timeout was
              set previously and an slideshow was in progress, it will
              continue with the new time between transitions, after this call.

              Note: A value less than or equal to 0 on $timeout will disable
              the widget's internal timer, thus halting any slideshow which
              could be happening on $obj.
            ]]
         }
         get {
            [[Get the interval set for image transitions on a given
              slideshow widget.
            ]]
         }
         values {
            timeout: double; [[The new displaying timeout for images.]]
         }
      }
      @property items {
         get {
            [[Get the internal list of items in a given slideshow widget.

              This list is not to be modified in any way and must not be
              freed.

              Warning: This list is only valid until $obj object's internal
              items list is changed. It should be fetched again with another
              call to this function when changes happen.
            ]]
            return: const(list<Elm.Widget.Item>); [[
               The list of items (#Elm.Widget.Item as data) or $null on
               errors.
            ]]
         }
      }
      @property transitions {
         get {
            [[Returns the list of sliding transition/effect names available,
              for a given slideshow widget.

              The transitions, which come from $obj's theme, must be an EDC
              data item named $"transitions" on the theme file, with (prefix)
              names of EDC programs actually implementing them.

              The available transitions for slideshows on the default theme
              are "fade" (the current item fades out, while the new one
              fades in to the slideshow's viewport), "black_fade" (the
              current item fades to black, and just then, the new item
              will fade in), "horizontal" (the current item slides
              horizontally, until it gets out of the slideshow's viewport,
              while the new item comes from the left to take its place),
              "vertical" (the current item slides vertically, until it
              gets out of the slideshow's viewport, while the new item
              comes from the bottom to take its place), "square" (the
              new item starts to appear from the middle of the current
              one, but with a tiny size, growing until its target (full)
              size and covering the old one.

              Warning: The stringshared strings get no new references
              exclusive to the user grabbing the list, here, so if you'd
              like to use them out of this call's context, you'd better
              \@ref eina_stringshare_ref them. Also the list is an internal
              list and so is only valid for as long as the slideshow object
              is valid and has not internally changed its list for some
              reason, so make a copy if you need it around.
            ]]
            return: const(list<string>); [[
               The list of transitions (list of stringshared strings
               as data).
            ]]
         }
      }
      @property count {
         get {
            [[Get the number of items stored in a given slideshow widget.]]
            return: uint; [[The number of items on $obj, at the moment of this call.]]
         }
      }
      @property item_current {
         get {
            [[Returns the currently displayed item, in a given slideshow widget.]]
            return: Elm.Widget.Item; [[A handle to the item being displayed
                                         in $obj or $null, if none is (and
                                         on errors)]]
         }
      }
      @property layouts {
         get {
            [[Returns the list of layout names available, for a given
              slideshow widget.

              Slideshow layouts will change how the widget is to dispose
              each image item in its viewport, with regard to cropping,
              scaling, etc.

              The layouts, which come from $obj's theme, must be an EDC
              data item name $"layouts" on the theme file, with (prefix)
              names of EDC programs actually implementing them.

              The available layouts for slideshows on the default theme are
              "fullscreen" (item images with original aspect, scaled to
              touch top and down slideshow borders or, if the image's height
              is not enough, left and right slideshow borders) and
              "not_fullscreen" (the same behavior as the "fullscreen"
              one, but always leaving 10% of the slideshow's dimensions of
              distance between the item image's borders and the slideshow
              borders, for each axis)-

              Warning: The stringshared strings get no new references
              exclusive to the user grabbing the list, here, so if you'd
              like to use them out of this call's context, you'd better
              \@ref eina_stringshare_ref them.
            ]]
            return: const(list<string>); [[
               The list of layouts (list of stringshared strings as data)
            ]]
         }
      }
      previous {
         [[Slide to the previous item, in a given slideshow widget

           The sliding animation $obj is set to use will be the
           transition effect used, after this call is issued.

           Note: If the beginning of the slideshow's internal list of items
           is reached, it'll wrap around to the list's end, again.
         ]]
      }
      item_nth_get @const {
         [[Get the the item, in a given slideshow widget, placed at
           position $nth, in its internal items list.
         ]]
         return: Elm.Widget.Item; [[The item stored in $obj at position
                                      $nth or $null if there's no item with
                                      that index (and on errors).]]
         params {
            @in nth: uint; [[The number of the item to grab a handle to
                             (0 being the first).]]
         }
      }
      next {
         [[Slide to the next item, in a given slideshow widget.

           The sliding animation $obj is set to use will be the
           transition effect used, after this call is issued.

           Note: If the end of the slideshow's internal list of items is
           reached, it'll wrap around to the list's beginning, again.
         ]]
      }
      clear {
         [[Remove all items from a given slideshow widget.

           This removes (and deletes) all items in $obj, leaving it empty.
         ]]
      }
      item_add {
         [[Add (append) a new item in a given slideshow widget.

           Add a new item to $obj's internal list of items, appending it.
           The item's class must contain the function really fetching the
           image object to show for this item, which could be an Evas image
           object or an Elementary photo, for example. The $data
           parameter is going to be passed to both class functions of the
           item.
         ]]
         return: Elm.Widget.Item; [[A handle to the item added or $null on errors.]]
         params {
            @cref itc: Elm_Slideshow_Item_Class; [[The item class for the item.]]
            @in data: const(void_ptr); [[The item's data.]]
         }
      }
      item_sorted_insert {
         [[Insert a new item into the given slideshow widget, using the
           $func function to sort items (by item handles).

           Add a new item to $obj's internal list of items, in a position
           determined by the $func comparing function. The item's class
           must contain the function really fetching the image object to
           show for this item, which could be an Evas image object or an
           Elementary photo, for example. The $data parameter is going to
           be passed to both class functions of the item.
         ]]
         return: Elm.Widget.Item; [[Returns The slideshow item handle,
                                      on success, or $null on errors.]]
         params {
            @cref itc: Elm_Slideshow_Item_Class; [[The item class for the item.]]
            @in data: const(void_ptr); [[The item's data.]]
            @in func: Eina_Compare_Cb; [[The comparing function to be used to sort the slideshow
                                         items by #Elm_Slideshow_Item_Class item handles.]]
         }
      }
   }
   implements {
      class.constructor;
      Efl.Object.constructor;
      Elm.Widget.widget_event;
      Efl.Access.Widget.Action.elm_actions { get; }
   }
   events {
      changed; [[Called when slideshow widget changed]]
      transition,end; [[Called on transition end]]
   }
}