How pdwidgets works

pdwidgets is a widget toolkit written in pure Python, for touchscreen, desktop and browser interfaces. It builds buttons, forms, navigation, charts, dialogs and layout containers on an OmniPython display driver and pygraphics, with no native code to compile.

A widget tree

An application is a tree. appdev.App owns input and timers, a Display joins it to a display driver, a Screen fills the display, and widgets nest inside the screen. Each widget has a parent, a rectangle, and a list of children.

Display connects a board’s display driver to the shared app coordinator, so the app owns input and the periodic redraw. That is why most programs never call a draw function: they create widgets, set value and register callbacks, and the app does the rest. Your first program builds one.

How a frame moves

input -> appdev.App -> Display -> widget hit test -> callback
                                |
widget state change -> dirty Area -> render tick -> driver flush

A widget changing a property marks itself invalid. The change climbs to the Display, which draws only the invalid widgets into an off-screen buffer on its next tick and then copies only the changed rectangles, each an Area, to the panel. A static screen costs nothing per frame. The architecture page follows one frame through the code.

Call pd.tick() to force a frame by hand, such as when setup needs a render before the app’s loop has started.

What it costs

Display keeps one buffer the size of the panel at the panel’s color depth, so a 320 by 480 panel at 16 bits is 307,200 bytes. That’s a large allocation on a small board, so pdwidgets suits boards with PSRAM, or a smaller panel.

The top-level pdwidgets module loads the core eagerly and each widget class the first time you name it. On a board short of memory, import the widget you need directly, such as from pdwidgets.widgets.button import Button.

Themes and layout

Layout uses ALIGN, pct, Row, Column and Grid, so a screen follows its panel’s size; see Lay out widgets. Colors come from a Material Design palette each display builds with palettes, and from color roles on the display; see Theme an app. Widget is also a plain container, and a subclass keeps its hit testing and redraw behavior, so a custom widget stays on the normal event and invalidation path instead of adding a render loop of its own.

What it depends on

pdwidgets imports appdev from OmniPython, palettes and pygraphics. Install brings them in. To work on pdwidgets itself, see CONTRIBUTING.md.