Architecture
The widget tree, the dirty-rectangle drawing pipeline and the event path.
The widget tree
Every pdwidgets UI is a tree: an App controller, a Display, the active Screen and nested Widget containers.
graph TD
App["appdev.App<br/>(Event Loop & Async Timers)"] --> Display["pdwidgets.Display<br/>(Display Driver & Viewport)"]
Display --> Screen1["pdwidgets.Screen (Active)"]
Screen1 --> AppBar["pd.AppBar / Header"]
Screen1 --> Container["pd.Card / ScrollView"]
Container --> Btn["pd.Button"]
Container --> Slider["pd.Slider"]
Container --> Label["pd.Label"]
The three core classes:
Display: Glues the physical display driver (display_drv) to the application event loop. Owns the focus manager and routes input events to widgets.Screen: One full-display page. A display shows one at a time: assigndisplay.active_screen = new_screento switch.Widget: The base class for all UI elements. Owns geometry (x, y, w, h), visibility, parent/child relationships, background color, corner radius, and event callbacks.
Drawing: dirty rectangles
pdwidgets avoids full-screen redraws by tracking dirty rectangles. Widgets draw into a buffer the size of the panel, and only the changed rectangles are copied to the panel:
sequenceDiagram
participant Code as Your code
participant Widget as pd.Widget
participant Display as pd.Display
participant Panel as Display driver
Code->>Widget: widget.value = "New text"
Widget->>Display: Invalidated, flagged dirty up the tree
Note over Display: Timer tick
Display->>Widget: Draw invalid widgets into the buffer
Display->>Display: Record each widget's Area as dirty
Note over Display: Next tick
Display->>Panel: Copy each dirty Area, then show()
What each step does:
Changing a property, such as
widget.value = "..."orwidget.bg = 0xF800, marks the widget and its children invalid and flags the widget dirty in each ancestor.A tick that finds nothing waiting to be copied runs due tasks, then redraws the invalid widgets, front to back in
childrenorder, into the buffer. Each redrawn widget’sAreajoins the dirty list.The next tick merges dirty areas that touch or overlap and copies each to the driver, then calls the driver’s
show().The app drives
tick()from a shared timer every 10 ms by default (Display.tick_period), so once the app is running, redraws just happen.Before the app’s loop starts, call
pd.tick()yourself to render intermediate states.
Input
Input events from touch screens, mouse pointers, rotary encoders and keyboards reach the widget under them:
flowchart LR
Input[Touch / Mouse / Key] --> App[appdev.App]
App --> Display[pd.Display]
Display --> HitTest{Hit Test on Screen}
HitTest -->|Inside Bounds| Widget[Target Widget]
Widget --> Callback[Registered Callback]
The event types a widget can receive are listed in Events.
Callbacks registered with add_event_cb receive (sender, event):
def button_handler(sender, event):
print(f"Widget {sender} received event {event.type}")
button.add_event_cb(pd.events.MOUSEBUTTONUP, button_handler)