kvex.widgets.layouts

  1"""Layout widgets."""
  2
  3from typing import Optional
  4import functools
  5from .. import kivy as kv
  6from .. import assets
  7from .. import util
  8from ..behaviors import XThemed
  9from .widget import XWidget
 10
 11
 12class XBox(XWidget, kv.BoxLayout):
 13    """BoyLayout."""
 14
 15    pass
 16
 17
 18class XZBox(XWidget, kv.GridLayout):
 19    """Behaves like a Box where widgets are drawn in reverse order."""
 20
 21    def __init__(
 22        self,
 23        *,
 24        orientation: str = "horizontal",
 25        **kwargs,
 26    ):
 27        """Initialize the class."""
 28        if orientation == "horizontal":
 29            kwargs["orientation"] = "rl-tb"
 30            kwargs["rows"] = 1
 31        elif orientation == "vertical":
 32            kwargs["orientation"] = "lr-bt"
 33            kwargs["cols"] = 1
 34        else:
 35            raise ValueError('orientation must be "horizontal" or "vertical"')
 36        super().__init__(**kwargs)
 37
 38    def add_widget(self, *args, **kwargs):
 39        """Overrides base method to insert correctly."""
 40        kwargs["insert_last"] = True
 41        super().add_widget(*args, **kwargs)
 42
 43
 44class XDBox(XWidget, kv.GridLayout):
 45    """Behaves like a Box that will dynamically resize based on children's height."""
 46
 47    def __init__(self, cols: int = 1, **kwargs):
 48        """Initialize the class."""
 49        super().__init__(cols=cols, **kwargs)
 50        self.bind(children=self._resize)
 51        trigger = util.create_trigger(self._resize)
 52        self._snooze_trigger = lambda *a: util.snooze_trigger(trigger)
 53
 54    def add_widget(self, w, *args, **kwargs):
 55        """Overrides base method in order to bind to size changes."""
 56        w.bind(size=self._resize)
 57        super().add_widget(w, *args, **kwargs)
 58        self._snooze_trigger()
 59
 60    def _resize(self, *a):
 61        self.set_size(hx=1, y=sum([util.sp2pixels(c.height) for c in self.children]))
 62
 63
 64class XGrid(XWidget, kv.GridLayout):
 65    """GridLayout."""
 66
 67    pass
 68
 69
 70class XStack(XWidget, kv.StackLayout):
 71    """StackLayout."""
 72
 73    pass
 74
 75
 76class XRelative(XWidget, kv.RelativeLayout):
 77    """RelativeLayout."""
 78
 79    pass
 80
 81
 82class XAnchor(XWidget, kv.AnchorLayout):
 83    """AnchorLayout."""
 84
 85    @classmethod
 86    def wrap(cls, widget: kv.Widget, /, **kwargs) -> "XAnchor":
 87        """Create `XAnchor` with child widget.
 88
 89        Args:
 90            widget: Widget to wrap.
 91            kwargs: Keyword arguments for the XAnchor.
 92        """
 93        anchor = cls(**kwargs)
 94        anchor.add_widget(widget)
 95        return anchor
 96
 97
 98class XFrame(XThemed, XAnchor):
 99    """Themed `XAnchor` with a background."""
100
101    BG = str(assets.get_image("xframe_bg"))
102
103    def on_subtheme(self, subtheme):
104        """Apply background color."""
105        self.make_bg(subtheme.bg, source=self.BG)
106
107
108wrap = XAnchor.wrap
109pwrap = functools.partial(XAnchor.wrap, padding="10sp")
110"""Like `wrap` but with '10sp' padding."""
111fwrap = XFrame.wrap
112"""Like `wrap` but with `XFrame`."""
113fpwrap = functools.partial(XFrame.wrap, padding="10sp")
114"""Like `fwrap` but with '10sp' padding."""
115
116
117class XAnchorDelayed(XAnchor):
118    """An XAnchor that delays layout events.
119
120    Useful for preventing window drag-resize from creating too many events.
121    """
122
123    layout_event_delay = kv.NumericProperty(0.1)
124    """Delay for layout events."""
125    _delayed_layout_event = None
126
127    def do_layout(self, *args, **kwargs):
128        """Override base method to delay layout events."""
129        if self._delayed_layout_event:
130            self._delayed_layout_event.cancel()
131        _real_do_layout = super().do_layout
132        self._delayed_layout_event = util.schedule_once(
133            lambda dt: _real_do_layout(*args, **kwargs),
134            self.layout_event_delay,
135        )
136
137
138class XCurtain(XAnchor):
139    """AnchorLayout that can show or hide it's content."""
140
141    content = kv.ObjectProperty(None, allownone=True)
142    """Widget to show and hide."""
143    showing = kv.BooleanProperty(True)
144    """If the content widget is showing."""
145    dynamic = kv.BooleanProperty(False)
146    """If the the curtain should resize based on content size and visibility."""
147
148    def __init__(self, *args, **kwargs):
149        """Initialize the class."""
150        super().__init__(*args, **kwargs)
151        self.bind(
152            content=self._on_properties,
153            showing=self._on_properties,
154            dynamic=self._on_properties,
155        )
156        self._on_properties()
157
158    def _on_properties(self, *args):
159        if self.showing and self.content:
160            if self.content.parent:
161                self.clear_widgets()
162            if not self.content.parent:
163                self.add_widget(self.content)
164            if self.dynamic:
165                self.set_size(*self.content.size)
166        else:
167            self.clear_widgets()
168            if self.dynamic:
169                self.set_size(0, 0)
170
171    def show(self, *args, **kwargs):
172        """Show the content widget."""
173        self.showing = True
174
175    def hide(self, *args, **kwargs):
176        """Hide the content widget."""
177        self.showing = False
178
179    def toggle(self, *args, set_as: Optional[bool] = None, **kwargs):
180        """Toggle showing the content widget."""
181        if set_as is None:
182            set_as = not self.showing
183        self.showing = set_as
184
185
186__all__ = (
187    "XBox",
188    "XZBox",
189    "XDBox",
190    "XGrid",
191    "XRelative",
192    "XStack",
193    "XAnchor",
194    "XFrame",
195    "wrap",
196    "pwrap",
197    "fwrap",
198    "fpwrap",
199    "XAnchorDelayed",
200    "XCurtain",
201)