widget

pdwidgets.widget

Base widget class and geometry/event primitives.

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)

Base class for all pdwidgets UI elements.

Subclass :class:Widget for custom controls, or use it as a simple container. Geometry uses relative x/y plus an :data:ALIGN constant; :attr:value changes trigger :meth:changed and redraw via :meth:invalidate. Pointer events route through :meth:handle_event; use :meth:add_event_cb to register handlers.

The base Widget class for creating widgets. May be used as a base class for custom widgets or as a container for other widgets.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget that contains this widget. All widgets except the Display widget must have a parent.	required
x	int	The x-coordinate of the widget.	0
y	int	The y-coordinate of the widget.	0
w	int	The width of the widget.	None
h	int	The height of the widget.	None
align	int	The alignment of the widget (default is ALIGN.TOP_LEFT).	None
align_to	Widget	The widget to align to (default is the parent widget).	None
fg	int	The foreground color of the widget (default is the parent's foreground color).	None
bg	int	The background color of the widget (default is the parent's background color).	None
visible	bool	The visibility of the widget (default is True).	True
value	str	The value of the widget (e.g., text of a label, value of a slider).	None
padding	tuple	The padding on each side of the widget (default is (2, 2, 2, 2)).	None

align property writable

Alignment constant from :data:ALIGN.

align_to property writable

Widget used as the alignment anchor.

area property

Absolute bounding box of the widget on screen.

Returns:

Name	Type	Description
Area	Area	(x, y, width, height) in display coordinates.

color_theme property

Semantic color palette from the display.

display property

Root :class:Display for this widget subtree.

height property writable

Widget height in pixels.

padded_area property

Bounding box inset by :attr:padding.

parent property writable

Parent widget that contains this widget.

value property writable

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

visible property writable

Get widget visibility.

width property writable

Widget width in pixels.

x property writable

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

y property writable

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

add_child(child)

Adds a child widget to the current widget.

add_dirty_descendant(branch)

Bubble a dirty descendant up the tree.

add_dirty_widget(child)

Mark a direct child as dirty for rendering.

add_event_cb(event_type, callback, data=None)

Register a callback for an event type on this widget.

Parameters:

Name	Type	Description	Default
event_type		eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback		Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

changed()

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)

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.

handle_event(event, condition=None, point=None)

Handle an event and propagate it to child widgets.

Subclasses that need to handle events should override this method and call it to propagate the event to children.

The default condition is a module-level function (not a per-call closure), and for pointer events the pointer is translated to display coordinates once per dispatch rather than once per child.

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	condition(child, event, point) returning True when the event should be delivered to child. Defaults to a pointer-hit test for mouse events, else always True.	None
point	tuple	Pre-translated pointer position, shared across the recursion for pointer events.	None

hide(hide=True)

Show or hide the widget.

Parameters:

Name	Type	Description	Default
hide	bool	True to hide, False to show.	True

invalidate()

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

remove_child(widget)

Removes a child widget from the current widget.

remove_dirty_descendant(branch)

Clear a descendant branch from the dirty set.

remove_dirty_widget(child)

Clear a child from the dirty set.

remove_event_cb(event_type, callback)

Remove a previously registered event callback.

Parameters:

Name	Type	Description	Default
event_type	int	eventsys.events constant the callback was registered for.	required
callback	callable	The callback to remove. No error if absent.	required

render()

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

set_change_cb(callback)

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

Parameters:

Name	Type	Description	Default
callback	callable	Called as callback(widget) on change.	required

set_modal(modal=True)

Grab or release modal pointer capture for this widget.

While a widget is modal, the :class: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 :class:Dialog and :class: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:

Name	Type	Description	Default
modal	bool	True to grab modal capture, False to release.	True

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

Update any subset of the widget's geometry and re-layout.

Only the arguments that are not None are changed. Changing geometry invalidates the parent so the affected area is redrawn.

Parameters:

Name	Type	Description	Default
x	int	New relative x-coordinate.	None
y	int	New relative y-coordinate.	None
w	int	New width.	None
h	int	New height.	None
align	int	New ALIGN constant.	None
align_to	Widget	New widget to align against.	None

set_value(value)

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

Parameters:

Name	Type	Description	Default
value		The new value; triggers changed when it differs.	required