bootstack 0.1.0__py3-none-any.whl

bootstack/style/element.py

@@ -0,0 +1,173 @@
+from collections.abc import Sequence
+from tkinter import PhotoImage
+from typing import Any, Optional, Tuple, Union
+
+
+class Element:
+    """
+    A style layout element for use in ttk-style widget construction.
+
+    Represents a named element within a widget layout. Each element can have
+    layout options (like `expand`, `side`, `sticky`, etc.) and nested children.
+
+    Attributes:
+        name (str): The name of this element (e.g., "Label.border").
+        parent (Optional[Element]): The parent element, if any.
+        _children (list[Element]): The list of child elements.
+        _options (dict): Layout configuration options for this element.
+    """
+
+    def __init__(
+            self,
+            name: str,
+            *,
+            expand: Optional[int] = None,
+            side: Optional[str] = None,
+            sticky: Optional[str] = None,
+            border: Optional[int] = None,
+    ):
+        """
+        Initialize a new layout Element.
+
+        Args:
+            name: The name of the element.
+            expand: Whether the element should expand to fill its parcel.
+            side: The side of the cavity to place the element.
+            sticky: How to align the element within its parcel (e.g., "nsew").
+            border: Border margin applied to the element.
+        """
+        self.name = name
+        self.parent: Optional[Element] = None
+        self._children: list[Element] = []
+        self._options: dict[str, Any] = {
+            "expand": expand,
+            "side": side,
+            "sticky": sticky,
+            "border": border,
+        }
+
+    def add_parent(self, parent: "Element") -> None:
+        """
+        Set the parent element and register this element as its child.
+
+        Args:
+            parent: The parent Element to attach to.
+        """
+        self.parent = parent
+        parent._children.append(self)
+
+    def children(self, layout: Sequence["Element"]):
+        """
+        Add children to this layout
+
+        Args:
+            layout: A list of Elements or nested lists/tuples representing the hierarchy.
+        """
+
+        def assign_parents(elements: Sequence[Any], parent: Optional[Element] = None):
+            for i, item in enumerate(elements):
+                if isinstance(item, Element) and parent:
+                    item.add_parent(parent)
+                elif isinstance(item, (list, tuple)):
+                    assign_parents(item, elements[i - 1] if i > 0 else None)
+
+        assign_parents(layout, self)
+        return self
+
+    def spec(self):
+        """
+        Recursively build a Python layout spec compatible with ttk.Style().layout().
+
+        Returns:
+            Tuple[str, dict]: A (name, options) pair for use in a layout tree.
+        """
+        options = {k: v for k, v in self._options.items() if v is not None}
+
+        if self._children:
+            options["children"] = [child.spec() for child in self._children]
+
+        if options:
+            return self.name, options
+        else:
+            return self.name, {"sticky": ""}
+
+
+class ElementImage:
+    """
+    An image-based element for styling ttk widgets.
+
+    Attributes:
+        _name (str): Name of the image element.
+        _image (str | PhotoImage): The default image.
+        _image_specs (list): List of state-specific overrides.
+        _options (dict): Element rendering options like width, padding, sticky, etc.
+    """
+
+    def __init__(
+            self,
+            name: str,
+            image: Union[PhotoImage, str],
+            *,
+            border: Optional[Union[int, Tuple[int, ...]]] = None,
+            height: Optional[int] = None,
+            width: Optional[int] = None,
+            padding: Optional[Union[int, Tuple[int, ...]]] = None,
+            sticky: Optional[str] = None,
+    ):
+        """
+        Initialize a new image element.
+
+        Args:
+            name: The name of the element (e.g., "Button.border").
+            image: The default image object or image name.
+            border: Border definition for tiling/stretching (e.g., 2 or (2,2)).
+            height: Minimum height of the element.
+            width: Minimum width of the element.
+            padding: Interior padding within the element.
+            sticky: Alignment within the layout parcel (e.g., "nsew").
+        """
+        self._name = name
+        self._image = image
+        self._image_specs: list[tuple[str, Union[str, PhotoImage]]] = []
+        self._options: dict[str, Any] = {
+            "border": border,
+            "height": height,
+            "width": width,
+            "padding": padding,
+            "sticky": sticky,
+        }
+
+    @property
+    def name(self) -> str:
+        """
+        Return the name of the element.
+
+        Returns:
+            str: Element name.
+        """
+        return self._name
+
+    def add_spec(self, state: str, image: Union[str, PhotoImage]) -> None:
+        """
+        Add a state-specific image override.
+
+        Args:
+            state: Widget state (e.g., "disabled", "active").
+            image: ManagedImage instance or registered image name.
+        """
+        self._image_specs.append((state, str(image)))
+
+    def build(self):
+        args: list[Any] = [str(self._image)]
+        for state, image in self._image_specs:
+            args.append(tuple([state, str(image)]))
+        options = {k: v for k, v in self._options.items() if v is not None}
+        return self.name, args, options
+
+    def state_specs(self, specs: list[Tuple[str, Union[str, PhotoImage]]]):
+        for spec in specs:
+            self.add_spec(*spec)
+        return self
+
+    def __str__(self) -> str:
+        return self.name

bootstack/style/fonts.py

@@ -0,0 +1,123 @@
+"""Public font configuration for bootstack.
+
+These functions adjust the application's typography at runtime. They operate on
+the framework's font tokens (`body`, `code`, `heading-lg`, …); see the
+typography reference for the full token list.
+
+Call them inside an active app (within `with bs.App():`), since fonts are bound
+to the application's Tk interpreter.
+"""
+from __future__ import annotations
+
+import warnings
+from tkinter import font as tkfont
+from typing import Literal
+
+from bootstack.style.typography import Typography
+
+__all__ = ["get_font_families", "set_font_family", "update_font_token"]
+
+
+def _installed_families() -> set[str]:
+    """Raw set of font families known to the active Tk interpreter."""
+    return set(tkfont.families())
+
+
+def get_font_families() -> list[str]:
+    """Return the installed UI font families available to the application.
+
+    System fonts that start with `@` and emoji fonts are filtered out, leaving
+    the families suitable for body and heading text. The list is sorted
+    alphabetically.
+
+    Returns:
+        Sorted list of font family names.
+    """
+    families = {
+        f for f in _installed_families()
+        if f and not f.startswith("@") and "emoji" not in f.lower()
+    }
+    return sorted(families)
+
+
+def set_font_family(family: str, *, mono_family: str | None = None) -> None:
+    """Set the application font family for all non-code text.
+
+    Every token except `code` is switched to `family`; the monospace `code`
+    token is left untouched unless `mono_family` is given. If a requested
+    family is not installed, a warning is issued and the current fonts are left
+    unchanged.
+
+    Args:
+        family: Font family for body, heading, label, and caption text
+            (e.g. `'Segoe UI'`, `'Inter'`). Must be installed.
+        mono_family: Optional family for the `code` token. Defaults to leaving
+            the existing monospace family in place.
+    """
+    installed = _installed_families()
+    if family not in installed:
+        warnings.warn(
+            f"Font family {family!r} is not installed; fonts left unchanged. "
+            f"Use get_font_families() to list available families.",
+            stacklevel=2,
+        )
+        return
+    if mono_family is not None and mono_family not in installed:
+        warnings.warn(
+            f"Font family {mono_family!r} is not installed; fonts left unchanged. "
+            f"Use get_font_families() to list available families.",
+            stacklevel=2,
+        )
+        return
+    Typography.set_global_family(family, mono_family=mono_family)
+
+
+def update_font_token(
+    name: str,
+    *,
+    family: str | None = None,
+    size: int | None = None,
+    weight: Literal["normal", "bold"] | None = None,
+    slant: Literal["roman", "italic"] | None = None,
+    underline: bool | None = None,
+    overstrike: bool | None = None,
+) -> None:
+    """Override the attributes of a single font token.
+
+    Only the attributes you pass are changed; the rest of the token is left as
+    is. The update applies everywhere the token is used.
+
+    Args:
+        name: Token to update (e.g. `'body'`, `'heading-lg'`, `'code'`).
+        family: New font family. Must be installed.
+        size: New point size.
+        weight: `'normal'` or `'bold'`.
+        slant: `'roman'` or `'italic'`.
+        underline: Whether to underline the text.
+        overstrike: Whether to strike through the text.
+    """
+    if name not in Typography.token_names():
+        raise ValueError(
+            f"Unknown font token: {name!r}. "
+            f"Valid tokens: {', '.join(sorted(Typography.token_names()))}."
+        )
+    if family is not None and family not in _installed_families():
+        warnings.warn(
+            f"Font family {family!r} is not installed; token left unchanged. "
+            f"Use get_font_families() to list available families.",
+            stacklevel=2,
+        )
+        return
+
+    changes = {
+        "font": family,
+        "size": size,
+        "weight": weight,
+        "slant": slant,
+        "underline": underline,
+        "overstrike": overstrike,
+    }
+    changes = {k: v for k, v in changes.items() if v is not None}
+    if not changes:
+        return
+    Typography.update_font_token(name, **changes)