Sideband/sbapp/kivymd/uix/responsivelayout.py

190 lines
5.3 KiB
Python

"""
Components/ResponsiveLayout
===========================
.. versionadded:: 1.0.0
.. rubric:: Responsive design is a graphic user interface (GUI) design
approach used to create content that adjusts smoothly to various screen
sizes.
.. raw:: html
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; height: auto;">
<iframe
src="https://www.youtube.com/embed/HMK1UZbSyeo"
frameborder="0"
allowfullscreen
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;">
</iframe>
</div>
The :class:`~MDResponsiveLayout` class does not reorganize your UI. Its task
is to track the size of the application screen and, depending on this size,
the :class:`~MDResponsiveLayout` class selects which UI layout should be
displayed at the moment: mobile, tablet or desktop. Therefore, if you want to
have a responsive view some kind of layout in your application, you should
have three KV files with UI markup for three platforms.
You need to set three parameters for the :class:`~MDResponsiveLayout` class
:attr:`~MDResponsiveLayout.mobile_view`,
:attr:`~MDResponsiveLayout.tablet_view` and
:attr:`~MDResponsiveLayout.desktop_view`. These should be Kivy or KivyMD
widgets.
Usage responsive
----------------
.. code-block:: python
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.uix.responsivelayout import MDResponsiveLayout
from kivymd.uix.screen import MDScreen
KV = '''
<CommonComponentLabel>
halign: "center"
<MobileView>
CommonComponentLabel:
text: "Mobile"
<TabletView>
CommonComponentLabel:
text: "Table"
<DesktopView>
CommonComponentLabel:
text: "Desktop"
ResponsiveView:
'''
class CommonComponentLabel(MDLabel):
pass
class MobileView(MDScreen):
pass
class TabletView(MDScreen):
pass
class DesktopView(MDScreen):
pass
class ResponsiveView(MDResponsiveLayout, MDScreen):
def __init__(self, **kw):
super().__init__(**kw)
self.mobile_view = MobileView()
self.tablet_view = TabletView()
self.desktop_view = DesktopView()
class Test(MDApp):
def build(self):
return Builder.load_string(KV)
Test().run()
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/responsive-usage.gif
:align: center
.. note:: Use common components for platform layouts (mobile, tablet, desktop views).
As shown in the example above, such a common component is the
`CommonComponentLabel` widget.
Perhaps you expected more from the :class:`~MDResponsiveLayout` widget, but
even `Flutter` uses a similar approach to creating a responsive UI.
You can also use the `commands <https://kivymd.readthedocs.io/en/latest/api/kivymd/tools/patterns/create_project/#create-project-with-responsive-view>`_
provided to you by the developer tools to create a project with an responsive
design.
"""
from kivy.event import EventDispatcher
from kivy.properties import ObjectProperty
from kivymd.uix.controllers import WindowController
class MDResponsiveLayout(EventDispatcher, WindowController):
"""
:Events:
:attr:`on_change_screen_type`
Called when the screen type changes.
"""
mobile_view = ObjectProperty()
"""
Mobile view. Must be a Kivy or KivyMD widget.
:attr:`mobile_view` is an :class:`~kivy.properties.ObjectProperty`
and defaults to `None`.
"""
tablet_view = ObjectProperty()
"""
Tablet view. Must be a Kivy or KivyMD widget.
:attr:`tablet_view` is an :class:`~kivy.properties.ObjectProperty`
and defaults to `None`.
"""
desktop_view = ObjectProperty()
"""
Desktop view. Must be a Kivy or KivyMD widget.
:attr:`desktop_view` is an :class:`~kivy.properties.ObjectProperty`
and defaults to `None`.
"""
_current_device_type = ""
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.register_event_type("on_change_screen_type")
def on_change_screen_type(self, *args):
"""Called when the screen type changes."""
def on_size(self, *args) -> None:
"""Called when the application screen size changes."""
super().on_size(*args)
self.set_screen()
if self._current_device_type != self.real_device_type:
self._current_device_type = self.real_device_type
def set_screen(self) -> None:
"""
Sets the screen according to the type of application screen size:
mobile/tablet or desktop view.
"""
if self.real_device_type != self._current_device_type:
self.clear_widgets()
if self.mobile_view and self.tablet_view and self.desktop_view:
if self.real_device_type == "mobile":
self.add_widget(self.mobile_view)
elif self.real_device_type == "tablet":
self.add_widget(self.tablet_view)
elif self.real_device_type == "desktop":
self.add_widget(self.desktop_view)
self.dispatch("on_change_screen_type", self.real_device_type)