nativelayout 1.2.0__py3-none-any.whl

nativelayout/core/tree.py

@@ -0,0 +1,406 @@
+"""Native tree and style (port of NativeTree.kt).
+
+Colors: unsigned ARGB integers (0xAARRGGBB). 0 = transparent.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+
+@dataclass(frozen=True)
+class Length:
+    value: float
+    scalable: bool = False
+
+    def to_pixels(self, density: float, font_scale: float) -> float:
+        if self.scalable:
+            return self.value * 16.0 * density * font_scale
+        return self.value * density
+
+    @staticmethod
+    def rem(value: float) -> "Length":
+        return Length(value, True)
+
+    @staticmethod
+    def px(value: float) -> "Length":
+        return Length(value, False)
+
+
+Length.ZERO = Length(0.0)
+
+
+@dataclass(frozen=True)
+class Dim:
+    length: Length
+
+
+@dataclass(frozen=True)
+class Percent:
+    value: float
+
+
+class _Auto:
+    _inst = None
+
+    def __new__(cls):
+        if cls._inst is None:
+            cls._inst = super().__new__(cls)
+        return cls._inst
+
+    def __repr__(self):
+        return "Auto"
+
+
+AUTO = _Auto()
+Size = Dim | Percent | _Auto
+
+
+class Direction(Enum):
+    COLUMN = auto()
+    ROW = auto()
+
+
+class Justify(Enum):
+    START = auto()
+    CENTER = auto()
+    END = auto()
+    BETWEEN = auto()
+    AROUND = auto()
+    EVENLY = auto()
+
+
+class Align(Enum):
+    START = auto()
+    CENTER = auto()
+    END = auto()
+    STRETCH = auto()
+
+
+class Dock(Enum):
+    """Where a <footer> sits: BOTTOM (the default) takes its space, the others float over the screen."""
+    BOTTOM = auto()
+    TOP = auto()
+    LEFT = auto()
+    RIGHT = auto()
+    CENTER = auto()
+
+
+class Position(Enum):
+    """`position`: STATIC stays in the flow of its parent; ABSOLUTE leaves it and is placed by top, right, bottom, left."""
+    STATIC = auto()
+    ABSOLUTE = auto()
+
+
+class ImageFit(Enum):
+    """How an image fills its box: COVER fills and crops, CONTAIN fits whole, FILL stretches."""
+    COVER = auto()
+    CONTAIN = auto()
+    FILL = auto()
+
+
+class ImagePos(Enum):
+    """Which part of a cover or contain image stays in view, or the side where it sits."""
+    CENTER = auto()
+    TOP = auto()
+    BOTTOM = auto()
+    LEFT = auto()
+    RIGHT = auto()
+
+
+class TextAlign(Enum):
+    START = auto()
+    CENTER = auto()
+    END = auto()
+
+
+class FieldType(Enum):
+    TEXT = auto()
+    PASSWORD = auto()
+    NUMBER = auto()
+    AREA = auto()
+
+
+class TextTransform(Enum):
+    NONE = auto()
+    UPPERCASE = auto()
+    LOWERCASE = auto()
+    CAPITALIZE = auto()
+
+
+class FontFamily(Enum):
+    DEFAULT = auto()
+    SANS = auto()
+    SERIF = auto()
+    MONOSPACE = auto()
+
+
+class AnimKind(Enum):
+    NONE = auto()
+    FADE = auto()
+    SLIDE_UP = auto()
+    SLIDE_LEFT = auto()
+
+
+@dataclass(frozen=True)
+class Sides:
+    top: Length = Length.ZERO
+    right: Length = Length.ZERO
+    bottom: Length = Length.ZERO
+    left: Length = Length.ZERO
+
+
+@dataclass(frozen=True)
+class Corners:
+    """CSS order: top-left, top-right, bottom-right, bottom-left."""
+    top_left: Length = Length.ZERO
+    top_right: Length = Length.ZERO
+    bottom_right: Length = Length.ZERO
+    bottom_left: Length = Length.ZERO
+
+
+class Colors:
+    BLACK = 0xFF000000
+    WHITE = 0xFFFFFFFF
+    BUTTON_GRAY = 0xFFE0E0E0
+    BORDER_GRAY = 0xFF767676
+
+
+@dataclass(frozen=True)
+class LineHeightMultiple:
+    value: float
+
+
+@dataclass(frozen=True)
+class LineHeightFixed:
+    length: Length
+
+
+LineHeight = LineHeightMultiple | LineHeightFixed
+
+
+@dataclass(frozen=True)
+class Gradient:
+    """angle in CSS degrees (0 = to top, 90 = to right, 180 = to bottom)."""
+    angle: int
+    colors: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class Animation:
+    kind: AnimKind
+    duration_ms: int = 200
+
+
+class DefaultAnimations:
+    SCREEN = Animation(AnimKind.FADE, 220)
+    LAYER = Animation(AnimKind.FADE, 160)
+
+
+@dataclass(frozen=True)
+class StateStyle:
+    background_color: int | None = None
+    text_color: int | None = None
+    border_color: int | None = None
+    opacity: float | None = None
+
+
+@dataclass(frozen=True)
+class StateStyles:
+    pressed: StateStyle | None = None
+    disabled: StateStyle | None = None
+    focused: StateStyle | None = None
+
+
+@dataclass(frozen=True)
+class NativeStyle:
+    text_color: int = Colors.BLACK
+    background_color: int = 0
+    font_size: Length = field(default_factory=lambda: Length.rem(1.0))
+    bold: bool = False
+    text_align: TextAlign = TextAlign.START
+    width: Size = AUTO
+    height: Size = AUTO
+    padding: Sides = field(default_factory=Sides)
+    margin: Sides = field(default_factory=Sides)
+    border_radius: Length = Length.ZERO
+    corners: Corners | None = None
+    border_width: Length = Length.ZERO
+    border_color: int = Colors.BLACK
+    direction: Direction = Direction.COLUMN
+    justify: Justify = Justify.START
+    align_items: Align = Align.STRETCH
+    gap: Length = Length.ZERO
+    flex: float = 0.0
+    opacity: float = 1.0
+    italic: bool = False
+    underline: bool = False
+    strike: bool = False
+    letter_spacing: Length = Length.ZERO
+    line_height: LineHeight | None = None
+    text_transform: TextTransform = TextTransform.NONE
+    font_family: FontFamily = FontFamily.DEFAULT
+    min_width: Length | None = None
+    max_width: Length | None = None
+    min_height: Length | None = None
+    max_height: Length | None = None
+    overflow_hidden: bool = False
+    align_self: Align | None = None
+    dock: Dock | None = None
+    position: Position = Position.STATIC
+    top: Length | None = None
+    right: Length | None = None
+    bottom: Length | None = None
+    left: Length | None = None
+    z_index: int = 0
+    # name of a background image, resolved by the host like the source of an <img>
+    background_image: str | None = None
+    background_size: ImageFit = ImageFit.COVER
+    background_position: ImagePos = ImagePos.CENTER
+    object_fit: ImageFit = ImageFit.CONTAIN
+    wrap: bool = False
+    elevation: Length = Length.ZERO
+    gradient: Gradient | None = None
+    animation: Animation | None = None
+    states: StateStyles | None = None
+
+
+@dataclass(frozen=True)
+class Span:
+    text: str
+    bold: bool
+    color: int
+    size: Length
+    italic: bool = False
+    underline: bool = False
+    strike: bool = False
+
+
+@dataclass(eq=False, kw_only=True)
+class Native:
+    id: str | None
+    classes: list[str]
+    style: NativeStyle
+    line: int
+    key: str = ""
+    key_hint: str | None = None
+    scope: str | None = None
+
+
+@dataclass(eq=False, kw_only=True)
+class NativeBox(Native):
+    children: list[Native]
+    virtual: bool = False
+    overlay: bool = False   # <dialog>
+    header: bool = False    # <header>
+    footer: bool = False    # <footer>
+    # True when a child is `position: absolute`: the host gives the box a frame for them
+    has_absolute: bool = False
+
+
+@dataclass(eq=False, kw_only=True)
+class NativeText(Native):
+    spans: list[Span]
+
+    @property
+    def plain_text(self) -> str:
+        return "".join(s.text for s in self.spans)
+
+
+@dataclass(eq=False, kw_only=True)
+class NativeButton(Native):
+    label: str
+    disabled: bool
+
+
+@dataclass(eq=False, kw_only=True)
+class NativeField(Native):
+    type: FieldType
+    hint: str
+    value: str
+    disabled: bool
+    read_only: bool
+    rows: int
+
+
+@dataclass(eq=False, kw_only=True)
+class NativeCheckbox(Native):
+    checked: bool
+    disabled: bool
+
+
+@dataclass(eq=False, kw_only=True)
+class NativeImage(Native):
+    source: str
+    description: str
+
+
+@dataclass(eq=False, kw_only=True)
+class NativeItem(Native):
+    marker: str
+    children: list[Native]
+
+
+@dataclass(eq=False, kw_only=True)
+class NativeList(Native):
+    items: list[NativeItem]
+
+
+def native_children(n: Native) -> list[Native]:
+    if isinstance(n, NativeBox):
+        return n.children
+    if isinstance(n, NativeList):
+        return n.items
+    if isinstance(n, NativeItem):
+        return n.children
+    return []
+
+
+def describe(n: Native, level: int = 0) -> str:
+    id_text = f" #{n.id}" if n.id is not None else ""
+    cls_text = " ." + " ".join(n.classes) if n.classes else ""
+    if isinstance(n, NativeText):
+        detail = f' "{n.plain_text}"'
+    elif isinstance(n, NativeButton):
+        detail = f' "{n.label}"'
+    elif isinstance(n, NativeField):
+        detail = f" {n.type.name}"
+    elif isinstance(n, NativeImage):
+        detail = f" {n.source}"
+    else:
+        detail = ""
+    out = "  " * level + type(n).__name__ + id_text + cls_text + detail + "\n"
+    return out + "".join(describe(c, level + 1) for c in native_children(n))
+
+
+def same_as(a: Native, o: Native) -> bool:
+    if a is o:
+        return True
+    if (type(a) is not type(o) or a.key != o.key or a.id != o.id
+            or a.classes != o.classes or a.style != o.style):
+        return False
+    if isinstance(a, NativeText):
+        same = a.spans == o.spans
+    elif isinstance(a, NativeButton):
+        same = a.label == o.label and a.disabled == o.disabled
+    elif isinstance(a, NativeField):
+        same = (a.type == o.type and a.hint == o.hint and a.value == o.value
+                and a.disabled == o.disabled and a.read_only == o.read_only and a.rows == o.rows)
+    elif isinstance(a, NativeCheckbox):
+        same = a.checked == o.checked and a.disabled == o.disabled
+    elif isinstance(a, NativeImage):
+        same = a.source == o.source and a.description == o.description
+    elif isinstance(a, NativeItem):
+        same = a.marker == o.marker
+    elif isinstance(a, NativeBox):
+        same = (a.virtual == o.virtual and a.overlay == o.overlay
+                and a.header == o.header and a.footer == o.footer
+                and a.has_absolute == o.has_absolute)
+    else:
+        same = True
+    if not same:
+        return False
+    ca, cb = native_children(a), native_children(o)
+    if len(ca) != len(cb):
+        return False
+    return all(same_as(x, y) for x, y in zip(ca, cb))

nativelayout/host/__init__.py

@@ -0,0 +1,4 @@
+"""Kivy host of nativelayout (the core is `nativelayout.core`)."""
+from .native_view import NativeView, file_loader, run_app, system_is_dark
+
+__all__ = ["NativeView", "file_loader", "run_app", "system_is_dark"]

nativelayout/host/draw.py

@@ -0,0 +1,189 @@
+"""Drawing with Kivy: colors, shapes with rounded corners, gradients and icons."""
+from __future__ import annotations
+
+import math
+
+from kivy.graphics import (Color, Ellipse, Line, Rectangle, RoundedRectangle, StencilPop, StencilPush,
+                           StencilUnUse, StencilUse)
+from kivy.graphics.texture import Texture
+
+from nativelayout.core import icons as IconSet
+from nativelayout.core.tree import Corners, ImageFit, ImagePos, Length, NativeStyle
+
+
+def rgba(c: int, opacity: float = 1.0) -> tuple[float, float, float, float]:
+    """Unsigned ARGB integer -> (r, g, b, a) from 0 to 1."""
+    return (((c >> 16) & 255) / 255.0, ((c >> 8) & 255) / 255.0, (c & 255) / 255.0,
+            ((c >> 24) & 255) / 255.0 * opacity)
+
+
+def radii_of(style: NativeStyle, px) -> list[float]:
+    """[top-left, top-right, bottom-right, bottom-left] in pixels."""
+    c: Corners | None = style.corners
+    if c is not None:
+        return [px(c.top_left), px(c.top_right), px(c.bottom_right), px(c.bottom_left)]
+    r = px(style.border_radius)
+    return [r, r, r, r]
+
+
+_gradient_cache: dict = {}
+
+
+def gradient_texture(angle: int, colors: tuple[int, ...], size: int = 48) -> Texture:
+    """Small texture with the CSS gradient (angle in degrees, 0 = up, 90 = to the right)."""
+    key = (angle, colors, size)
+    tex = _gradient_cache.get(key)
+    if tex is not None:
+        return tex
+    rad = math.radians(angle)
+    dx, dy = math.sin(rad), -math.cos(rad)          # direction in screen coordinates (y down)
+    half = (abs(dx) + abs(dy)) / 2.0 or 1.0
+    stops = [rgba(c) for c in colors]
+    n = len(stops) - 1
+    buf = bytearray()
+    for row in range(size):                         # a Kivy texture has its origin at the bottom
+        sy = (size - 1 - row) / (size - 1) - 0.5
+        for col in range(size):
+            sx = col / (size - 1) - 0.5
+            t = min(max((sx * dx + sy * dy) / (2 * half) + 0.5, 0.0), 1.0)
+            f = t * n
+            i = min(int(f), n - 1)
+            k = f - i
+            a, b = stops[i], stops[i + 1]
+            for ch in range(4):
+                buf.append(int(255 * (a[ch] + (b[ch] - a[ch]) * k)))
+    tex = Texture.create(size=(size, size), colorfmt="rgba")
+    tex.blit_buffer(bytes(buf), colorfmt="rgba", bufferfmt="ubyte")
+    tex.mag_filter = tex.min_filter = "linear"
+    if len(_gradient_cache) > 64:
+        _gradient_cache.clear()
+    _gradient_cache[key] = tex
+    return tex
+
+
+def draw_box(canvas, x: float, y: float, w: float, h: float, style: NativeStyle, px,
+             background: int | None = None, border: int | None = None, opacity: float = 1.0,
+             image: Texture | None = None) -> None:
+    """Background, gradient, background image, shadow and border of a box. (x, y) is the bottom-left corner (Kivy)."""
+    if w <= 0 or h <= 0:
+        return
+    radii = radii_of(style, px)
+    r = [min(v, w / 2, h / 2) for v in radii]
+    elevation = px(style.elevation)
+    if elevation > 0.5 and (style.background_color or style.gradient or background):
+        steps = 4
+        for i in range(steps, 0, -1):
+            grow = elevation * i / steps
+            canvas.add(Color(0, 0, 0, 0.06 * opacity))
+            canvas.add(RoundedRectangle(pos=(x - grow * 0.4, y - grow * 0.9),
+                                        size=(w + grow * 0.8, h + grow * 0.8),
+                                        radius=[v + grow * 0.4 for v in r]))
+    if background is None and style.gradient is not None:
+        g = style.gradient
+        canvas.add(Color(1, 1, 1, opacity))
+        canvas.add(RoundedRectangle(pos=(x, y), size=(w, h), radius=r,
+                                    texture=gradient_texture(g.angle, g.colors)))
+    else:
+        bg = background if background is not None else style.background_color
+        if bg:
+            canvas.add(Color(*rgba(bg, opacity)))
+            canvas.add(RoundedRectangle(pos=(x, y), size=(w, h), radius=r))
+    if image is not None:
+        draw_image(canvas, image, x, y, w, h, style.background_size, style.background_position, r, opacity)
+    bw = px(style.border_width)
+    if bw > 0:
+        bw = max(1.0, bw)
+        canvas.add(Color(*rgba(border if border is not None else style.border_color, opacity)))
+        inset = bw / 2
+        canvas.add(Line(rounded_rectangle=(x + inset, y + inset, w - bw, h - bw,
+                                           *[max(v - inset, 0) for v in r]), width=bw))
+
+
+def _sub_tex_coords(tex: Texture, a0: float, a1: float, b0: float, b1: float) -> tuple:
+    """Texture coordinates of the part of `tex` between a0..a1 (left to right) and b0..b1 (bottom to top).
+
+    Uses the coordinates the texture already has, so it works whatever its orientation (loaded images are flipped).
+    """
+    u_bl, v_bl, u_br, v_br, u_tr, v_tr, u_tl, v_tl = tex.tex_coords
+
+    def at(a: float, b: float) -> tuple[float, float]:
+        u = u_bl * (1 - a) * (1 - b) + u_br * a * (1 - b) + u_tr * a * b + u_tl * (1 - a) * b
+        v = v_bl * (1 - a) * (1 - b) + v_br * a * (1 - b) + v_tr * a * b + v_tl * (1 - a) * b
+        return u, v
+
+    return (*at(a0, b0), *at(a1, b0), *at(a1, b1), *at(a0, b1))
+
+
+def draw_image(canvas, tex: Texture, x: float, y: float, w: float, h: float, fit: ImageFit,
+               pos: ImagePos = ImagePos.CENTER, radii: list[float] | None = None, opacity: float = 1.0) -> None:
+    """Draws `tex` in the box (x, y, w, h), (x, y) being the bottom-left corner.
+
+    COVER fills the box and cuts what does not fit, CONTAIN shows the whole image, FILL stretches it.
+    `pos` says which part stays in view (cover) or on which side the image sits (contain). It follows
+    the Android host (ImageBackground). COVER and FILL follow the rounded corners given in `radii`.
+    """
+    tw, th = tex.size
+    if tw <= 0 or th <= 0 or w <= 0 or h <= 0:
+        return
+    canvas.add(Color(1, 1, 1, opacity))
+    rounded = radii is not None and any(r > 0 for r in radii)
+
+    def box(coords, px_, py_, pw_, ph_, round_corners):
+        if round_corners:
+            # RoundedRectangle ignores a cut of the texture, so the image goes in a plain rectangle
+            # and a stencil mask with the rounded corners cuts it
+            canvas.add(StencilPush())
+            canvas.add(RoundedRectangle(pos=(px_, py_), size=(pw_, ph_), radius=radii))
+            canvas.add(StencilUse())
+            canvas.add(Color(1, 1, 1, opacity))
+            canvas.add(Rectangle(texture=tex, tex_coords=coords, pos=(px_, py_), size=(pw_, ph_)))
+            canvas.add(StencilUnUse())
+            canvas.add(RoundedRectangle(pos=(px_, py_), size=(pw_, ph_), radius=radii))
+            canvas.add(StencilPop())
+        else:
+            canvas.add(Rectangle(texture=tex, tex_coords=coords, pos=(px_, py_), size=(pw_, ph_)))
+
+    if fit == ImageFit.FILL:
+        box(_sub_tex_coords(tex, 0, 1, 0, 1), x, y, w, h, rounded)
+    elif fit == ImageFit.COVER:
+        scale = max(w / tw, h / th)
+        sw, sh = w / scale, h / scale                      # part of the image that stays in view, in image pixels
+        sx = 0.0 if pos == ImagePos.LEFT else (tw - sw) if pos == ImagePos.RIGHT else (tw - sw) / 2
+        sy = 0.0 if pos == ImagePos.TOP else (th - sh) if pos == ImagePos.BOTTOM else (th - sh) / 2   # from the top
+        coords = _sub_tex_coords(tex, sx / tw, (sx + sw) / tw, 1 - (sy + sh) / th, 1 - sy / th)
+        box(coords, x, y, w, h, rounded)
+    else:
+        scale = min(w / tw, h / th)
+        dw, dh = tw * scale, th * scale
+        dx = 0.0 if pos == ImagePos.LEFT else (w - dw) if pos == ImagePos.RIGHT else (w - dw) / 2
+        dy = 0.0 if pos == ImagePos.TOP else (h - dh) if pos == ImagePos.BOTTOM else (h - dh) / 2     # from the top
+        box(_sub_tex_coords(tex, 0, 1, 0, 1), x + dx, y + h - dy - dh, dw, dh, False)
+
+
+def draw_icon(canvas, name: str, x: float, y: float, size: float, color: int, opacity: float = 1.0) -> None:
+    """Draws a built-in icon (24x24 grid, stroke 2, round caps). (x, y) is the bottom-left corner."""
+    shapes = IconSet.shapes_of(name)
+    if shapes is None:
+        return
+    s = size / IconSet.GRID
+    top = y + size
+
+    def X(v): return x + v * s
+    def Y(v): return top - v * s
+
+    canvas.add(Color(*rgba(color, opacity)))
+    for sh in shapes:
+        if isinstance(sh, IconSet.Line):
+            pts = []
+            for i in range(0, len(sh.points), 2):
+                pts += [X(sh.points[i]), Y(sh.points[i + 1])]
+            canvas.add(Line(points=pts, width=IconSet.STROKE * s, cap="round", joint="round", close=sh.closed))
+        elif isinstance(sh, IconSet.Circle):
+            canvas.add(Line(circle=(X(sh.cx), Y(sh.cy), sh.r * s), width=IconSet.STROKE * s))
+        elif isinstance(sh, IconSet.Dot):
+            r = IconSet.DOT_RADIUS * s
+            canvas.add(Ellipse(pos=(X(sh.cx) - r, Y(sh.cy) - r), size=(2 * r, 2 * r)))
+        elif isinstance(sh, IconSet.Rect):
+            canvas.add(Line(rounded_rectangle=(X(sh.left), Y(sh.bottom), (sh.right - sh.left) * s,
+                                               (sh.bottom - sh.top) * s, sh.radius * s),
+                            width=IconSet.STROKE * s))