kvex.widgets.widget

 1"""Home of `XWidget`."""
 2
 3from typing import Optional
 4from .. import kivy as kv
 5from ..util import sp2pixels
 6from ..colors import XColor
 7
 8
 9class XWidget:
10    """A mixin for kivy widgets with useful methods."""
11
12    def add_widgets(
13        self,
14        *children: tuple[kv.Widget, ...],
15        insert_last: bool = False,
16        **kwargs,
17    ):
18        """Add multiple widgets."""
19        if not children:
20            raise ValueError("Must supply children to add.")
21        for child in children:
22            if insert_last:
23                kwargs["index"] = len(self.children)
24            self.add_widget(child, **kwargs)
25
26    def set_size(
27        self,
28        x: Optional[float | str] = None,
29        y: Optional[float | str] = None,
30        hx: float = 1,
31        hy: float = 1,
32    ):
33        """Set the size of the widget.
34
35        Designed to produce intuitive results when using size or hint without
36        specifying the other.
37
38        Args:
39            x: Width in pixels.
40            y: Height in pixels.
41            hx: Width hint.
42            hy: Height hint.
43        """
44        hx = hx if x is None else None
45        hy = hy if y is None else None
46        x = self.width if x is None else x
47        y = self.height if y is None else y
48        self.size_hint = hx, hy
49        self.size = x, y
50
51    def set_focus(self, *args):
52        """Set the focus on this widget."""
53        self.focus = True
54
55    def make_bg(self, color: Optional[XColor] = None, source: Optional[str] = None):
56        """Add or update a background image using self.canvas.before."""
57        if hasattr(self, "_kvex_bg") and hasattr(self, "_kvex_bg_color"):
58            if color is not None:
59                self._kvex_bg_color.rgba = color.rgba
60            if source is not None:
61                self._kvex_bg.source = str(source)
62        else:
63            if color is None:
64                color = XColor(1, 1, 1, 1)
65            with self.canvas.before:
66                self._kvex_bg_color = kv.Color(*color.rgba)
67                self._kvex_bg = kv.Rectangle(
68                    size=self.size,
69                    pos=self.pos,
70                    source=str(source),
71                )
72            self.bind(pos=self._update_kvex_bg_pos, size=self._update_kvex_bg_size)
73
74    def _update_kvex_bg_pos(self, w, pos):
75        self._kvex_bg.pos = pos
76
77    def _update_kvex_bg_size(self, w, size):
78        self._kvex_bg.size = sp2pixels(size)
79
80    @property
81    def app(self):
82        """Get the running app."""
83        return kv.App.get_running_app()
84
85
86__all__ = (
87    "XWidget",
88)