aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/elementary/elm_slideshow.eo
blob: b51ee63b7143839075d12ef5a3b5656fe3dabb9c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
type Elm_Slideshow_Item_Class: __undefined_type; [[Elementary slideshow item class type]]

class Elm.Slideshow (Efl.Ui.Layout, Efl.Access.Widget.Action, Efl.Ui.Legacy)
{
   [[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 items_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.
            ]]
            legacy: elm_slideshow_loop_set;
         }
         get {
            [[Get if, after a slideshow is started, for a given slideshow
              widget, its items are to be displayed cyclically or not.
            ]]
            legacy: elm_slideshow_loop_get;
         }
         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;
      Efl.Ui.Widget.widget_event;
      Efl.Access.Widget.Action.elm_actions { get; }
   }
   events {
      changed: Efl.Object; [[Called when slideshow widget changed]]
      transition,end: Efl.Object; [[Called on transition end]]
   }
}