pdwidgets.widget

Base widget class and geometry/event primitives.

class pdwidgets.widget.Widget(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)[source]

Bases: object

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.

add_event_cb(event_type, callback, data=None)[source]

Register an event handler for this widget.

Parameters:
  • 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.

remove_event_cb(event_type, callback)[source]

Remove a previously registered event callback.

Parameters:
  • event_type (int) – events constant the callback was registered for.

  • callback (callable) – The callback to remove. No error if absent.

handle_event(event, condition=None, point=None)[source]

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.

Parameters:
  • 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.

property parent

Parent widget that contains this widget.

property area

Absolute bounding box of the widget on screen.

Returns:

Area: (x, y, width, height) in display coordinates.

property padded_area

Bounding box inset by padding.

property x

Calculate the absolute x-coordinate of the widget based on align

property y

Calculate the absolute y-coordinate of the widget based on align

property width

Widget width in pixels.

property height

Widget height in pixels.

property align

Alignment constant from ALIGN.

property align_to

Widget used as the alignment anchor.

property display

Root Display for this widget subtree.

property color_theme

Semantic color palette from the display.

property visible

Get widget visibility.

Detached widgets (parent is None) are not visible. The root Display overrides this.

property value

Widget value (text, number, bool, etc.).

add_child(child)[source]

Adds a child widget to the current widget.

changed()[source]

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.

draw(area=None)[source]

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.

hide(hide=True)[source]

Show or hide the widget.

Parameters:

hide (bool) – True to hide, False to show.

invalidate()[source]

Mark this widget (and its descendants) as needing a redraw.

remove()[source]

Detach this widget from its parent (no-op if already detached).

clear()[source]

Remove all child widgets via remove_child.

remove_child(widget)[source]

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).

set_change_cb(callback)[source]

Set the callback invoked when the widget’s value changes.

Parameters:

callback (callable) – Called as callback(widget) on change.

set_position(x=None, y=None, w=None, h=None, align=None, align_to=None)[source]

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.

Parameters:
  • 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.

add_dirty_widget(child)[source]

Mark a direct child as dirty for rendering.

add_dirty_descendant(branch)[source]

Bubble a dirty descendant up the tree.

render()[source]

Redraw this widget if invalidated, then clear its dirty flags.

remove_dirty_widget(child)[source]

Clear a child from the dirty set.

remove_dirty_descendant(branch)[source]

Clear a descendant branch from the dirty set.

set_value(value)[source]

Set the widget’s value (equivalent to assigning widget.value).

Parameters:

value (Any) – The new value; triggers changed when it differs.

set_modal(modal=True)[source]

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.

Parameters:

modal (bool) – True to grab modal capture, False to release.