openCom-Companion/sbapp/kivymd/uix/segmentedbutton/segmentedbutton.py

"""
Components/SegmentedButton
==========================

.. versionadded:: 1.2.0

.. seealso::

    `Material Design spec, Segmented buttons <https://m3.material.io/components/segmented-buttons/overview>`_

    `Segmented control <https://kivymd.readthedocs.io/en/latest/components/segmentedcontrol/>`_

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

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-preview.png
    :align: center

Usage
-----

.. code-block:: kv

    MDScreen:

        MDSegmentedButton:

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

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

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

Example
-------

.. code-block:: python

    from kivy.lang import Builder

    from kivymd.app import MDApp

    KV = '''
    MDScreen:

        MDSegmentedButton:
            pos_hint: {"center_x": .5, "center_y": .5}

            MDSegmentedButtonItem:
                text: "Walking"

            MDSegmentedButtonItem:
                text: "Transit"

            MDSegmentedButtonItem:
                text: "Driving"
    '''


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


    Example().run()

By default, segmented buttons support single marking of elements:

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-multiselect-false.gif
    :align: center

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

.. code-block:: kv

    MDSegmentedButton:
        multiselect: True

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-multiselect-true.gif
    :align: center

Control width
-------------

The width of the panel of segmented buttons will be equal to the width
of the texture of the widest button multiplied by the number of buttons:

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-width-by-default.png
    :align: center

But you can use the `size_hint_x` parameter to specify the relative width:

.. code-block:: kv

    MDSegmentedButton:
        size_hint_x: .9

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-width-size-hint-x.png
    :align: center

Customization
-------------

You can see below in the documentation from which classes the
:class:`~kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButton` and
:class:`~kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButtonItem`
classes are inherited and use all their attributes such as
`md_bg_color`, `md_bg_color` etc. for additional customization of segments.

Events
------

- on_marked
    The method is called when a segment is marked.

- on_unmarked
    The method is called when a segment is unmarked.

.. code-block:: kv

    MDSegmentedButton:
        on_marked: app.on_marked(*args)

.. code-block:: python

    def on_marked(
        self,
        segment_button: MDSegmentedButton,
        segment_item: MDSegmentedButtonItem,
        marked: bool,
    ) -> None:
        print(segment_button)
        print(segment_item)
        print(marked)

A practical example
-------------------

.. code-block:: python

    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
    from kivymd.uix.segmentedbutton import MDSegmentedButton, MDSegmentedButtonItem
    from kivymd.utils import asynckivy

    KV = '''
    <UserCard>
        adaptive_height: True
        md_bg_color: "#343930"
        radius: 16

        TwoLineAvatarListItem:
            id: item
            divider: None
            _no_ripple_effect: True
            text: root.name
            secondary_text: root.path_to_file
            theme_text_color: "Custom"
            text_color: "#8A8D79"
            secondary_theme_text_color: self.theme_text_color
            secondary_text_color: self.text_color
            on_size:
                self.ids._left_container.size = (item.height, item.height)
                self.ids._left_container.x = dp(6)
                self._txt_right_pad = item.height + dp(12)

            ImageLeftWidget:
                source: root.album
                radius: root.radius


    MDScreen:
        md_bg_color: "#151514"

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

            MDLabel:
                adaptive_height: True
                text: "Your downloads"
                font_style: "H5"
                theme_text_color: "Custom"
                text_color: "#8A8D79"

            MDSegmentedButton:
                size_hint_x: 1
                selected_color: "#303A29"
                line_color: "#343930"
                on_marked: app.on_marked(*args)

                MDSegmentedButtonItem:
                    text: "Songs"
                    active: True

                MDSegmentedButtonItem:
                    text: "Albums"

                MDSegmentedButtonItem:
                    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"
            return Builder.load_string(KV)

        def on_marked(
            self,
            segment_button: MDSegmentedButton,
            segment_item: MDSegmentedButtonItem,
            marked: bool,
        ) -> None:
            self.generate_card()

        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()

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/segmented-button-practical-example.gif
    :align: center
"""

from __future__ import annotations

__all__ = ("MDSegmentedButton", "MDSegmentedButtonItem")

import os

from kivy.animation import Animation
from kivy.clock import Clock
from kivy.lang import Builder
from kivy.metrics import dp
from kivy.properties import (
    BooleanProperty,
    ColorProperty,
    ListProperty,
    NumericProperty,
    StringProperty,
    VariableListProperty,
)
from kivy.uix.behaviors import ButtonBehavior

from kivymd import uix_path
from kivymd.uix.behaviors import RectangularRippleBehavior, ScaleBehavior
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.label import MDIcon

with open(
    os.path.join(uix_path, "segmentedbutton", "segmentedbutton.kv"),
    encoding="utf-8",
) as kv_file:
    Builder.load_string(kv_file.read())


class MDSegmentedButtonItem(
    RectangularRippleBehavior, ButtonBehavior, MDFloatLayout
):
    """
    Segment button item.

    For more information, see in the
    :class:`~kivymd.uix.behaviors.RectangularRippleBehavior` and
    :class:`~kivy.uix.behaviors.ButtonBehavior` and
    :class:`~kivymd.uix.boxlayout.MDBoxLayout`
    class documentation.
    """

    icon = StringProperty()
    """
    Icon segment.

    :attr:`icon` is an :class:`~kivy.properties.StringProperty`
    and defaults to `''`.
    """

    text = StringProperty()
    """
    Text segment.

    :attr:`text` is an :class:`~kivy.properties.StringProperty`
    and defaults to `''`.
    """

    active = BooleanProperty(False)
    """
    Background color of an disabled segment.

    :attr:`active` is an :class:`~kivy.properties.BooleanProperty`
    and defaults to `False`.
    """

    disabled_color = ColorProperty(None)
    """
    Is active segment.

    :attr:`active` is an :class:`~kivy.properties.ColorProperty`
    and defaults to `None`.
    """

    _no_ripple_effect = BooleanProperty(True)
    _current_icon = ""
    _current_md_bg_color = None

    def on_disabled(self, instance, value: bool) -> None:
        def on_disabled(*args):
            if value:
                if not self._current_md_bg_color:
                    self._current_md_bg_color = self.md_bg_color
                self.md_bg_color = (
                    self.theme_cls.disabled_hint_text_color
                    if not self.disabled_color
                    else self.disabled_color
                )
            else:
                if self._current_md_bg_color:
                    self.md_bg_color = self._current_md_bg_color
                    self._current_md_bg_color = None

        Clock.schedule_once(on_disabled)

    def on_icon(self, instance, icon_name: str):
        if icon_name != "check":
            self._current_icon = icon_name


# TODO:
#  Add the feature to use both text and icons in segments -
#      https://m3.material.io/components/segmented-buttons/guidelines#26abac1c-c6bd-44c1-a969-8c910c880b98
#  Icons: optional check icon to indicate selected state -
#      https://m3.material.io/components/segmented-buttons/overview#7b80f313-7d3a-4865-b26c-1f7ec98ba694
#  Hovered: add a color for the hovered segment -
#      https://m3.material.io/components/segmented-buttons/specs#d730b3ba-c59e-4ef8-b652-20979fe20b67
#  Density: Each step down in density removes 4dp from the height -
#      https://m3.material.io/components/segmented-buttons/specs#2d5cab36-1deb-40bd-9e37-bc2bb1657009


class MDSegmentedButton(MDBoxLayout):
    """
    Segment button panel.

    For more information, see in the
    :class:`~kivymd.uix.boxlayout.MDBoxLayout` class documentation.

    :Events:
        `on_marked`
            The method is called when a segment is marked.
        `on_unmarked`
            The method is called when a segment is unmarked.
    """

    radius = VariableListProperty([20], length=4)
    """
    Panel radius.

    :attr:`radius` is an :class:`~kivy.properties.VariableListProperty`
    and defaults to `[20, 20, 20, 20]`.
    """

    multiselect = BooleanProperty(False)
    """
    Do I allow multiple segment selection.

    :attr:`multiselect` is an :class:`~kivy.properties.BooleanProperty`
    and defaults to `False`.
    """

    hiding_icon_transition = StringProperty("linear")
    """
    Name of the transition hiding the current icon.

    :attr:`hiding_icon_transition` is a :class:`~kivy.properties.StringProperty`
    and defaults to `'linear'`.
    """

    hiding_icon_duration = NumericProperty(0.05)
    """
    Duration of hiding the current icon.

    :attr:`hiding_icon_duration` is a :class:`~kivy.properties.NumericProperty`
    and defaults to `0.05`.
    """

    opening_icon_transition = StringProperty("linear")
    """
    The name of the transition that opens a new icon of the "marked" type.

    :attr:`opening_icon_transition` is a :class:`~kivy.properties.StringProperty`
    and defaults to `'linear'`.
    """

    opening_icon_duration = NumericProperty(0.05)
    """
    The duration of opening a new icon of the "marked" type.

    :attr:`opening_icon_duration` is a :class:`~kivy.properties.NumericProperty`
    and defaults to `0.05`.
    """

    selected_items = ListProperty()
    """
    The list of :class:`~MDSegmentedButtonItem` objects that are currently
    marked.

    :attr:`selected_items` is a :class:`~kivy.properties.ListProperty`
    and defaults to `[]`.
    """

    selected_color = ColorProperty(None)
    """
    Color of the marked segment.

    :attr:`selected_color` is a :class:`~kivy.properties.ColorProperty`
    and defaults to `None`.
    """

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.register_event_type("on_marked")
        self.register_event_type("on_unmarked")
        Clock.schedule_once(self.mark_segment)
        Clock.schedule_once(self.adjust_segment_radius)
        Clock.schedule_once(self.adjust_segment_panel_width, 2)

    def mark_segment(self, *args) -> None:
        """Programmatically marks a segment."""

        for widget in self.children:
            if widget.active:
                widget.active = False
                widget.dispatch("on_release")

                if not self.multiselect:
                    break

    def adjust_segment_radius(self, *args) -> None:
        """Rounds off the first and last elements."""

        if self.children[0].radius == [0, 0, 0, 0]:
            self.children[0].radius = (0, self.height / 2, self.height / 2, 0)
        if self.children[-1].radius == [0, 0, 0, 0]:
            self.children[-1].radius = (self.height / 2, 0, 0, self.height / 2)

    def adjust_segment_panel_width(self, *args) -> None:
        """
        Sets the width of all segments and the width of the panel
        by the widest segment.
        """

        if not self.size_hint_x:
            width_list = [
                widget.ids.label_text.texture_size[0]
                + (dp(72) if widget.icon else dp(48))
                for widget in self.children
            ]
            max_width = max(width_list)
            self.width = max_width * len(width_list)
        else:
            max_width = self.width / len(self.children)

        for widget in self.children:
            widget.width = max_width

        self.opacity = 1

        for widget in self.children:
            if widget.active:
                widget.dispatch("on_release")

    def shift_segment_text(self, segment_item: MDSegmentedButtonItem) -> None:
        """
        Shifts the segment text to the right, thus freeing up space
        for the icon (when the segment is marked).
        """

        Animation(
            x=(
                segment_item.ids.label_text.x
                + (
                    dp(16)
                    if not segment_item.icon and not segment_item.active
                    else 0
                )
            )
            if not segment_item.active
            else (
                segment_item.ids.label_text.x
                - (
                    dp(16)
                    if not segment_item.icon and segment_item.active
                    else 0
                )
            ),
            d=0.2,
        ).start(segment_item.ids.label_text)

    def show_icon_marked_segment(
        self, segment_item: MDSegmentedButtonItem
    ) -> None:
        """
        Sets the icon for the marked segment and changes the icon scale
        to the normal scale.
        """

        segment_item.ids.scale_icon.icon = "check"
        if segment_item.ids.scale_icon.icon == "check" and segment_item.active:
            segment_item.ids.scale_icon.icon = segment_item._current_icon

        Animation(
            scale_value_x=1,
            scale_value_y=1,
            d=self.opening_icon_duration,
            t=self.opening_icon_transition,
        ).start(segment_item.ids.scale_icon)

        self.shift_segment_text(segment_item)
        self.set_selected_segment_list(segment_item)
        self.set_bg_marked_segment(segment_item)

    def hide_icon_marked_segment(
        self, segment_item: MDSegmentedButtonItem
    ) -> None:
        """Changes the scale of the icon of the marked segment to zero."""

        anim = Animation(
            scale_value_x=0,
            scale_value_y=0,
            d=self.hiding_icon_duration,
            t=self.hiding_icon_transition,
        )
        anim.bind(
            on_complete=lambda x, y: self.show_icon_marked_segment(segment_item)
        )
        anim.start(segment_item.ids.scale_icon)

    def restore_bg_segment(self, segment_item) -> None:
        Animation(md_bg_color=self.md_bg_color, d=0.2).start(segment_item)

    def set_bg_marked_segment(self, segment_item) -> None:
        if segment_item.active:
            Animation(
                md_bg_color=self.selected_color
                if self.selected_color
                else self.theme_cls.primary_color,
                d=0.2,
            ).start(segment_item)

    def set_selected_segment_list(self, segment_item) -> None:
        segment_item.active = not segment_item.active

        if segment_item.active:
            self.selected_items.append(segment_item)
            self.dispatch("on_marked", segment_item, segment_item.active)
        else:
            if segment_item in self.selected_items:
                self.selected_items.remove(segment_item)
                self.dispatch("on_unmarked", segment_item, segment_item.active)

    def mark_item(self, segment_item: MDSegmentedButtonItem) -> None:
        if segment_item.active and not self.multiselect:
            return
        if not self.multiselect and self.selected_items:
            self.uncheck_item()
        else:
            if segment_item.active:
                self.restore_bg_segment(segment_item)

        self.hide_icon_marked_segment(segment_item)

    def uncheck_item(self) -> None:
        for item in self.children:
            if item.active:
                self.hide_icon_marked_segment(item)
                self.restore_bg_segment(item)
                break

    def add_widget(self, widget, *args, **kwargs):
        if isinstance(widget, MDSegmentedButtonItem):
            widget.bind(on_release=self.mark_item)
            return super().add_widget(widget)

    def on_size(self, instance_segment_button, size: list) -> None:
        """Called when the root screen is resized."""

        if self.size_hint_x:
            max_width = size[0] / len(self.children)
            for widget in self.children:
                widget.width = max_width

    def on_marked(self, *args):
        """The method is called when a segment is marked."""

    def on_unmarked(self, *args):
        """The method is called when a segment is unmarked."""


class SegmentButtonIcon(MDIcon, ScaleBehavior):
    """Implements an icon with scaling behavior."""