pdwidgets

pdwidgets

pdwidgets

Provides a collection of widgets for creating graphical user interfaces on embedded systems. It includes base classes for widgets, as well as specific widgets such as buttons, labels, sliders, and more.

Classes:

Name	Description
Task	A task that runs a callback function after a specified delay.
Widget	The base class for creating widgets.
Display	Manages the display and child widgets.
Screen	A container for widgets.
Button	A widget that displays an icon and/or text.
Label	A widget that displays text.
TextBox	A widget that displays formatted text.
Icon	A widget that displays an icon.
IconButton	A button widget that displays an icon.
Toggle	A button widget that toggles between two states.
ToggleButton	A toggle button widget.
CheckBox	A checkbox widget.
RadioGroup	Manages a group of radio buttons.
RadioButton	A radio button widget.
ProgressBar	A widget that displays a progress bar.
Slider	A widget that displays a slider with a circular knob.
ScrollBar	A widget that displays a scroll bar with two arrow buttons and a slider.
DigitalClock	A widget that displays the current time.
ListView	A widget that displays a list of items.

Functions:

Name	Description
tick	Calls the tick method of all Display objects.
init_timer	Initializes the timer to call the tick function at regular intervals.

Classes

Task

Task(callback, delay)

A task that runs a callback function after a specified delay. Used by the Display object to run tasks at regular intervals, such as refreshing the display or updating the clock.

Parameters:

Name	Type	Description	Default
callback	callable	The function to run.	required
delay	int	The delay in milliseconds before running the callback.	required

Usage

def my_callback(): print("Hello, world!")

task = Task(my_callback, 1000) # Run my_callback every second display.add_task(task)

Methods:

run

run(t)

Run the callback function and set the next run time.

Parameters:

Name	Type	Description	Default
t	int	The current time in milliseconds.	required

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)

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

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

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

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.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

Display

Display(display_drv, broker, tfa=0, bfa=0, format=RGB565)

Initialize a Display object to manage the display and child widgets.

Parameters:

Name	Type	Description	Default
display_drv	DisplayDriver	The display driver object that manages the display hardware.	required
broker	Broker	The event broker object that manages the event system.	required
tfa	int	The top fixed area of the display.	0
bfa	int	The bottom fixed area of the display.	0
format	int	The color format of the display (default is RGB565).	RGB565

Usage

from board_config import display_drv, broker display = Display(display_drv, broker)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

Methods:

refresh

refresh(area)

Copy a dirty region from the internal framebuffer to the physical display.

Parameters:

Name	Type	Description	Default
area	Area	Area or (x, y, w, h) rectangle to flush.	required

tick

tick()

Run one frame of the widget event loop.

Flushes dirty areas to the display, otherwise polls broker for events, runs scheduled tasks, and re-renders invalidated widgets. Call from a timer (see init_timer) or your main loop.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

changed

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

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.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

Screen

Screen(parent, fg=None, bg=None, visible=True)

Initialize a Screen object to contain widgets.

Parameters:

Name	Type	Description	Default
parent	Display	The display object that contains the screen.	required
fg	int	The foreground color of the screen.	None
bg	int	The background color of the screen.	None
visible	bool	The visibility of the screen.	True

Usage

screen = Screen(display)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

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

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.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

Button

Button(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, pressed_offset=2, pressed=False, label=None, text_color=None, text_height=TEXT_SIZE.LARGE, icon_file=None, icon_color=None)

Initialize a Button widget to display an icon and/or text.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this widget.	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.	None
align_to	Widget	The widget to align to.	None
fg	int	The foreground color of the widget.	None
bg	int	The background color of the widget.	None
visible	bool	The visibility of the widget (default is True).	True
value	Any	User-assigned value of the widget.	None
padding	tuple	The padding on each side of the widget.	None
radius	int	The corner radius of the widget (default is 0).	0
pressed_offset	int	The offset of the widget when pressed (default is 2).	2
pressed	bool	The state of the widget (default is False).	False
label	str	The text label of the widget.	None
text_color	int	The color of the text label.	None
text_height	int	The height of the text label (default is TEXT_SIZE.LARGE).	LARGE
icon_file	str	The icon file to display on the widget.	None
icon_color	int	The color of the icon.	None

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

draw

draw(_=None)

Draw the button background and shape only.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

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.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

Label

Label(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=None, padding=None, text_height=TEXT_SIZE.LARGE, scale=1, inverted=False, font_data=None)

Initialize a Label widget to display text.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this label.	required
x	int	The x-coordinate of the label.	0
y	int	The y-coordinate of the label.	0
w	int	The width of the label.	None
h	int	The height of the label.	None
align	int	The alignment of the label.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the text.	None
bg	int	The background color of the label.	None
visible	bool	The visibility of the label.	True
value	str	The text content of the label.	None
padding	tuple	The padding on each side of the label.	None
text_height	int	The height of the text (default is TEXT_SIZE.LARGE).	LARGE
scale	int	The scale of the text (default is 1).	1
inverted	bool	The inversion of the text (default is False).	False
font_data	str	The font file to use for the text.	None

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

draw

draw(_=None)

Draw the label's text on the screen, using absolute coordinates. Optionally fills the background first if bg is set.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

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.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

TextBox

TextBox(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=None, padding=None, format='', text_height=TEXT_SIZE.LARGE, scale=1, inverted=False, font_data=None)

Initialize a TextBox widget to display formatted text.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this text box.	required
x	int	The x-coordinate of the text box.	0
y	int	The y-coordinate of the text box.	0
w	int	The width of the text box.	None
h	int	The height of the text box.	None
align	int	The alignment of the text box.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the text.	None
bg	int	The background color of the text box.	None
visible	bool	The visibility of the text box.	True
value	str	The text content of the text box.	None
padding	tuple	The padding on each side of the text box.	None
format	str	The format string for the text.	''
text_height	int	The height of the text (default is TEXT_SIZE.LARGE).	LARGE
scale	int	The scale of the text (default is 1).	1
inverted	bool	The inversion of the text (default is False).	False
font_data	str	The font file to use for the text.	None

Usage

text_box = TextBox(screen, value="Hello, world!", format="{:>20}", text_height=TEXT_SIZE.LARGE)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

draw

draw(_=None)

Draw the label's text on the screen, using absolute coordinates.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

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.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

Icon

Icon(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=None, padding=None)

Initialize an Icon widget to display an icon. Currently only supports PBM files. PBM files are monochrome (1 bit per pixel) bitmaps.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this icon.	required
x	int	The x-coordinate of the icon.	0
y	int	The y-coordinate of the icon.	0
w	int	The width of the icon.	None
h	int	The height of the icon.	None
align	int	The alignment of the icon.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the icon.	None
bg	int	The background color of the icon.	None
visible	bool	The visibility of the icon.	True
value	str	The icon file to display.	None
padding	tuple	The padding on each side of the icon.	None

Usage

icon = Icon(screen, value="icon.pbm")

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

load_icon

load_icon(value)

Load icon file and store pixel data.

changed

changed()

Update the icon when the value (file) changes.

draw

draw(_=None)

Draw the icon on the screen.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

IconButton

IconButton(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=None, padding=None, icon_file=None)

Initialize an IconButton widget to display an icon on a button.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this icon button.	required
x	int	The x-coordinate of the icon button.	0
y	int	The y-coordinate of the icon button.	0
w	int	The width of the icon button.	None
h	int	The height of the icon button.	None
align	int	The alignment of the icon button.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the icon button.	None
bg	int	The background color of the icon button.	None
visible	bool	The visibility of the icon button.	True
value	str	The user-assigned value of the icon button.	None
padding	tuple	The padding on each side of the icon button.	None
icon_file	str	The icon file to display.	None

Usage

icon_button = IconButton(screen, icon_file="icon.pbm")

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

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

draw(_=None)

Draw the button background and shape only.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

Toggle

Toggle(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=False, padding=None, on_file=None, off_file=None)

An IconButton that toggles between two states (on and off). Serves as a base widget for ToggleButton, CheckBox, and RadioButton widgets but may be used on its own. Requires an on_file and optionally an off_file. If only a single file is provided, the widget will change colors when toggled, otherwise the icon will change.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this toggle button.	required
x	int	The x-coordinate of the toggle button.	0
y	int	The y-coordinate of the toggle button.	0
w	int	The width of the toggle button.	None
h	int	The height of the toggle button.	None
align	int	The alignment of the toggle button.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the toggle button.	None
bg	int	The background color of the toggle button.	None
visible	bool	The visibility of the toggle button.	True
value	bool	The initial state of the toggle button.	False
padding	tuple	The padding on each side of the toggle button.	None
on_file	str	The icon file to display when the button is on.	None
off_file	str	The icon file to display when the button is off.	None

Usage

toggle = Toggle(screen, on_file="on.pbm", off_file="off.pbm")

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

toggle

toggle(data=None, event=None)

Toggle the on/off state of the button.

changed

changed()

Update the icon based on the current on/off state.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

draw

draw(_=None)

Draw the button background and shape only.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

ToggleButton

ToggleButton(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=False, padding=None, size=ICON_SIZE.LARGE)

Initialize a ToggleButton widget.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this toggle button.	required
x	int	The x-coordinate of the toggle button.	0
y	int	The y-coordinate of the toggle button.	0
w	int	The width of the toggle button.	None
h	int	The height of the toggle button.	None
align	int	The alignment of the toggle button.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the toggle button.	None
bg	int	The background color of the toggle button.	None
visible	bool	The visibility of the toggle button.	True
value	bool	The initial state of the toggle button.	False
padding	tuple	The padding on each side of the toggle button.	None
size	int	The size of the toggle button (default is ICON_SIZE.LARGE).	LARGE

Usage

toggle_button = ToggleButton(screen, size=ICON_SIZE.LARGE)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

changed()

Update the icon based on the current on/off state.

draw

draw(_=None)

Draw the button background and shape only.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

toggle

toggle(data=None, event=None)

Toggle the on/off state of the button.

CheckBox

CheckBox(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=False, padding=None, size=ICON_SIZE.LARGE)

Initialize a CheckBox widget.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this check box.	required
x	int	The x-coordinate of the check box.	0
y	int	The y-coordinate of the check box.	0
w	int	The width of the check box.	None
h	int	The height of the check box.	None
align	int	The alignment of the check box.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the check box.	None
bg	int	The background color of the check box.	None
visible	bool	The visibility of the check box.	True
value	bool	The initial state of the check box.	False
padding	tuple	The padding on each side of the check box.	None
size	int	The size of the check box (default is ICON_SIZE.LARGE).	LARGE

Usage

check_box = CheckBox(screen, size=ICON_SIZE.LARGE)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

changed()

Update the icon based on the current on/off state.

draw

draw(_=None)

Draw the button background and shape only.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

toggle

toggle(data=None, event=None)

Toggle the on/off state of the button.

RadioGroup

RadioGroup()

Initialize a RadioGroup to manage a group of RadioButtons.

See Also

RadioButton

Methods:

add

add(radio_button)

Add a RadioButton to the group.

Parameters:

Name	Type	Description	Default
radio_button	RadioButton	The RadioButton to add to the group.	required

set_checked

set_checked(selected_button)

Ensure only the selected button is checked in the group.

Parameters:

Name	Type	Description	Default
selected_button	RadioButton	The RadioButton to check.	required

RadioButton

RadioButton(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=False, padding=None, size=ICON_SIZE.LARGE, group=None)

Initialize a RadioButton widget.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this radio button.	required
x	int	The x-coordinate of the radio button.	0
y	int	The y-coordinate of the radio button.	0
w	int	The width of the radio button.	None
h	int	The height of the radio button.	None
align	int	The alignment of the radio button.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the radio button.	None
bg	int	The background color of the radio button.	None
visible	bool	The visibility of the radio button.	True
value	bool	The initial state of the radio button.	False
padding	tuple	The padding on each side of the radio button.	None
size	int	The size of the radio button (default is ICON_SIZE.LARGE).	LARGE
group	RadioGroup	The RadioGroup to which this radio button belongs.	None

Usage

radio_group = RadioGroup() radio_button = RadioButton(screen, group=radio_group)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

toggle

toggle(data=None, event=None)

Toggle the checked state to true when clicked and uncheck other RadioButtons in the group.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

changed()

Update the icon based on the current on/off state.

draw

draw(_=None)

Draw the button background and shape only.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

ProgressBar

ProgressBar(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=0.0, padding=None, vertical=False, reverse=False)

Initialize a ProgressBar widget to display a progress bar.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this progress bar.	required
x	int	The x-coordinate of the progress bar.	0
y	int	The y-coordinate of the progress bar.	0
w	int	The width of the progress bar.	None
h	int	The height of the progress bar.	None
align	int	The alignment of the progress bar.	None
align_to	Widget	The widget to align to.	None
fg	int	The foreground color of the progress bar.	None
bg	int	The background color of the progress bar.	None
visible	bool	The visibility of the progress bar.	True
value	float	The initial value of the progress bar (0 to 1).	0.0
padding	tuple	The padding on each side of the progress bar.	None
vertical	bool	Whether the progress bar is vertical (True) or horizontal (False).	False
reverse	bool	Whether the progress bar is reversed (True) or not (False).	False

Usage

progress_bar = ProgressBar(screen)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

draw_ends

draw_ends()

Draw the circular ends of the progress bar.

draw

draw(_=None)

Draw the progress bar on the screen.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

Slider

Slider(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=0.0, padding=None, vertical=False, reverse=False, knob_color=None, step=0.1)

Initialize a Slider widget with a circular knob that can be dragged.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this slider.	required
x	int	The x-coordinate of the slider.	0
y	int	The y-coordinate of the slider.	0
w	int	The width of the slider.	None
h	int	The height of the slider.	None
align	int	The alignment of the slider.	None
align_to	Widget	The widget to align to.	None
fg	int	The foreground color of the slider.	None
bg	int	The background color of the slider.	None
visible	bool	The visibility of the slider.	True
value	float	The initial value of the slider (0 to 1).	0.0
padding	tuple	The padding on each side of the slider.	None
vertical	bool	Whether the slider is vertical (True) or horizontal (False).	False
reverse	bool	Whether the slider is reversed (True) or not (False).	False
knob_color	int	The color of the knob.	None
step	float	The step size for value adjustments.	0.1

Usage

slider = Slider(screen, vertical=True, step=0.1)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

draw

draw(_=None)

Draw the slider, including the progress bar and the circular knob.

event_callback

event_callback(data, event)

Handle user input events like clicks, dragging, and mouse movements.

adjust_value

adjust_value(value)

Adjust the slider value by one step in the specified direction.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

draw_ends

draw_ends()

Draw the circular ends of the progress bar.

ScrollBar

ScrollBar(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=0.0, padding=None, vertical=False, reverse=False, knob_color=None, step=0.1)

Initialize a ScrollBar widget with two arrow IconButtons and a Slider.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this scroll bar.	required
x	int	The x-coordinate of the scroll bar.	0
y	int	The y-coordinate of the scroll bar.	0
w	int	The width of the scroll bar.	None
h	int	The height of the scroll bar.	None
align	int	The alignment of the scroll bar.	None
align_to	Widget	The widget to align to.	None
fg	int	The foreground color of the scroll bar.	None
bg	int	The background color of the scroll bar.	None
visible	bool	The visibility of the scroll bar.	True
value	float	The initial value of the scroll bar (0 to 1).	0.0
padding	tuple	The padding on each side of the scroll bar.	None
vertical	bool	Whether the scroll bar is vertical (True) or horizontal (False).	False
reverse	bool	Whether the scroll bar is reversed (True) or not (False).	False
knob_color	int	The color of the knob.	None
step	float	The step size for value adjustments.	0.1

Usage

scroll_bar = ScrollBar(screen, vertical=True, step=0.1)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

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

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.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

DigitalClock

DigitalClock(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, value=None, padding=None, text_height=TEXT_SIZE.LARGE, scale=1)

Initialize a DigitalClock widget to display the current time.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this digital clock.	required
x	int	The x-coordinate of the digital clock.	0
y	int	The y-coordinate of the digital clock.	0
w	int	The width of the digital clock.	None
h	int	The height of the digital clock.	None
align	int	The alignment of the digital clock.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the digital clock.	None
bg	int	The background color of the digital clock.	None
visible	bool	The visibility of the digital clock.	True
value	str	The initial value of the digital clock.	None
padding	tuple	The padding on each side of the digital clock.	None
text_height	int	The height of the text (default is TEXT_SIZE.LARGE).	LARGE
scale	int	The scale of the text (default is 1).	1

Usage

clock = DigitalClock(screen, text_height=TEXT_SIZE.LARGE, scale=2)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

add_child

add_child(child)

Adds a child widget to the current widget.

changed

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

draw(_=None)

Draw the label's text on the screen, using absolute coordinates. Optionally fills the background first if bg is set.

remove_child

remove_child(widget)

Removes a child widget from the current widget.

ListView

ListView(parent, x=0, y=0, w=None, h=None, align=None, align_to=None, fg=None, bg=None, visible=True, padding=None)

Initialize a ListView widget to display a list of items.

Parameters:

Name	Type	Description	Default
parent	Widget	The parent widget or screen that contains this list view.	required
x	int	The x-coordinate of the list view.	0
y	int	The y-coordinate of the list view.	0
w	int	The width of the list view.	None
h	int	The height of the list view.	None
align	int	The alignment of the list view.	None
align_to	Widget	The widget to align to.	None
fg	int	The color of the list view.	None
bg	int	The background color of the list view.	None
visible	bool	The visibility of the list view.	True
padding	tuple	The padding on each side of the list view.	None

Usage

list_view = ListView(screen) button1 = Button(list_view, label="Button 1", value=1) button2 = Button(list_view, label="Button 2", value=2)

Attributes

area property

area

Absolute bounding box of the widget on screen.

Returns:

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

x property writable

x

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

y property writable

y

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

visible property writable

visible

Get widget visibility.

Methods:

add_child

add_child(child)

Adds a child widget to the current widget.

remove_child

remove_child(child)

Removes a child widget from the current widget.

reassign_positions

reassign_positions()

Reassign the positions of all children after one is removed.

config_scrollbar

config_scrollbar()

Configure the scrollbar based on the number of children.

scroll

scroll(sender)

Read the value of the scrollbar and scroll the list view accordingly.

scroll_up

scroll_up()

Scroll the list view up by one item.

scroll_down

scroll_down()

Scroll the list view down by one item.

changed

changed()

Update the list view when the value changes.

add_event_cb

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	int	eventsys.events constant (e.g. events.MOUSEBUTTONDOWN).	required
callback	callable	Callable invoked as callback(event, data).	required
data		User data passed to callback; defaults to this widget.	None

handle_event

handle_event(event, condition=None)

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

Parameters:

Name	Type	Description	Default
event	Event	The event to handle.	required
condition	callable	A function that returns True if the event should be handled by the child widget.	None

draw

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.

Functions:

tick

tick(_=None)

Function to call the tick method of all Display objects.

init_timer

init_timer(period=10)

Initialize the timer to call the tick function at regular intervals.

Parameters:

Name	Type	Description	Default
period	int	The period in milliseconds to call the tick function.	10

pump

pump()

Process one frame during setup bursts (before run_forever).

On queued backends, drains the multimer callback queue. In poll mode (no init_timer), also calls tick().

run_forever

run_forever()

Keep the widget loop alive on all platforms.

On queued/SDL backends, runs run_queued() forever. In poll mode (no init_timer), also calls tick() each iteration. On sync MCU with an active timer, returns immediately (the timer drives tick()).