Sideband/sbapp/kivymd/uix/backdrop/backdrop.py

"""
Components/Backdrop
===================

.. seealso::

    `Material Design spec, Backdrop <https://material.io/components/backdrop>`_

.. rubric:: Skeleton layout for using :class:`~MDBackdrop`:

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

Usage
-----

.. code-block:: kv

    <Root>

        MDBackdrop:

            MDBackdropBackLayer:

                ContentForBackdropBackLayer:

            MDBackdropFrontLayer:

                 ContentForBackdropFrontLayer:

Example
-------

.. tabs::

    .. tab:: Declarative KV styles

        .. code-block:: python

            from kivy.lang import Builder

            from kivymd.uix.screen import MDScreen
            from kivymd.app import MDApp

            # Your layouts.
            Builder.load_string(
                '''
            #:import os os
            #:import Window kivy.core.window.Window
            #:import IconLeftWidget kivymd.uix.list.IconLeftWidget
            #:import images_path kivymd.images_path


            <ItemBackdropFrontLayer@TwoLineAvatarListItem>
                icon: "android"

                IconLeftWidget:
                    icon: root.icon


            <MyBackdropFrontLayer@ItemBackdropFrontLayer>
                backdrop: None
                text: "Lower the front layer"
                secondary_text: " by 50 %"
                icon: "transfer-down"
                on_press: root.backdrop.open(-Window.height / 2)
                pos_hint: {"top": 1}
                _no_ripple_effect: True


            <MyBackdropBackLayer@Image>
                size_hint: .8, .8
                source: os.path.join(images_path, "logo", "kivymd-icon-512.png")
                pos_hint: {"center_x": .5, "center_y": .6}
            '''
            )

            # Usage example of MDBackdrop.
            Builder.load_string(
                '''
            <ExampleBackdrop>

                MDBackdrop:
                    id: backdrop
                    left_action_items: [['menu', lambda x: self.open()]]
                    title: "Example Backdrop"
                    radius_left: "25dp"
                    radius_right: "0dp"
                    header_text: "Menu:"

                    MDBackdropBackLayer:
                        MyBackdropBackLayer:
                            id: backlayer

                    MDBackdropFrontLayer:
                        MyBackdropFrontLayer:
                            backdrop: backdrop
            '''
            )


            class ExampleBackdrop(MDScreen):
                pass


            class Example(MDApp):
                def build(self):
                    self.theme_cls.theme_style = "Dark"
                    self.theme_cls.primary_palette = "Orange"
                    return ExampleBackdrop()


            Example().run()

    .. tab:: Declarative python styles

        .. code-block:: python

            import os

            from kivy.core.window import Window
            from kivy.uix.image import Image

            from kivymd import images_path
            from kivymd.uix.backdrop import MDBackdrop
            from kivymd.uix.backdrop.backdrop import (
                MDBackdropBackLayer, MDBackdropFrontLayer
            )
            from kivymd.uix.list import TwoLineAvatarListItem, IconLeftWidget
            from kivymd.uix.screen import MDScreen
            from kivymd.app import MDApp


            class Example(MDApp):
                def build(self):
                    self.theme_cls.theme_style = "Dark"
                    self.theme_cls.primary_palette = "Orange"

                    return (
                        MDScreen(
                            MDBackdrop(
                                MDBackdropBackLayer(
                                    Image(
                                        size_hint=(0.8, 0.8),
                                        source=os.path.join(images_path, "logo", "kivymd-icon-512.png"),
                                        pos_hint={"center_x": 0.5, "center_y": 0.6},
                                    )
                                ),
                                MDBackdropFrontLayer(
                                    TwoLineAvatarListItem(
                                        IconLeftWidget(icon="transfer-down"),
                                        text="Lower the front layer",
                                        secondary_text=" by 50 %",
                                        on_press=self.backdrop_open_by_50_percent,
                                        pos_hint={"top": 1},
                                        _no_ripple_effect=True,
                                    ),
                                ),
                                id="backdrop",
                                title="Example Backdrop",
                                radius_left="25dp",
                                radius_right="0dp",
                                header_text="Menu:",
                            )
                        )
                    )

                def backdrop_open_by_50_percent(self, *args):
                    self.root.ids.backdrop.open(-Window.height / 2)


            Example().run()

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

.. Note:: `See full example <https://github.com/kivymd/KivyMD/wiki/Components-Backdrop>`_
"""

__all__ = (
    "MDBackdropToolbar",
    "MDBackdropFrontLayer",
    "MDBackdropBackLayer",
    "MDBackdrop",
)

import os
from typing import Union

from kivy.animation import Animation
from kivy.clock import Clock
from kivy.lang import Builder
from kivy.properties import (
    BooleanProperty,
    ColorProperty,
    ListProperty,
    NumericProperty,
    OptionProperty,
    StringProperty,
)
from kivy.uix.boxlayout import BoxLayout

from kivymd import uix_path
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.card import MDCard
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.toolbar.toolbar import ActionTopAppBarButton, MDTopAppBar

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


class MDBackdrop(MDFloatLayout):
    """
    For more information, see in the
    :class:`~kivymd.uix.floatlayout.MDFloatLayout` class documentation.

    :Events:
        :attr:`on_open`
            When the front layer drops.
        :attr:`on_close`
            When the front layer rises.
    """

    anchor_title = OptionProperty("left", options=["left", "center", "right"])
    """
    Position toolbar title. Only used with `material_style = 'M3'`
    Available options are: `'left'`, `'center'`, `'right'`.

    .. versionadded:: 1.0.0

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/backdrop-anchor-title.png
        :align: center

    :attr:`anchor_title` is an :class:`~kivy.properties.OptionProperty`
    and defaults to `'left'`.
    """

    padding = ListProperty([0, 0, 0, 0])
    """
    Padding for contents of the front layer.

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

    :attr:`padding` is an :class:`~kivy.properties.ListProperty`
    and defaults to `[0, 0, 0, 0]`.
    """

    left_action_items = ListProperty()
    """
    The icons and methods left of the :class:`kivymd.uix.toolbar.MDTopAppBar`
    in back layer. For more information, see the
    :class:`kivymd.uix.toolbar.MDTopAppBar` module
    and :attr:`left_action_items` parameter.

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

    right_action_items = ListProperty()
    """
    Works the same way as :attr:`left_action_items`.

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

    title = StringProperty()
    """
    See the :class:`kivymd.uix.toolbar.MDTopAppBar.title` parameter.

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

    back_layer_color = ColorProperty(None)
    """
    Background color of back layer in (r, g, b, a) or string format.

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/backdrop-back-layer-color.png
        :align: center

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

    front_layer_color = ColorProperty(None)
    """
    Background color of front layer in (r, g, b, a) or string format.

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/backdrop-front-layer-color.png
        :align: center

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

    radius_left = NumericProperty("16dp")
    """
    The value of the rounding radius of the upper left corner
    of the front layer.

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/backdrop-radius-left.png
        :align: center

    :attr:`radius_left` is an :class:`~kivy.properties.NumericProperty`
    and defaults to `16dp`.
    """

    radius_right = NumericProperty("16dp")
    """
    The value of the rounding radius of the upper right corner
    of the front layer.

    :attr:`radius_right` is an :class:`~kivy.properties.NumericProperty`
    and defaults to `16dp`.
    """

    header = BooleanProperty(True)
    """
    Whether to use a header above the contents of the front layer.

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

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

    header_text = StringProperty("Header")
    """
    Text of header.

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/backdrop-header-text.png
        :align: center

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

    close_icon = StringProperty("close")
    """
    The name of the icon that will be installed on the toolbar
    on the left when opening the front layer.

    .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/backdrop-close-icon.png
        :align: center

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

    opening_time = NumericProperty(0.2)
    """
    The time taken for the panel to slide to the :attr:`state` `'open'`.

    .. versionadded:: 1.0.0

    :attr:`opening_time` is a :class:`~kivy.properties.NumericProperty`
    and defaults to `0.2`.
    """

    opening_transition = StringProperty("out_quad")
    """
    The name of the animation transition type to use when animating to
    the :attr:`state` `'open'`.

    .. versionadded:: 1.0.0

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

    closing_time = NumericProperty(0.2)
    """
    The time taken for the panel to slide to the :attr:`state` `'close'`.

    .. versionadded:: 1.0.0

    :attr:`closing_time` is a :class:`~kivy.properties.NumericProperty`
    and defaults to `0.2`.
    """

    closing_transition = StringProperty("out_quad")
    """
    The name of the animation transition type to use when animating to
    the :attr:`state` 'close'.

    .. versionadded:: 1.0.0

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

    _open_icon = ""
    _front_layer_open = False

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.register_event_type("on_open")
        self.register_event_type("on_close")
        Clock.schedule_once(
            lambda x: self.on_left_action_items(self, self.left_action_items)
        )

    def on_open(self) -> None:
        """When the front layer drops."""

    def on_close(self) -> None:
        """When the front layer rises."""

    def on_left_action_items(self, instance_backdrop, menu: list) -> None:
        if menu:
            self.left_action_items = [menu[0]]
        else:
            self.left_action_items = [["menu", lambda x: self.open()]]
        self._open_icon = self.left_action_items[0][0]

    def on_header(self, instance_backdrop, value: bool) -> None:
        def on_header(*args):
            if not value:
                self.ids._front_layer.remove_widget(self.ids.header_button)

        Clock.schedule_once(on_header)

    def open(self, open_up_to: int = 0) -> None:
        """
        Opens the front layer.

        :open_up_to:
            the height to which the front screen will be lowered;
            if equal to zero - falls to the bottom of the screen;
        """

        self.animate_opacity_icon()
        if self._front_layer_open:
            self.close()
            return

        if open_up_to:
            if open_up_to < (
                self.ids.header_button.height - self.ids._front_layer.height
            ):
                y = self.ids.header_button.height - self.ids._front_layer.height
            elif open_up_to > 0:
                y = 0
            else:
                y = open_up_to
        else:
            y = self.ids.header_button.height - self.ids._front_layer.height

        Animation(y=y, d=self.opening_time, t=self.opening_transition).start(
            self.ids._front_layer
        )
        self._front_layer_open = True
        self.dispatch("on_open")

    def close(self) -> None:
        """Opens the front layer."""

        Animation(y=0, d=self.closing_time, t=self.closing_transition).start(
            self.ids._front_layer
        )
        self._front_layer_open = False
        self.dispatch("on_close")

    def animate_opacity_icon(
        self,
        instance_icon_menu: Union[ActionTopAppBarButton, None] = None,
        opacity_value: int = 0,
        call_set_new_icon: bool = True,
    ) -> None:
        """Starts the opacity animation of the icon."""

        if not instance_icon_menu:
            instance_icon_menu = self.ids.toolbar.ids.left_actions.children[0]
        anim = Animation(
            opacity=opacity_value,
            d=self.opening_time,
            t=self.opening_transition,
        )
        if call_set_new_icon:
            anim.bind(on_complete=self.set_new_icon)
        anim.start(instance_icon_menu)

    def set_new_icon(
        self,
        instance_animation: Animation,
        instance_icon_menu: ActionTopAppBarButton,
    ) -> None:
        """
        Sets the icon of the button depending on the state of the backdrop.
        """

        instance_icon_menu.icon = (
            self.close_icon
            if instance_icon_menu.icon == self._open_icon
            else self._open_icon
        )
        self.animate_opacity_icon(instance_icon_menu, 1, False)

    def add_widget(self, widget, index=0, canvas=None):
        if widget.__class__ in (MDBackdropToolbar, _BackLayer, _FrontLayer):
            return super().add_widget(widget)
        else:
            if widget.__class__ is MDBackdropBackLayer:
                self.ids.back_layer.add_widget(widget)
            elif widget.__class__ is MDBackdropFrontLayer:
                self.ids.front_layer.add_widget(widget)


class MDBackdropToolbar(MDTopAppBar):
    """
    Implements a toolbar for back content.

    For more information, see in the
    :class:`~kivymd.uix.toolbar.toolbar.MDTopAppBar` classes documentation.
    """


class MDBackdropFrontLayer(MDBoxLayout):
    """
    Container for front content.

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


class MDBackdropBackLayer(MDBoxLayout):
    """
    Container for back content.

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


class _BackLayer(BoxLayout):
    pass


class _FrontLayer(MDCard):
    pass