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

"""
Components/BottomNavigation
===========================

.. seealso::

    `Material Design 2 spec, Bottom navigation <https://material.io/components/bottom-navigation>`_ and
    `Material Design 3 spec, Bottom navigation <https://m3.material.io/components/navigation-bar/overview>`_

.. rubric:: Bottom navigation bars allow movement between primary destinations in an app:

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation.png
    :align: center

Usage
-----

.. code-block:: kv

    <Root>

        MDBottomNavigation:

            MDBottomNavigationItem:
                name: "screen 1"

                YourContent:

            MDBottomNavigationItem:
                name: "screen 2"

                YourContent:

            MDBottomNavigationItem:
                name: "screen 3"

                YourContent:

For ease of understanding, this code works like this:

.. code-block:: kv

    <Root>

        ScreenManager:

            Screen:
                name: "screen 1"

                YourContent:

            Screen:
                name: "screen 2"

                YourContent:

            Screen:
                name: "screen 3"

                YourContent:

Example
-------

.. tabs::

    .. tab:: Declarative KV style

        .. code-block:: python

            from kivy.lang import Builder

            from kivymd.app import MDApp


            class Test(MDApp):

                def build(self):
                    self.theme_cls.material_style = "M3"
                    self.theme_cls.theme_style = "Dark"
                    return Builder.load_string(
                        '''
            MDScreen:

                MDBottomNavigation:
                    #panel_color: "#eeeaea"
                    selected_color_background: "orange"
                    text_color_active: "lightgrey"

                    MDBottomNavigationItem:
                        name: 'screen 1'
                        text: 'Mail'
                        icon: 'gmail'
                        badge_icon: "numeric-10"

                        MDLabel:
                            text: 'Mail'
                            halign: 'center'

                    MDBottomNavigationItem:
                        name: 'screen 2'
                        text: 'Twitter'
                        icon: 'twitter'
                        badge_icon: "numeric-5"

                        MDLabel:
                            text: 'Twitter'
                            halign: 'center'

                    MDBottomNavigationItem:
                        name: 'screen 3'
                        text: 'LinkedIN'
                        icon: 'linkedin'

                        MDLabel:
                            text: 'LinkedIN'
                            halign: 'center'
            '''
                    )


            Test().run()

    .. tab:: Declarative python style

        .. code-block:: python

            from kivymd.app import MDApp
            from kivymd.uix.bottomnavigation import MDBottomNavigation, MDBottomNavigationItem
            from kivymd.uix.label import MDLabel
            from kivymd.uix.screen import MDScreen


            class Test(MDApp):
                def build(self):
                    self.theme_cls.material_style = "M3"
                    self.theme_cls.theme_style = "Dark"
                    return (
                        MDScreen(
                            MDBottomNavigation(
                                MDBottomNavigationItem(
                                    MDLabel(
                                        text='Mail',
                                        halign='center',
                                    ),
                                    name='screen 1',
                                    text='Mail',
                                    icon='gmail',
                                    badge_icon="numeric-10",
                                ),
                                MDBottomNavigationItem(
                                    MDLabel(
                                        text='Twitter',
                                        halign='center',
                                    ),
                                    name='screen 1',
                                    text='Twitter',
                                    icon='twitter',
                                    badge_icon="numeric-10",
                                ),
                                MDBottomNavigationItem(
                                    MDLabel(
                                        text='LinkedIN',
                                        halign='center',
                                    ),
                                    name='screen 1',
                                    text='LinkedIN',
                                    icon='linkedin',
                                    badge_icon="numeric-10",
                                ),
                                selected_color_background="orange",
                                text_color_active="lightgrey",
                            )
                        )
                    )


            Test().run()

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation.gif
    :align: center

.. rubric:: :class:`~MDBottomNavigationItem` provides the following events for use:

.. code-block:: python

    __events__ = (
        "on_tab_touch_down",
        "on_tab_touch_move",
        "on_tab_touch_up",
        "on_tab_press",
        "on_tab_release",
    )

.. code-block:: kv

    Root:

        MDBottomNavigation:

            MDBottomNavigationItem:
                on_tab_touch_down: print("on_tab_touch_down")
                on_tab_touch_move: print("on_tab_touch_move")
                on_tab_touch_up: print("on_tab_touch_up")
                on_tab_press: print("on_tab_press")
                on_tab_release: print("on_tab_release")

                YourContent:

How to automatically switch a tab?
----------------------------------

Use method :attr:`~MDBottomNavigation.switch_tab` which takes as argument
the name of the tab you want to switch to.

Use custom icon
---------------

.. code-block:: kv

    MDBottomNavigation:

        MDBottomNavigationItem:
            icon: "icon.png"

.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation-custom-icon.png
    :align: center
"""

__all__ = (
    "TabbedPanelBase",
    "MDBottomNavigationItem",
    "MDBottomNavigation",
    "MDTab",
)

import os
from typing import Union

from kivy.animation import Animation
from kivy.clock import Clock
from kivy.core.window import Window
from kivy.core.window.window_sdl2 import WindowSDL
from kivy.lang import Builder
from kivy.metrics import dp, sp
from kivy.properties import (
    BooleanProperty,
    ColorProperty,
    ListProperty,
    NumericProperty,
    ObjectProperty,
    StringProperty,
)
from kivy.uix.behaviors import ButtonBehavior
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.screenmanager import FadeTransition, ScreenManagerException

from kivymd import uix_path
from kivymd.material_resources import STANDARD_INCREMENT
from kivymd.theming import ThemableBehavior, ThemeManager
from kivymd.uix.anchorlayout import MDAnchorLayout
from kivymd.uix.behaviors import CommonElevationBehavior, DeclarativeBehavior
from kivymd.uix.behaviors.backgroundcolor_behavior import (
    SpecificBackgroundColorBehavior,
)
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.screen import MDScreen
from kivymd.utils.set_bars_colors import set_bars_colors

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


class MDBottomNavigationHeader(ButtonBehavior, MDAnchorLayout):
    """
    Bottom navigation header class.

    For more information, see in the
    :class:`~kivy.uix.behaviors.ButtonBehavior` and
    :class:`~kivymd.uix.anchorlayout.MDAnchorLayout`
    classes documentation.
    """

    panel_color = ColorProperty([1, 1, 1, 0])
    """
    Panel color of bottom navigation in (r, g, b, a) or string format.

    :attr:`panel_color` is an :class:`~kivy.properties.ColorProperty`
    and defaults to `[1, 1, 1, 0]`.
    """

    tab = ObjectProperty()
    """
    :attr:`tab` is an :class:`~MDBottomNavigationItem`
    and defaults to `None`.
    """

    panel = ObjectProperty()
    """
    :attr:`panel` is an :class:`~MDBottomNavigation`
    and defaults to `None`.
    """

    active = BooleanProperty(False)

    text = StringProperty()
    """
    :attr:`text` is an :class:`~MDTab.text`
    and defaults to `''`.
    """

    text_color_normal = ColorProperty([1, 1, 1, 1])
    """
    Text color in (r, g, b, a) or string format of the label when it is not
    selected.

    :attr:`text_color_normal` is an :class:`~kivy.properties.ColorProperty`
    and defaults to `[1, 1, 1, 1]`.
    """

    text_color_active = ColorProperty([1, 1, 1, 1])
    """
    Text color in (r, g, b, a) or string format of the label when it is selected.

    :attr:`text_color_active` is an :class:`~kivy.properties.ColorProperty`
    and defaults to `[1, 1, 1, 1]`.
    """

    selected_color_background = ColorProperty(None)
    """
    The background color in (r, g, b, a) or string format of the highlighted
    item when using Material Design v3.

    .. versionadded:: 1.0.0

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

    opposite_colors = BooleanProperty(True)

    _label = ObjectProperty()
    _label_font_size = NumericProperty("12sp")
    _text_color_normal = ColorProperty([1, 1, 1, 1])
    _text_color_active = ColorProperty([1, 1, 1, 1])
    _selected_region_width = NumericProperty(dp(64))

    def __init__(self, panel, tab):
        self.panel = panel
        self.tab = tab
        super().__init__()
        self._text_color_normal = (
            self.theme_cls.disabled_hint_text_color
            if self.text_color_normal == [1, 1, 1, 1]
            else self.text_color_normal
        )
        self._label = self.ids._label
        self._label_font_size = sp(12)
        self.theme_cls.bind(disabled_hint_text_color=self._update_theme_style)
        self.active = False

    def on_press(self) -> None:
        """Called when clicking on a panel item."""

        if self.theme_cls.material_style == "M2":
            Animation(_label_font_size=sp(14), d=0.1).start(self)
        elif self.theme_cls.material_style == "M3":
            Animation(
                _selected_region_width=dp(64),
                t="in_out_sine",
                d=0,
            ).start(self)
        Animation(
            _text_color_normal=self.theme_cls.primary_color
            if self.text_color_active == [1, 1, 1, 1]
            else self.text_color_active,
            d=0.1,
        ).start(self)

    def _update_theme_style(
        self, instance_theme_manager: ThemeManager, color: list
    ):
        """Called when the application theme style changes (White/Black)."""

        if not self.active:
            self._text_color_normal = (
                color
                if self.text_color_normal == [1, 1, 1, 1]
                else self.text_color_normal
            )


class MDTab(MDScreen):
    """
    A tab is simply a screen with meta information that defines the content
    that goes in the tab header.

    For more information, see in the
    :class:`~kivymd.uix.screen.MDScreen` class documentation.
    """

    __events__ = (
        "on_tab_touch_down",
        "on_tab_touch_move",
        "on_tab_touch_up",
        "on_tab_press",
        "on_tab_release",
    )
    """Events provided."""

    text = StringProperty()
    """
    Tab header text.

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

    icon = StringProperty("checkbox-blank-circle")
    """
    Tab header icon.

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

    badge_icon = StringProperty()
    """
    Tab header badge icon.

    .. versionadded:: 1.0.0

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

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.index = 0
        self.parent_widget = None
        self.register_event_type("on_tab_touch_down")
        self.register_event_type("on_tab_touch_move")
        self.register_event_type("on_tab_touch_up")
        self.register_event_type("on_tab_press")
        self.register_event_type("on_tab_release")

    def on_tab_touch_down(self, *args):
        pass

    def on_tab_touch_move(self, *args):
        pass

    def on_tab_touch_up(self, *args):
        pass

    def on_tab_press(self, *args):
        par = self.parent_widget
        if par.previous_tab is not self:
            if par.previous_tab.index > self.index:
                par.ids.tab_manager.transition.direction = "right"
            elif par.previous_tab.index < self.index:
                par.ids.tab_manager.transition.direction = "left"
            par.ids.tab_manager.current = self.name
            par.previous_tab = self

    def on_tab_release(self, *args):
        pass

    def __repr__(self):
        return f"<MDTab name='{self.name}', text='{self.text}'>"


class MDBottomNavigationItem(MDTab):
    header = ObjectProperty()
    """
    :attr:`header` is an :class:`~MDBottomNavigationHeader`
    and defaults to `None`.
    """

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    def animate_header(
        self, bottom_navigation_object, bottom_navigation_header_object
    ) -> None:
        if bottom_navigation_object.use_text:
            Animation(_label_font_size=sp(12), d=0.1).start(
                bottom_navigation_object.previous_tab.header
            )
        Animation(
            _selected_region_width=0,
            t="in_out_sine",
            d=0,
        ).start(bottom_navigation_header_object)
        Animation(
            _text_color_normal=bottom_navigation_header_object.text_color_normal
            if bottom_navigation_object.previous_tab.header.text_color_normal
            != [1, 1, 1, 1]
            else self.theme_cls.disabled_hint_text_color,
            d=0.1,
        ).start(bottom_navigation_object.previous_tab.header)
        bottom_navigation_object.previous_tab.header.active = False
        self.header.active = True

    def on_tab_press(self, *args) -> None:
        """Called when clicking on a panel item."""

        bottom_navigation_object = self.parent_widget
        bottom_navigation_header_object = (
            bottom_navigation_object.previous_tab.header
        )

        if bottom_navigation_object.previous_tab is not self:
            self.animate_header(
                bottom_navigation_object, bottom_navigation_header_object
            )

        super().on_tab_press(*args)

    def on_disabled(
        self, instance_bottom_navigation_item, disabled_value: bool
    ) -> None:
        self.header.disabled = disabled_value

    def on_leave(self, *args):
        pass


class TabbedPanelBase(
    ThemableBehavior, SpecificBackgroundColorBehavior, BoxLayout
):
    """
    A class that contains all variables a :class:`~kivy.properties.TabPannel`
    must have. It is here so I (zingballyhoo) don't get mad about
    the :class:`~kivy.properties.TabbedPannels` not being DRY.

    For more information, see in the :class:`~kivymd.theming.ThemableBehavior`
    and :class:`~kivymd.uix.behaviors.SpecificBackgroundColorBehavior`
    and :class:`~kivy.uix.boxlayout.BoxLayout` classes documentation.
    """

    current = StringProperty(None)
    """
    Current tab name.

    :attr:`current` is an :class:`~kivy.properties.StringProperty`
    and defaults to `None`.
    """

    previous_tab = ObjectProperty(None, aloownone=True)
    """
    :attr:`previous_tab` is an :class:`~MDTab` and defaults to `None`.
    """

    panel_color = ColorProperty(None)
    """
    Panel color of bottom navigation.

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

    tabs = ListProperty()


class MDBottomNavigation(DeclarativeBehavior, TabbedPanelBase):
    """
    A bottom navigation that is implemented by delegating all items to a
    :class:`~kivy.uix.screenmanager.ScreenManager`.

    For more information, see in the
    :class:`~kivymd.uix.behaviors.DeclarativeBehavior` and
    :class:`~TabbedPanelBase` classes documentation.

    :Events:
        :attr:`on_switch_tabs`
            Called when switching tabs. Returns the object of the tab to be
            opened.

        .. versionadded:: 1.0.0
    """

    transition = ObjectProperty(FadeTransition)
    """
    Transition animation of bottom navigation screen manager.

    .. versionadded:: 1.1.0

    :attr:`transition` is an :class:`~kivy.properties.ObjectProperty`
    and defaults to `FadeTransition`.
    """

    transition_duration = NumericProperty(0.2)
    """
    Duration animation of bottom navigation screen manager.

    .. versionadded:: 1.1.0

    :attr:`transition_duration` is an :class:`~kivy.properties.NumericProperty`
    and defaults to `0.2`.
    """

    text_color_normal = ColorProperty([1, 1, 1, 1])
    """
    Text color of the label when it is not selected.

    .. code-block:: kv

        MDBottomNavigation:
            text_color_normal: 1, 0, 1, 1

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation-text_color_normal.png

    :attr:`text_color_normal` is an :class:`~kivy.properties.ColorProperty`
    and defaults to `[1, 1, 1, 1]`.
    """

    text_color_active = ColorProperty([1, 1, 1, 1])
    """
    Text color of the label when it is selected.

    .. code-block:: kv

        MDBottomNavigation:
            text_color_active: 0, 0, 0, 1

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation-text_color_active.png

    :attr:`text_color_active` is an :class:`~kivy.properties.ColorProperty`
    and defaults to `[1, 1, 1, 1]`.
    """

    use_text = BooleanProperty(True)
    """
    Use text for :class:`~MDBottomNavigationItem` or not.
    If ``True``, the :class:`~MDBottomNavigation` panel height will be reduced
    by the text height.

    .. versionadded:: 1.0.0

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation-use-text.png
        :align: center

    :attr:`use_text` is an :class:`~kivy.properties.BooleanProperty`
    and defaults to `True`.
    """

    selected_color_background = ColorProperty(None)
    """
    The background color of the highlighted item when using Material Design v3.

    .. versionadded:: 1.0.0

    .. code-block:: kv

        MDBottomNavigation:
            selected_color_background: 0, 0, 1, .4

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation=selected-color-background.png

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

    font_name = StringProperty("Roboto")
    """
    Font name of the label.

    .. versionadded:: 1.0.0

    .. code-block:: kv

        MDBottomNavigation:
            font_name: "path/to/font.ttf"

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-navigation-font-name.png

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

    first_widget = ObjectProperty()
    """
    :attr:`first_widget` is an :class:`~MDBottomNavigationItem`
    and defaults to `None`.
    """

    tab_header = ObjectProperty()
    """
    :attr:`tab_header` is an :class:`~MDBottomNavigationHeader`
    and defaults to `None`.
    """

    set_bars_color = BooleanProperty(False)
    """
    If `True` the background color of the navigation bar will be set
    automatically according to the current color of the toolbar.

    .. versionadded:: 1.0.0

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

    widget_index = NumericProperty(0)

    # Text active color if it is selected.
    _active_color = ColorProperty([1, 1, 1, 1])

    def __init__(self, *args, **kwargs):
        self.previous_tab = None
        self.register_event_type("on_switch_tabs")
        super().__init__(*args, **kwargs)
        self.theme_cls.bind(material_style=self.refresh_tabs)
        Window.bind(on_resize=self.on_resize)
        Clock.schedule_once(lambda x: self.on_resize())
        Clock.schedule_once(self.set_status_bar_color)

    def set_status_bar_color(self, interval: Union[int, float]) -> None:
        if self.set_bars_color:
            set_bars_colors(self.panel_color, None, self.theme_cls.theme_style)

    def switch_tab(self, name_tab) -> None:
        """Switching the tab by name."""

        if not self.ids.tab_manager.has_screen(name_tab):
            raise ScreenManagerException(f"No Screen with name '{name_tab}'.")
        self.ids.tab_manager.get_screen(name_tab).dispatch("on_tab_press")
        count_index_screen = [
            self.ids.tab_manager.screens.index(screen)
            for screen in self.ids.tab_manager.screens
            if screen.name == name_tab
        ][0]
        numbers_screens = list(range(len(self.ids.tab_manager.screens)))
        numbers_screens.reverse()
        self.ids.tab_bar.children[
            numbers_screens.index(count_index_screen)
        ].dispatch("on_press")

    def refresh_tabs(self, *args) -> None:
        """Refresh all tabs."""

        if self.ids:
            tab_bar = self.ids.tab_bar
            tab_bar.clear_widgets()
            tab_manager = self.ids.tab_manager
            self._active_color = self.theme_cls.primary_color

            if self.text_color_active != [1, 1, 1, 1]:
                self._active_color = self.text_color_active

            for tab in tab_manager.screens:
                self.tab_header = MDBottomNavigationHeader(tab=tab, panel=self)
                tab.header = self.tab_header
                tab_bar.add_widget(self.tab_header)

                if tab is self.first_widget:
                    self.tab_header._text_color_normal = self._active_color
                    self.tab_header._label_font_size = sp(14)
                    self.tab_header.active = True
                else:
                    self.tab_header.ids._label.font_size = sp(12)
                    self.tab_header._label_font_size = sp(12)

    def on_font_name(self, instance_bottom_navigation, font_name: str) -> None:
        for tab in self.ids.tab_bar.children:
            tab.ids._label.font_name = font_name

    def on_selected_color_background(
        self, instance_bottom_navigation, color: list
    ) -> None:
        def on_selected_color_background(*args):
            for tab in self.ids.tab_bar.children:
                tab.selected_color_background = color

        Clock.schedule_once(on_selected_color_background)

    def on_use_text(
        self, instance_bottom_navigation, use_text_value: bool
    ) -> None:
        if not use_text_value:
            for instance_bottom_navigation_header in self.ids.tab_bar.children:
                instance_bottom_navigation_header.ids.item_container.remove_widget(
                    instance_bottom_navigation_header.ids._label
                )
            if self.theme_cls.material_style == "M2":
                height = dp(42)
            else:
                height = dp(80)
            self.height = height
            self.ids.bottom_panel.height = height
            self.ids.tab_bar.height = height
        else:
            if self.theme_cls.material_style == "M2":
                height = STANDARD_INCREMENT
            else:
                height = dp(80)
            self.height = height
            self.ids.bottom_panel.height = height
            self.ids.tab_bar.height = height

    def on_text_color_normal(
        self, instance_bottom_navigation, color: list
    ) -> None:
        MDBottomNavigationHeader.text_color_normal = color
        for tab in self.ids.tab_bar.children:
            if not tab.active:
                tab._text_color_normal = color

    def on_text_color_active(
        self, instance_bottom_navigation, color: list
    ) -> None:
        def on_text_color_active(*args):
            MDBottomNavigationHeader.text_color_active = color
            self.text_color_active = color
            for tab in self.ids.tab_bar.children:
                tab.text_color_active = color
                if tab.active:
                    tab._text_color_normal = color

        Clock.schedule_once(on_text_color_active)

    def on_switch_tabs(self, bottom_navigation_item, name_tab: str) -> None:
        """
        Called when switching tabs. Returns the object of the tab to be opened.
        """

    def on_size(self, *args) -> None:
        self.on_resize()

    def on_resize(
        self,
        instance: Union[WindowSDL, None] = None,
        width: Union[int, None] = None,
        do_again: bool = True,
    ) -> None:
        """Called when the application window is resized."""

        full_width = 0
        for tab in self.ids.tab_manager.screens:
            full_width += tab.header.width
            tab.header.text_color_normal = self.text_color_normal
        self.ids.tab_bar.width = full_width
        if do_again:
            Clock.schedule_once(lambda x: self.on_resize(do_again=False), 0.1)

    def add_widget(self, widget, **kwargs):
        if isinstance(widget, MDBottomNavigationItem):
            self.widget_index += 1
            widget.index = self.widget_index
            widget.parent_widget = self
            self.ids.tab_manager.add_widget(widget)
            if self.widget_index == 1:
                self.previous_tab = widget
                self.first_widget = widget
            self.refresh_tabs()
        else:
            super().add_widget(widget)

    def remove_widget(self, widget):
        if isinstance(widget, MDBottomNavigationItem):
            self.ids.tab_manager.remove_widget(widget)
            self.refresh_tabs()
        else:
            super().remove_widget(widget)

    def _get_switchig_tab(self, name_tab: str) -> MDBottomNavigationItem:
        bottom_navigation_item = None
        for bottom_navigation_header_instance in self.ids.tab_bar.children:
            if bottom_navigation_header_instance.tab.name == name_tab:
                bottom_navigation_item = bottom_navigation_header_instance.tab
                break
        return bottom_navigation_item


class MDBottomNavigationBar(CommonElevationBehavior, MDFloatLayout):
    pass