Source code for pdwidgets.pct

# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""
`pdwidgets.pct`
====================================================
Classes that dynamically calculate a percentage of a Widget's width or height.

``Width``/``Height`` are lightweight value objects: pass one as a widget's ``w``
or ``h`` and it tracks the reference widget's size, so a child stays at (say)
50% of its parent even after the parent is resized.

Performance
-----------
The value is read straight from ``widget.width`` / ``widget.height`` (plain
``int(self._w)`` / ``int(self._h)`` accessors) rather than constructing a full
``widget.area`` ``Area`` object on every access, and the computed result is
cached and only recomputed when the reference dimension actually changes. This
keeps the common case (repeated reads while the widget is not resizing) down to
a single attribute read and comparison, which matters on MicroPython where the
old design allocated an ``Area`` and re-multiplied on every arithmetic op and
comparison.
"""


class _Percent:
    """Base for `Width` / `Height`: a cached percentage of a widget dimension."""

    # Value-like and dynamic, so it is intentionally unhashable (mirrors
    # ``pygraphics.Area``); it is never used as a set/dict key.
    __hash__ = None

    def __init__(self, percent, widget):
        if not (0 <= percent <= 100):
            raise ValueError(f"{self.__class__.__name__}: percent must be between 0 and 100")
        if not hasattr(widget, "area"):
            raise AttributeError(f"{self.__class__.__name__}: widget has no attribute 'area'")
        self._percent = percent
        self._widget = widget
        self._cache_dim = None
        self._cache_val = 0.0

    def _dimension(self):
        """Return the current reference dimension (overridden by subclasses)."""
        raise NotImplementedError

    def __float__(self):
        dim = self._dimension()
        if dim != self._cache_dim:
            self._cache_dim = dim
            self._cache_val = self._percent * dim / 100
        return self._cache_val

    def __eq__(self, other):
        return float(self) == other

    def __repr__(self):
        return str(float(self))

    def __add__(self, other):
        return float(self) + other

    def __sub__(self, other):
        return float(self) - other

    def __mul__(self, other):
        return float(self) * other

    def __truediv__(self, other):
        return float(self) / other

    def __radd__(self, other):
        return self.__add__(other)

    def __rsub__(self, other):
        return -self.__sub__(other)

    def __rmul__(self, other):
        return self.__mul__(other)

    def __rtruediv__(self, other):
        return other / float(self)

    def __int__(self):
        return int(float(self))


[docs] class Height(_Percent): """ A value object that tracks a percentage of a Widget's height. Args: percent (int | float): The percentage of the height of the widget (0-100). widget (Widget): The widget whose height drives the calculation. Raises: ValueError: If the percent is not between 0 and 100. AttributeError: If the widget has no attribute 'area'. Returns: (int): The calculated percentage of the height of the widget. Usage: import pdwidgets as pd ... widget = pd.Widget(parent, h=100) my_height = pd.pct.Height(50, widget) print(my_height) # 50 widget.height = 200 print(my_height) # 100 """ def _dimension(self): return self._widget.height
[docs] class Width(_Percent): """ A value object that tracks a percentage of a Widget's width. Args: percent (int | float): The percentage of the width of the widget (0-100). widget (Widget): The widget whose width drives the calculation. Raises: ValueError: If the percent is not between 0 and 100. AttributeError: If the widget has no attribute 'area'. Returns: (int): The calculated percentage of the width of the widget. Usage: import pdwidgets as pd ... widget = pd.Widget(parent, w=100) my_width = pd.pct.Width(50, widget) print(my_width) # 50 widget.width = 200 print(my_width) # 100 """ def _dimension(self): return self._widget.width