Carousel¶

New in version 1.4.0.

The Carousel widget provides the classic mobile-friendly carousel view where you can swipe between slides. You can add any content to the carousel and have it move horizontally or vertically. The carousel can display pages in a sequence or a loop.

Example:

from kivy.app import App
from kivy.uix.carousel import Carousel
from kivy.uix.image import AsyncImage


class CarouselApp(App):
    def build(self):
        carousel = Carousel(direction='right')
        for i in range(10):
            src = "http://placehold.it/480x270.png&text=slide-%d&.png" % i
            image = AsyncImage(source=src, allow_stretch=True)
            carousel.add_widget(image)
        return carousel


CarouselApp().run()

Changed in version 1.5.0: The carousel now supports active children, like the ScrollView. It will detect a swipe gesture according to the Carousel.scroll_timeout and Carousel.scroll_distance properties.

In addition, the slide container is no longer exposed by the API. The impacted properties are Carousel.slides, Carousel.current_slide, Carousel.previous_slide and Carousel.next_slide.

class kivy.uix.carousel.Carousel(**kwargs)[source]¶

Bases: kivy.uix.stencilview.StencilView

Carousel class. See module documentation for more information.

anim_cancel_duration¶

Defines the duration of the animation when a swipe movement is not accepted. This is generally when the user does not make a large enough swipe. See min_move.

anim_cancel_duration is a NumericProperty and defaults to 0.3.

anim_move_duration¶

Defines the duration of the Carousel animation between pages.

anim_move_duration is a NumericProperty and defaults to 0.5.

anim_type¶

Type of animation to use while animating to the next/previous slide. This should be the name of an AnimationTransition function.

anim_type is a StringProperty and defaults to ‘out_quad’.

New in version 1.8.0.

current_slide¶

The currently shown slide.

current_slide is an AliasProperty.

Changed in version 1.5.0: The property no longer exposes the slides container. It returns the widget you have added.

direction¶

Specifies the direction in which the slides are ordered. This corresponds to the direction from which the user swipes to go from one slide to the next. It can be right, left, top, or bottom. For example, with the default value of right, the second slide is to the right of the first and the user would swipe from the right towards the left to get to the second slide.

direction is an OptionProperty and defaults to ‘right’.

ignore_perpendicular_swipes¶

Ignore swipes on axis perpendicular to direction.

ignore_perpendicular_swipes is a BooleanProperty and defaults to False.

New in version 1.10.0.

index¶

Get/Set the current slide based on the index.

index is an AliasProperty and defaults to 0 (the first item).

load_next(mode='next')[source]¶: Animate to the next slide.

New in version 1.7.0.

load_previous()[source]¶: Animate to the previous slide.

New in version 1.7.0.

load_slide(slide)[source]¶: Animate to the slide that is passed as the argument.

Changed in version 1.8.0.

loop¶

Allow the Carousel to loop infinitely. If True, when the user tries to swipe beyond last page, it will return to the first. If False, it will remain on the last page.

loop is a BooleanProperty and defaults to False.

min_move¶

Defines the minimum distance to be covered before the touch is considered a swipe gesture and the Carousel content changed. This is a expressed as a fraction of the Carousel’s width. If the movement doesn’t reach this minimum value, the movement is cancelled and the content is restored to its original position.

min_move is a NumericProperty and defaults to 0.2.

next_slide¶

The next slide in the Carousel. It is None if the current slide is the last slide in the Carousel. This ordering reflects the order in which the slides are added: their presentation varies according to the direction property.

next_slide is an AliasProperty.

Changed in version 1.5.0: The property no longer exposes the slides container. It returns the widget you have added.

previous_slide¶

The previous slide in the Carousel. It is None if the current slide is the first slide in the Carousel. This ordering reflects the order in which the slides are added: their presentation varies according to the direction property.

previous_slide is an AliasProperty.

Changed in version 1.5.0: This property no longer exposes the slides container. It returns the widget you have added.

scroll_distance¶

Distance to move before scrolling the Carousel in pixels. As soon as the distance has been traveled, the Carousel will start to scroll, and no touch event will go to children. It is advisable that you base this value on the dpi of your target device’s screen.

scroll_distance is a NumericProperty and defaults to 20dp.

New in version 1.5.0.

scroll_timeout¶

Timeout allowed to trigger the scroll_distance, in milliseconds. If the user has not moved scroll_distance within the timeout, no scrolling will occur and the touch event will go to the children.

scroll_timeout is a NumericProperty and defaults to 200 (milliseconds)

New in version 1.5.0.

slides¶

List of slides inside the Carousel. The slides are the widgets added to the Carousel using the add_widget method.

slides is a ListProperty and is read-only.