Slideshow

../_images/slideshow-preview.png

Widget description

This widget, as the name indicates, is a pre-made image slideshow panel, with API functions acting on (child) image items presentation. Between those actions, are:

  • advance to next/previous image

  • select the style of image transition animation

  • set the exhibition time for each image

  • start/stop the slideshow

The transition animations are defined in the widget’s theme, consequently new animations can be added without having to update the widget’s code.

Slideshow items

For slideshow items, just like for Genlist ones, the user defines a classes, specifying functions that will be called on the item’s creation and deletion times.

The SlideshowItemClass class contains the following members:

  • get - When an item is displayed, this function is called, and it’s where one should create the item object, de facto. For example, the object can be a pure Evas image object or a Photocam widget.

  • delete - When an item is no more displayed, this function is called, where the user must delete any data associated to the item.

Slideshow caching

The slideshow provides facilities to have items adjacent to the one being displayed already “realized” (i.e. loaded) for you, so that the system does not have to decode image data anymore at the time it has to actually switch images on its viewport. The user is able to set the numbers of items to be cached before and after the current item, in the widget’s item list.

Emitted signals

  • changed - when the slideshow switches its view to a new item. event_info parameter in callback contains the current visible item

  • transition,end - when a slide transition ends. event_info parameter in callback contains the current visible item

Inheritance diagram

Inheritance diagram of Slideshow
class efl.elementary.Slideshow(Object parent, *args, **kwargs)

Bases: efl.elementary.__init__.LayoutClass

This is the class that actually implements the widget.

Parameters
  • parent (efl.evas.Object) – The parent object

  • **kwargs – All the remaining keyword arguments are interpreted as properties of the instance

cache_after

The number of items to cache, on a given slideshow widget, after the current item

The default value for this property is 2.

Type

int

cache_before

The number of items to cache, on a given slideshow widget, before the current item

The default value for this property is 2.

Type

int

callback_changed_add(func, *args, **kwargs)

When the slideshow switches its view to a new item. event_info parameter in callback contains the current visible item.

callback_changed_del(func)
callback_transition_end_add(func, *args, **kwargs)

When a slide transition ends. event_info parameter in callback contains the current visible item.

callback_transition_end_del(func)
clear()

Remove all items from a given slideshow widget.

This removes (and deletes) all items in the object, leaving it empty.

See also

delete(), to remove just one item.

count

Get the number of items stored in a given slideshow widget

Type

int

current_item

The currently displayed item, in a given slideshow widget

Type

SlideshowItem

item_add(item_class, item_data)

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.

See also

SlideshowItemClass item_sorted_insert() efl.elementary.object_item.ObjectItem.data

Parameters
  • item_class (SlideshowItemClass) – The item class for the item

  • item_data – The data (model) associated with this item

Returns

A handle to the item added or None, on errors

Return type

SlideshowItem

Changed in version 1.14: use item_data param instead or args/kargs

item_sorted_insert(item_class, func, item_data)

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.

The compare function compares data1 and data2. If data1 is ‘less’ than data2, -1 must be returned, if it is ‘greater’, 1 must be returned, and if they are equal, 0 must be returned.

Parameters
  • itc – The item class for the item

  • func – The comparing function to be used to sort slideshow items by SlideshowItemClass item handles

  • item_data – The data (model) associated with this item

Returns

A handle to the item added or None, on errors

Return type

SlideshowItem

Changed in version 1.14: use item_data param instead or args/kargs

items

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. Use the list members with functions like delete(), data.

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.

Type

tuple of SlideshowItem

layout

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.

Type

string

layouts

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 the object 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.

  • "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.

See also

layout

Type

tuple of strings

loop

If the slideshow items should be displayed cyclically or not.

This means that, 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.

Type

bool

next()

Slide to the next item, in a given slideshow widget

The sliding animation the object 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.

nth_item_get(nth)

Get the the item, in a given slideshow widget, placed at position nth in its internal items list.

Parameters

nth (int) – The number of the item to grab a handle to (0 being the first)

Returns

The item stored in obj at position nth or None, if there’s no item with that index (and on errors)

Return type

SlideshowItem

previous()

Slide to the previous item, in a given slideshow widget

The sliding animation the object 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.

timeout

The interval between each image transition on a given slideshow widget, and start the slideshow, itself

After setting this, 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.

Type

float

transition

The 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), this new sliding effect will be used on the widget.

Type

string

transitions

Returns the list of sliding transition/effect names available, for a given slideshow widget.

The transitions, which come from the objects 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.

See also

transition

Type

tuple of strings

class efl.elementary.SlideshowItem(SlideshowItemClass item_class, item_data=None, *args, **kwargs)

Bases: efl.elementary.__init__.ObjectItem

An item for the Slideshow widget.

add_to(slideshow)

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.

Parameters

item_class (SlideshowItemClass) – The item class for the item

Returns

A handle to the item added or None, on errors

Return type

SlideshowItem

data

The data (model) associated with this item.

This is the data that has been passed to the add/sorted_insert functions, and the same that you get in the ItemClass get and delete functions.

New in version 1.14.

data_get()
object

Get the real Evas object created to implement the view of a given slideshow item.

This returns the actual Evas object used to implement the specified slideshow item’s view. This may be None, as it may not have been created or may have been deleted, at any time, by the slideshow. Do not modify this object (move, resize, show, hide, etc.), as the slideshow is controlling it. This function is for querying, emitting custom signals or hooking lower level callbacks for events on that object. Do not delete this object under any circumstances.

See also

data

Type

Slideshow

show()

Display a given slideshow widget’s item, programmatically.

The change between the current item and this item will use the transition the slideshow object is set to use.

sorted_insert(slideshow, func)

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.

The compare function compares data1 and data2. If data1 is ‘less’ than data2, -1 must be returned, if it is ‘greater’, 1 must be returned, and if they are equal, 0 must be returned.

Parameters
  • itc – The item class for the item

  • func – The comparing function to be used to sort slideshow items by SlideshowItemClass item handles

Returns

Returns The slideshow item handle, on success, or None, on errors

class efl.elementary.SlideshowItemClass(get_func=None, del_func=None)

Bases: object

Defines the behavior of each slideshow item.

This class should be created and handled to the Slideshow itself.

It may be subclassed, in this case the methods get() and delete() will be used.

It may also be instantiated directly, given getters to override as constructor parameters.

Parameters
  • get_func – if provided will override the behavior defined by get() in this class. Its purpose is to return the icon object to be used (swallowed) by a given part and row. This function should have the signature: func(obj, item_data) -> obj

  • del_func – if provided will override the behavior defined by delete() in this class. Its purpose is to be called when item is deleted, thus finalizing resources and similar. This function should have the signature: func(obj, item_data)

Note

In all these signatures, ‘obj’ means Slideshow and ‘item_data’ is the value given to Slideshow item add/sorted_insert methods, it should represent your item model as you want.

get(obj, item_data)

To be called by Slideshow for each item to get its icon.

Parameters
  • obj – the Slideshow instance

  • item_data – the value given to slideshow item_add func.

Returns

icon object to be used and swallowed.

Return type

evas Object or None