SegmentedButton#

#

Added in version 1.2.0.

Segmented buttons help people select options, switch views, or sort elements.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-preview.png
  • Segmented buttons can contain icons, label text, or both

  • Two types: single-select and multi-select

  • Use for simple choices between two to five items (for more items or complex choices, use chips)

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-types.png
  1. Single-select segmented button

  2. Multi-select segmented button

Anatomy#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-anatomy.png

Icons#

Icons may be used as labels by themselves or alongside text. If an icon is used without label text, it must clearly communicate the option it represents.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-icons.png

Use with text and icon#

MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-python"

        MDSegmentButtonLabel:
            text: "Python"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-javascript"

        MDSegmentButtonLabel:
            text: "Java-Script"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-swift"

        MDSegmentButtonLabel:
            text: "Swift"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-use-with-text-and-icon.gif

Use without text with an icon#

MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-python"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-javascript"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-swift"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-use-without-text-with-an-icon.gif

Use only text#

MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Python"

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Java-Script"

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Swift"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-use-only-text.gif

Multiselect#

For multiple marking of elements, use the kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButton.multiselect parameter:

MDSegmentedButton:
    multiselect: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-multiselect-true.gif

Type#

Density can be used in denser UIs where space is limited. Density is only applied to the height. Each step down in density removes 4dp from the height.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-type.png
from kivy.lang import Builder

from kivymd.uix.label import MDLabel
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.segmentedbutton import (
    MDSegmentedButton,
    MDSegmentedButtonItem,
    MDSegmentButtonLabel,
)
from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        id: box
        orientation: "vertical"
        size_hint_x: .7
        adaptive_height: True
        spacing: "24dp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Example(MDApp):
    def on_start(self):
        for segment_type in ["large", "normal", "medium", "small"]:
            self.root.ids.box.add_widget(
                MDBoxLayout(
                    MDLabel(
                        text=f"Type '{segment_type}'",
                        adaptive_height=True,
                        bold=True,
                        pos_hint={"center_y": 0.5},
                        halign="center",
                    ),
                    MDSegmentedButton(
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Songs",
                            ),
                        ),
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Albums",
                            ),
                        ),
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Podcasts",
                            ),
                        ),
                        type=segment_type,
                    ),
                    orientation="vertical",
                    spacing="12dp",
                    adaptive_height=True,
                )
            )

    def build(self):
        return Builder.load_string(KV)


Example().run()

A practical example#

import os

from faker import Faker

from kivy.clock import Clock
from kivy.lang import Builder
from kivy.properties import StringProperty

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout

import asynckivy

KV = '''
<UserCard>
    adaptive_height: True
    radius: 16

    MDListItem:
        radius: 16
        theme_bg_color: "Custom"
        md_bg_color: self.theme_cls.secondaryContainerColor

        MDListItemLeadingAvatar:
            source: root.album

        MDListItemHeadlineText:
            text: root.name

        MDListItemSupportingText:
            text: root.path_to_file


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        orientation: "vertical"
        padding: "12dp"
        spacing: "12dp"

        MDLabel:
            adaptive_height: True
            text: "Your downloads"
            theme_font_style: "Custom"
            font_style: "Display"
            role: "small"

        MDSegmentedButton:
            size_hint_x: 1

            MDSegmentedButtonItem:
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Songs"
                    active: True

            MDSegmentedButtonItem:
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Albums"

            MDSegmentedButtonItem:
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Podcasts"

        RecycleView:
            id: card_list
            viewclass: "UserCard"
            bar_width: 0

            RecycleBoxLayout:
                orientation: 'vertical'
                spacing: "16dp"
                padding: "16dp"
                default_size: None, dp(72)
                default_size_hint: 1, None
                size_hint_y: None
                height: self.minimum_height
'''


class UserCard(MDBoxLayout):
    name = StringProperty()
    path_to_file = StringProperty()
    album = StringProperty()


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)

    def generate_card(self):
        async def generate_card():
            for i in range(10):
                await asynckivy.sleep(0)
                self.root.ids.card_list.data.append(
                    {
                        "name": fake.name(),
                        "path_to_file": f"{os.path.splitext(fake.file_path())[0]}.mp3",
                        "album": fake.image_url(),
                    }
                )

        fake = Faker()
        self.root.ids.card_list.data = []
        Clock.schedule_once(lambda x: asynckivy.start(generate_card()))


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-practical-example.gif

API break#

1.2.0 version#

MDSegmentedButton:
    on_marked: func(*args)

    MDSegmentedButtonItem:
        icon: ...
        text: ...

2.0.0 version#

MDSegmentedButton:

    MDSegmentedButtonItem:
        on_active: func(*args)

        MDSegmentButtonIcon:
            icon: ...

        MDSegmentButtonLabel:
            text: ...

API - kivymd.uix.segmentedbutton.segmentedbutton#

class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButtonItem(*args, **kwargs)#

Segment button item.

For more information see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and RectangularRippleBehavior and ButtonBehavior and StateLayerBehavior and RelativeLayout and class documentation.

selected_color#

Color of the marked segment.

Added in version 2.0.0.

selected_color is a ColorProperty and defaults to None.

md_bg_color_disabled#

The background color in (r, g, b, a) or string format of the list item when the list item is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

active#

Background color of an disabled segment.

active is an BooleanProperty and defaults to False.

add_widget(widget, *args, **kwargs)#

Add a new widget as a child of this widget.

Parameters:
widget: 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 Widgets Programming Guide.

Added in version 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.

Added in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
on_line_color(instance, value) None#

Fired when the values of line_color change.

on_active(instance, value) None#

Fired when the active value changes. Animates the marker icon for the element.

on_disabled(instance, value) None#

Fired when the disabled value changes.

class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButton(*args, **kwargs)#

Segment button panel.

For more information, see in the MDBoxLayout class documentation.

multiselect#

Do I allow multiple segment selection.

multiselect is an BooleanProperty and defaults to False.

hiding_icon_transition#

Name of the transition hiding the current icon.

hiding_icon_transition is a StringProperty and defaults to ‘linear’.

hiding_icon_duration#

Duration of hiding the current icon.

hiding_icon_duration is a NumericProperty and defaults to 1.

opening_icon_transition#

The name of the transition that opens a new icon of the “marked” type.

opening_icon_transition is a StringProperty and defaults to ‘linear’.

opening_icon_duration#

The duration of opening a new icon of the “marked” type.

opening_icon_duration is a NumericProperty and defaults to 0.1.

selected_segments#

The list of MDSegmentedButtonItem objects that are currently marked.

selected_segments is a ListProperty and defaults to [].

type#

Density can be used in denser UIs where space is limited. Density is only applied to the height. Each step down in density removes ‘4dp’ from the height.

Added in version 2.0.0.

Available options are: ‘large’, ‘normal’, ‘medium’, ‘small’.

type is an OptionProperty and defaults to ‘large’.

selected_icon_color#

Color in (r, g, b, a) or string format of the icon of the marked segment.

Added in version 2.0.0.

selected_icon_color is a ColorProperty and defaults to None.

get_marked_items() list#

Returns a list of active item objects.

get_items() list#

Returns a list of item objects.

adjust_segment_radius(*args) None#

Rounds off the first and last elements.

mark_item(segment_item: MDSegmentedButtonItem) None#

Fired when a segment element is clicked (on_release event).

add_widget(widget, *args, **kwargs)#

Add a new widget as a child of this widget.

Parameters:
widget: 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 Widgets Programming Guide.

Added in version 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.

Added in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)
remove_widget(widget, *args, **kwargs)#

Remove a widget from the children of this widget.

Parameters:
widget: Widget

Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)
class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentButtonIcon(*args, **kwargs)#

Implements a icon for MDSegmentedButtonItem class.

Added in version 2.0.0.

For more information, see in the MDIcon class documentation.

class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentButtonLabel(*args, **kwargs)#

Implements a label for MDSegmentedButtonItem class.

Added in version 2.0.0.

For more information, see in the MDLabel class documentation.