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:
objectBase class for pdwidgets UI elements and simple container layouts.
Subclass
Widgetto 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
ScreenandDisplay, 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:
This is the primary way to react to pointer and keyboard input without overriding
handle_eventin every subclass.
- remove_event_cb(event_type, callback)[source]
Remove a previously registered event callback.
- Parameters:
event_type (int) –
eventsconstant 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)returningTruewhen the event should reachchild. 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
Displayfor 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 rootDisplayoverrides this.
- property value
Widget value (text, number, bool, etc.).
- 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) –
Trueto hide,Falseto show.
- 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
Noneare 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.
- set_value(value)[source]
Set the widget’s value (equivalent to assigning
widget.value).- Parameters:
value (Any) – The new value; triggers
changedwhen it differs.
- set_modal(modal=True)[source]
Grab or release modal pointer capture for this widget.
While a widget is modal, the
Displayroutes 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 byDialogandDropdownto 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) –
Trueto grab modal capture,Falseto release.