Source code for pdwidgets.widget
# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Base widget class and geometry/event primitives."""
from pygraphics import Area
from ._constants import ALIGN, DEFAULT_PADDING, POSITION
from ._themes import ColorTheme
from ._util import _POINTER_EVENTS, _cond_always, _cond_pointer, _log
[docs]
class Widget:
"""Base class for pdwidgets UI elements and simple container layouts.
Subclass `Widget` to build a custom control, or use it directly as a
lightweight layout container. Each widget has a local geometry, an optional
parent/child tree, a semantic value, and a small event model. The default
implementation draws a solid background and leaves the interesting visuals to
subclasses, while the base class handles hit-testing, invalidation, and
child propagation.
In practice, most applications compose a tree of widgets with
`Screen` and `Display`, then use alignment and padding to
arrange content rather than manually calculating absolute coordinates.
"""
next_instance_id = 0
def __init__(
self,
parent,
x=0,
y=0,
w=None,
h=None,
align=None,
align_to=None,
fg=None,
bg=None,
visible=True,
value=None,
padding=None,
radius=0,
):
"""Create a widget in a parent tree with optional geometry and styling.
Args:
parent (Widget): Parent widget that owns this child. The root display
is the only widget that may have no parent.
x (int): Relative x offset from the parent or alignment anchor.
y (int): Relative y offset from the parent or alignment anchor.
w (int): Width in pixels; defaults to the parent's width.
h (int): Height in pixels; defaults to the parent's height.
align (int): Alignment constant from `ALIGN`.
align_to (Widget): Widget used as the alignment anchor.
fg (int): Foreground color; falls back to the parent color.
bg (int): Background color; falls back to the parent color.
visible (bool): Whether the widget is shown immediately.
value (Any): Widget value such as text, numeric state, or a model object.
padding (tuple): Padding applied to the widget's content area.
radius (int): Corner radius stored on the widget; subclasses may use
it when drawing rounded surfaces.
Example:
screen = Screen(display)
title = Label(screen, x=8, y=8, value="Hello")
"""
self.id = Widget.next_instance_id # Currently only used in debugging
Widget.next_instance_id += 1
self._parent: Widget = None
self.fg = fg if fg is not None else parent.fg if parent else -1
self.bg = bg if bg is not None else parent.bg if parent else 0
self._visible = visible
self._value = value # Value of the widget (e.g., text of a label)
self.padding = padding if padding is not None else DEFAULT_PADDING
self.radius = radius
self.children: list[Widget] = []
self.dirty_widgets = set()
self.dirty_descendants = set()
self.invalidated = False
self._event_callbacks = {}
self._change_callback = None
self._x = self._y = self._w = self._h = self._align = self._align_to = None
# When True, this widget's padded_area clips descendant drawing (ScrollView / ListView).
self.clip_content = False
self.set_position(
x,
y,
w or parent.width,
h or parent.height,
align if align is not None else ALIGN.TOP_LEFT,
align_to or parent,
)
self.parent: Widget = parent
self._register_callbacks()
def __str__(self):
"""Return a short ``ID <n> <ClassName>`` label for debugging."""
return f"ID {self.id} {self.__class__.__name__}"
def __format__(self, format_spec):
"""Format like `__str__`, applying ``format_spec`` to the class name.
Args:
format_spec: Format specifier applied to the class name portion.
"""
return f"ID {self.id} {self.__class__.__name__:{format_spec}}"
def _register_callbacks(self):
"""
Register event callbacks for the widget. Subclasses should override this method to register event callbacks.
"""
[docs]
def add_event_cb(self, event_type, callback, data=None):
"""Register an event handler for this widget.
Args:
event_type (int): ``events`` constant such as
``events.MOUSEBUTTONDOWN`` or ``events.KEYDOWN``.
callback (callable): Callable invoked as ``callback(data_or_sender, event)``.
data (Any): User data passed as the first callback argument; defaults to
the widget itself.
This is the primary way to react to pointer and keyboard input without
overriding `handle_event` in every subclass.
"""
# Each item's key is the callback and value is the optional data. If the event_type is not found,
# add it to the dictionary with the callback and data.
data = data or self
if event_type not in self._event_callbacks:
self._event_callbacks[event_type] = {}
self._event_callbacks[event_type][callback] = data
[docs]
def remove_event_cb(self, event_type: int, callback: callable):
"""
Remove a previously registered event callback.
Args:
event_type (int): ``events`` constant the callback was
registered for.
callback (callable): The callback to remove. No error if absent.
"""
if event_type in self._event_callbacks:
self._event_callbacks[event_type].pop(callback, None)
[docs]
def handle_event(self, event, condition=None, point=None):
"""Dispatch an event through the widget tree.
The default implementation walks the children in order, checks whether
each child should receive the event, and invokes any registered callbacks
for that event type. Pointer events are translated to display
coordinates once per dispatch so child widgets can reason about screen
positions consistently.
Args:
event (Event): The event to handle.
condition (callable): ``condition(child, event, point)`` returning
``True`` when the event should reach ``child``. The default
uses pointer hit-testing for mouse/touch events and falls back to
unconditional delivery for keyboard and other events.
point (tuple): Pre-translated pointer position shared across the
recursive walk.
"""
if condition is None:
if event.type in _POINTER_EVENTS:
condition = _cond_pointer
point = self.display.translate_point(event.pos)
else:
condition = _cond_always
# Snapshot: click handlers often rebuild the tree (remove_child) mid-walk.
for child in list(self.children):
if child.parent is not self:
continue
if child.visible:
if condition(child, event, point):
for callback, data in child._event_callbacks.get(event.type, {}).items():
callback(data, event)
if child.parent is not self:
continue
child.handle_event(event, condition, point)
@property
def parent(self):
"""Parent widget that contains this widget."""
return self._parent
@parent.setter
def parent(self, parent):
"""
Reparent this widget.
Args:
parent (Widget): New parent, or ``None`` to detach.
"""
if parent != self._parent:
if self._parent:
self._parent.remove_child(self)
self._parent = parent
if self._parent:
self._parent.add_child(self)
if self.align_to is None:
self.set_position(align_to=parent)
@property
def area(self) -> Area:
"""
Absolute bounding box of the widget on screen.
Returns:
Area: ``(x, y, width, height)`` in display coordinates.
"""
return Area(self.x, self.y, self.width, self.height)
@property
def padded_area(self):
"""Bounding box inset by `padding`."""
return self.area.inset(*self.padding)
@property
def x(self):
"""Calculate the absolute x-coordinate of the widget based on align"""
align = self.align
align_to = self.align_to or self.display
x = align_to.x + int(self._x)
if align & POSITION.LEFT:
if align & POSITION.OUTER:
x -= self.width
elif align & POSITION.RIGHT:
x += align_to.width
if not align & POSITION.OUTER:
x -= self.width
else:
x += (align_to.width - self.width) // 2
return x
@x.setter
def x(self, x):
"""Set the relative x-coordinate (triggers relayout)."""
self.set_position(x=x)
@property
def y(self):
"""Calculate the absolute y-coordinate of the widget based on align"""
align = self.align
align_to = self.align_to or self.display
y = align_to.y + int(self._y)
if align & POSITION.TOP:
if align & POSITION.OUTER:
y -= self.height
elif align & POSITION.BOTTOM:
y += align_to.height
if not align & POSITION.OUTER:
y -= self.height
else:
y += (align_to.height - self.height) // 2
return y
@y.setter
def y(self, y):
"""Set the relative y-coordinate (triggers relayout)."""
self.set_position(y=y)
@property
def width(self):
"""Widget width in pixels."""
return int(self._w)
@width.setter
def width(self, w):
"""Set widget width in pixels."""
self.set_position(w=w)
@property
def height(self):
"""Widget height in pixels."""
return int(self._h)
@height.setter
def height(self, h):
"""Set widget height in pixels."""
self.set_position(h=h)
@property
def align(self):
"""Alignment constant from `ALIGN`."""
return self._align
@align.setter
def align(self, align):
"""Set alignment relative to `align_to`."""
self.set_position(align=align)
@property
def align_to(self):
"""Widget used as the alignment anchor."""
return self._align_to
@align_to.setter
def align_to(self, align_to):
"""Set the alignment anchor widget."""
self.set_position(align_to=align_to)
@property
def display(self):
"""Root `Display` for this widget subtree."""
return self.parent.display
@property
def color_theme(self) -> ColorTheme:
"""Semantic color palette from the display."""
return self.display.color_theme
@property
def visible(self):
"""Get widget visibility.
Detached widgets (``parent is None``) are not visible. The root
`Display <pdwidgets.display.Display>` overrides this.
"""
if not self._visible:
return False
parent = self._parent
return parent is not None and parent.visible
@visible.setter
def visible(self, visible):
"""Set widget visibility."""
if visible != self._visible:
if not self.visible:
self._visible = True
self.invalidate()
else:
self._visible = False
if self._parent is not None:
self._parent.invalidate()
@property
def value(self):
"""Widget value (text, number, bool, etc.)."""
return self._value
@value.setter
def value(self, value):
"""Set the value and call `changed` when it differs."""
if value != self._value:
self._value = value
self.changed()
[docs]
def add_child(self, child):
"""Adds a child widget to the current widget."""
_log("Adding", child, "to", self)
self.children.append(child)
child.invalidate()
[docs]
def changed(self):
"""Called when the value of the widget changes. May be overridden in subclasses.
If overridden, the subclass should call this method to trigger the on_change_callback and invalidate.
"""
if self.visible:
if self._change_callback:
self._change_callback(self)
self.invalidate()
[docs]
def draw(self, area=None):
"""
Draw the widget on the screen. Subclasses should override this method to draw the widget unless the widget is
a container widget (like a screen) that contains other widgets. Subclasses may call this method to draw the
background of the widget before drawing other elements.
"""
if self.bg is not None:
area = self.area if area is None else area
self.display.framebuf.fill_rect(*area, self.bg)
[docs]
def hide(self, hide=True):
"""
Show or hide the widget.
Args:
hide (bool): ``True`` to hide, ``False`` to show.
"""
self.visible = not hide
[docs]
def invalidate(self):
"""Mark this widget (and its descendants) as needing a redraw."""
if not self.invalidated:
self.invalidated = True
if self.parent:
self.parent.add_dirty_widget(self)
for child in self.children:
child.invalidate()
[docs]
def remove(self):
"""Detach this widget from its parent (no-op if already detached)."""
parent = self._parent
if parent is not None:
parent.remove_child(self)
[docs]
def clear(self):
"""Remove all child widgets via `remove_child`."""
for child in list(self.children):
self.remove_child(child)
[docs]
def remove_child(self, widget):
"""Removes a child widget from the current widget.
Detaches the child so it cannot paint again via leftover dirty-set
entries (page swaps that leave empty regions would otherwise ghost).
"""
self.children.remove(widget)
self.dirty_widgets.discard(widget)
self.dirty_descendants.discard(widget)
if widget._parent is self:
widget._parent = None
self.invalidate()
[docs]
def set_change_cb(self, callback):
"""
Set the callback invoked when the widget's value changes.
Args:
callback (callable): Called as ``callback(widget)`` on change.
"""
self._change_callback = callback
[docs]
def set_position(self, x=None, y=None, w=None, h=None, align=None, align_to=None):
"""Update a subset of the widget's geometry and relayout state.
Only the arguments that are not ``None`` are changed. Geometry changes
invalidate the parent so the affected area is redrawn on the next tick.
This is the preferred way to reposition or resize widgets after they
have already been created.
Args:
x (int): New relative x-coordinate.
y (int): New relative y-coordinate.
w (int): New width in pixels.
h (int): New height in pixels.
align (int): New ``ALIGN`` constant.
align_to (Widget): New widget to align against.
"""
changed = False
if x is not None:
self._x = x
changed = True
if y is not None:
self._y = y
changed = True
if w is not None:
self._w = w
changed = True
if h is not None:
self._h = h
changed = True
if align is not None:
self._align = align
changed = True
if align_to is not None:
self._align_to = align_to
changed = True
if changed and self.parent is not None:
self.parent.invalidate()
[docs]
def add_dirty_widget(self, child):
"""Mark a direct child as dirty for rendering."""
self.dirty_widgets.add(child)
self.dirty_descendants.add(child)
if self.parent:
self.parent.add_dirty_descendant(self)
[docs]
def add_dirty_descendant(self, branch):
"""Bubble a dirty descendant up the tree."""
self.dirty_descendants.add(branch)
if self.parent:
self.parent.add_dirty_descendant(self)
def _clip_from_ancestors(self):
"""Intersect padded areas of ancestors with ``clip_content`` set."""
clip = None
node = self.parent
while node is not None:
if getattr(node, "clip_content", False):
area = node.padded_area
clip = area if clip is None else clip.clip(area)
node = node.parent
if clip is not None and (clip.w <= 0 or clip.h <= 0):
return None
return clip
[docs]
def render(self):
"""Redraw this widget if invalidated, then clear its dirty flags."""
if self.invalidated:
_log("Drawing", self, "on", self.parent, "at", self.area)
clip = self._clip_from_ancestors()
if clip is not None:
self.display.clip_push(clip)
try:
self.draw()
finally:
if clip is not None:
self.display.clip_pop()
self.invalidated = False
if self.parent:
self.parent.remove_dirty_widget(self)
[docs]
def remove_dirty_widget(self, child):
"""Clear a child from the dirty set."""
self.dirty_widgets.discard(child)
if not self.dirty_widgets and not self.dirty_descendants and self.parent:
self.parent.remove_dirty_descendant(self)
[docs]
def remove_dirty_descendant(self, branch):
"""Clear a descendant branch from the dirty set."""
self.dirty_descendants.discard(branch)
[docs]
def set_value(self, value) -> None:
"""
Set the widget's value (equivalent to assigning ``widget.value``).
Args:
value (Any): The new value; triggers ``changed`` when it differs.
"""
self.value = value
[docs]
def set_modal(self, modal=True):
"""
Grab or release modal pointer capture for this widget.
While a widget is modal, the `Display` routes all pointer events
(mouse/touch) through this widget's branch only, so widgets elsewhere in
the tree do not receive them. Non-pointer events (e.g. key events) are
unaffected. This is used by `Dialog` and `Dropdown` to
implement modal overlays without a separate event layer. Modality nests:
the most recently grabbed widget wins, and releasing restores the
previous one.
Args:
modal (bool): ``True`` to grab modal capture, ``False`` to release.
"""
modals = self.display._modals
if modal:
if self not in modals:
modals.append(self)
elif self in modals:
modals.remove(self)