:github_url: https://github.com/kivymd/KivyMD/blob/master/kivymd/uix/carousel/carousel.py Carousel ======== .. py:module:: kivymd.uix.carousel.carousel .. autoapi-nested-parse:: Components/Carousel =================== .. versionadded:: 2.0.0 .. seealso:: `Material Design spec, Carousel `_ .. rubric:: Carousels show a collection of items that can be scrolled on and off the screen. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-preview.png :align: center - Contain visual items like images or video, along with optional label text - Six layouts: Multi-browse, uncontained, uncontained multi-aspect ratio, hero, center-aligned hero and full-screen - Layouts can be start-aligned or center-aligned - Item visuals have a parallax effect when scrolled - Items change size as they move through the carousel Usage ----- .. tabs:: .. tab:: Imperative python style .. code-block:: python from kivy.lang import Builder from kivy.metrics import dp from kivymd.app import MDApp from kivymd.uix.carousel import MDCarouselItem from kivymd.uix.fitimage import FitImage KV = ''' MDScreen: md_bg_color: self.theme_cls.backgroundColor MDCarousel: id: carousel layouts: "multi-browse" ''' class ExampleApp(MDApp): def on_start(self): for i in range(1, 20): carousel_item = MDCarouselItem() image = FitImage( source=f"https://picsum.photos/800/600?random={i}", radius=[dp(28)], ) carousel_item.add_widget(image) self.root.ids.carousel.add_widget(carousel_item) def build(self): self.theme_cls.theme_style = "Dark" return Builder.load_string(KV) if __name__ == "__main__": ExampleApp().run() .. tab:: Declarative python style .. code-block:: python from kivy.metrics import dp from kivymd.app import MDApp from kivymd.uix.carousel import MDCarousel, MDCarouselItem from kivymd.uix.fitimage import FitImage from kivymd.uix.screen import MDScreen class MyCarousel(MDCarousel): def __init__(self, **kwargs): super().__init__(**kwargs) images = [ f"https://picsum.photos/800/600?random={i}" for i in range(1, 20) ] self.widgets = [ MDCarouselItem( FitImage(source=img_url, radius=[dp(28)]) ) for img_url in images ] class ExampleApp(MDApp): def build(self): self.theme_cls.theme_style = "Dark" return MDScreen( MyCarousel( layouts="multi-browse", ), md_bg_color=self.theme_cls.backgroundColor, ) if __name__ == "__main__": ExampleApp().run() .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-usage.gif :align: center Anatomy ------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-anatomy.png :align: center API - :mod:`kivymd.uix.carousel.carousel` ----------------------------------------- .. py:class:: MDCarouselItem(*args, **kwargs) Implements a item for :class:`~MDCarousel` class. For more information, see in the :class:`~kivymd.uix.card.card.MDCard` class documentation. :Events: `on_slide_left` Fired when user slides/swipes to the left. `on_slide_right` Fired when user slides/swipes to the right. `on_slide_up` Fired when user slides/swipes up. `on_slide_down` Fired when user slides/swipes down. `on_index` Fired when the active slide index changes. .. py:attribute:: full_screen_radius Corner radius used during scrolling for items in full-screen layout modes. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-full-screen-radius.png :align: center :attr:`full_screen_radius` is a :class:`~kivy.properties.NumericProperty` and defaults to `dp(16)`. .. py:attribute:: radius Item radius by default. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-radius.png :align: center :attr:`radius` is an :class:`~kivy.properties.VariableListProperty` and defaults to `[dp(28), dp(28), dp(28), dp(28)]`. .. py:method:: add_widget(widget, index=0, canvas=None) Add a new widget as a child of this widget. :Parameters: `widget`: :class:`Widget` Widget to add to our list of children. `index`: int, defaults to 0 Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the :doc:`Widgets Programming Guide `. .. versionadded:: 1.0.5 `canvas`: str, defaults to None Canvas to add widget's canvas to. Can be 'before', 'after' or None for the default canvas. .. versionadded:: 1.9.0 .. code-block:: python >>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider) .. py:class:: MDCarousel(**kwargs) Implements a custom Material Design 3 carousel. For more information, see in the :class:`~kivymd.uix.widget.widget.MDWidget` class documentation. .. py:attribute:: padding Padding of the carousel view in the format ``[left, top, right, bottom]``. :attr:`padding` is an :class:`~kivy.properties.ListProperty` and defaults to ``[dp(16), dp(16), dp(16), dp(16)]``. .. py:attribute:: spacing Distance between items in the carousel. :attr:`spacing` is an :class:`~kivy.properties.NumericProperty` and defaults to ``dp(12)``. .. py:attribute:: shrink_extent Size of the collapsed or shrinked extent for trailing items. :attr:`shrink_extent` is an :class:`~kivy.properties.NumericProperty` and defaults to ``dp(56)``. .. py:attribute:: item_snapping If ``True``, enables automatic snapping of items to the closest slot upon touch release. :attr:`item_snapping` is an :class:`~kivy.properties.BooleanProperty` and defaults to ``True``. .. py:attribute:: scroll_offset Current scroll offset value of the carousel. :attr:`scroll_offset` is an :class:`~kivy.properties.NumericProperty` and defaults to ``0``. .. py:attribute:: layouts Layout type of the carousel view. Available options are: - ``"multi-browse"``: Standard layout displaying multiple items of varying sizes. - ``"uncontained"``: Items maintain a fixed width and overflow beyond the carousel edge. - ``"hero"``: Highlights a single large hero item aligned to the start. - ``"center-aligned"``: Displays a centered hero item flanked by smaller preview items. - ``"full-screen-horizontal"``: Items occupy the full width and height of the carousel, scrolling horizontally. - ``"full-screen-vertical"``: Items occupy the full width and height of the carousel, scrolling vertically. :attr:`layouts` is an :class:`~kivy.properties.OptionProperty` and defaults to ``"multi-browse"``. Multi-browse ------------ .. code-block:: kv MDCarousel: layouts: "multi-browse" .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-usage.gif :align: center Uncontained ----------- .. code-block:: kv MDCarousel: layouts: "uncontained" .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-uncontained.gif :align: center Hero ---- .. code-block:: kv MDCarousel: layouts: "hero" .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-hero.gif :align: center Center-aligned -------------- .. code-block:: kv MDCarousel: layouts: "center-aligned" .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-center-aligned.gif :align: center Full-screen-vertical ---------------------- .. code-block:: kv MDCarousel: layouts: "full-screen-vertical" .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-full-screen-vertical.gif :align: center :width: 60% Full-screen-horizontal ---------------------- .. code-block:: kv MDCarousel: layouts: "full-screen-horizontal" .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/carousel-full-screen-horizontal.gif :align: center :width: 60% .. py:attribute:: uncontained_item_width Width of individual items when using the ``"uncontained"`` layout mode. :attr:`uncontained_item_width` is an :class:`~kivy.properties.NumericProperty` and defaults to ``dp(280)``. .. py:attribute:: index Index of the currently active item. :attr:`index` is an :class:`~kivy.properties.NumericProperty` and defaults to ``0``. .. py:method:: add_widget(widget, index=0, canvas=None) Add a new widget as a child of this widget. :Parameters: `widget`: :class:`Widget` Widget to add to our list of children. `index`: int, defaults to 0 Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the :doc:`Widgets Programming Guide `. .. versionadded:: 1.0.5 `canvas`: str, defaults to None Canvas to add widget's canvas to. Can be 'before', 'after' or None for the default canvas. .. versionadded:: 1.9.0 .. code-block:: python >>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider) .. py:method:: on_touch_down(touch) Receive a touch down event. :Parameters: `touch`: :class:`~kivy.input.motionevent.MotionEvent` class Touch received. The touch is in parent coordinates. See :mod:`~kivy.uix.relativelayout` for a discussion on coordinate systems. :Returns: bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree. .. py:method:: on_touch_move(touch) Receive a touch move event. The touch is in parent coordinates. See :meth:`on_touch_down` for more information. .. py:method:: on_touch_up(touch) Receive a touch up event. The touch is in parent coordinates. See :meth:`on_touch_down` for more information. .. py:method:: on_index(instance, value) Fired when the active slide index changes. .. py:method:: on_slide_left() Fired when user slides/swipes to the left. .. py:method:: on_slide_right() Fired when user slides/swipes to the right. .. py:method:: on_slide_up() Fired when user slides/swipes up. .. py:method:: on_slide_down() Fired when user slides/swipes down.