Drawing the panel
How render() works, how to lay widgets out, and which widget to reach for.
Your plugin never draws pixels. It describes the panel with widgets, and the keyboard draws them in the user’s theme. This page covers how that works and which widget fits which job. Every widget and its arguments are listed in the API reference.
render() describes the panel
Section titled “render() describes the panel”Write a function called render. The keyboard calls it when the panel opens,
and again after every event: a press, a change, a timer, an answer from the
internet. Each call draws the panel from scratch.
from wm import plugin, ui
state = plugin.state(count=0)
def add(): state.count += 1
def render(): with ui.column(): ui.title(f"{state.count} presses") ui.button("Add one", on_click=add)So render() should only read state and create widgets. Change state in
callbacks, not in render(). A render() that changes state, or that calls
the internet, runs again and again.
Two ways to build the tree
Section titled “Two ways to build the tree”With blocks. Open a container with with, and every widget you create
inside it goes in, in order:
def render(): with ui.card(title="Today"): ui.stat("Now", "21°", caption="Dhaka") with ui.row(): ui.button("Refresh", on_click=refresh) ui.button("Share", on_click=share_it)Nested calls. Pass children as arguments, and return the top widget:
def render(): return ui.card( ui.stat("Now", "21°", caption="Dhaka"), ui.row( ui.button("Refresh", on_click=refresh), ui.button("Share", on_click=share_it), ), title="Today", )Both give the same panel. with blocks read better when there are if and
for inside. You can mix them. When render() returns nothing, the panel is
everything you created at the top level.
Layout
Section titled “Layout”| Widget | Use it for |
|---|---|
ui.column(...) | Things top to bottom. The usual outer container. |
ui.row(..., weights=[3, 1]) | Things side by side. A row of buttons splits the width evenly; next to a box, a button keeps its own width. weights shares out the width yourself; a weight of 0 keeps that child at its own width, as weights=[1, 0] does for a box with an icon button beside it. A button on a line of its own runs the panel’s width. A one-character label (a symbol palette’s ∫, ≤) is drawn larger than a word. A label too long for its button narrows its letters first, then gets smaller, and is cut short with ”…” only after both; the user can change that under Appearance › Toolbar › Long words. |
ui.grid(..., columns=3) | A grid of equal cells: buttons, stats, pictures. |
ui.card(..., title=, on_click=) | A group that belongs together. Pressable with on_click. |
ui.section(title, ..., collapsible=True) | A titled part of a long panel that the user can fold. |
ui.scroll(..., height=200) | A part that scrolls on its own. |
ui.tabs(ui.page("One", ...), ui.page("Two", ...)) | Pages the user switches between. |
ui.spacer(16), ui.divider() | Space and a line. |
gap= sets the space between children of a column or row, and align= lines
them up.
ui.title(text)andui.label(text)show text.ui.caption(text)is small and quiet.ui.label(text, style=, color=)covers the rest.ui.markdown(text)shows simple Markdown:#headings,-bullets,**bold**,*italic*and`code`. Links show as plain text.ui.output(text)shows a result with Insert and Copy buttons under it. This is how a plugin puts text into what the user is writing without any permission: the user presses Insert. Passmono=Truefor code.
| Widget | The callback hears |
|---|---|
ui.input(label=, value=, on_change=, on_submit=, multiline=, kind=) | the text |
ui.search(placeholder=, on_submit=) | the text |
ui.button(text, on_click=, primary=, icon=), ui.icon_button(icon, on_click=, label=) | nothing |
ui.toggle(label, value, on_change=), ui.checkbox(...) | True or False |
ui.slider(value, min=, max=, step=, on_change=), ui.stepper(...) | the number |
ui.select(options, value=, on_change=, style="segmented") | the chosen value |
ui.chips(options, value=, multi=True, on_change=) | a value, or a list with multi |
ui.date(label=, value=, time=True, on_change=) | seconds since 1970, or None |
ui.keys(rows, on_press=) | the key’s label |
The keyboard types into a plugin’s ui.input, the same way it types into an
app. Three things about text boxes:
- Without
on_change, the plugin hears nothing while the user types. It gets the text when they press Enter, throughon_submit. Use this when you only need the finished text: it saves a redraw on every key. - With
on_change, every key press is an event. Keep the text in state and pass it back asvalue=, or the box empties on the next draw. kind="number","email","url"or"password"changes the keys the keyboard offers. A password box shows dots and is never logged.- A long line scrolls sideways to keep its end in view, as an app’s text field
does. The
placeholderis drawn faint, with the caret before it.
A select drawn as a dropdown opens its options over the panel, under the box
(or above it, near the bottom), and a tap anywhere else closes them; nothing
below is pushed down. With style="segmented", the chosen segment’s fill and
check slide in. Tabs share the width, up to six of them, with their titles
narrowed to fit, and a page slides in from the side of the tab tapped.
An output puts its Copy and Insert buttons above the text, so a long result
can be taken without scrolling past it.
Options for select and chips are a list of values, or of
(value, label) pairs when the text shown differs:
ui.select([("c", "Celsius"), ("f", "Fahrenheit")], value=state.unit).
ui.list shows rows made with ui.item. A row has a title, and can have a
subtitle, an icon, text on the right, and actions. The actions show when the
user presses the ⋯ button at the end of the row:
def render(): ui.list( [ ui.item(note["text"], subtitle=note["when"], icon="sticky_note_2", on_click=lambda n=note: open_note(n), actions={"Delete": lambda n=note: delete(n)}) for note in state.notes ], empty="No notes yet", )Pictures, numbers and drawings
Section titled “Pictures, numbers and drawings”ui.image(src, alt=, height=)shows a picture you bundle in the plugin ("assets/logo.png") or bytes you made. See Sharing your plugin for bundling.ui.icon(name)shows a Material Symbols icon by name, such ascloud,deleteorhistory. The icon the keyboard draws for your plugin itself, on its tool, is set in the manifest instead: see Your icon.ui.qr(text)draws a QR code.ui.stat(label, value, caption=)shows one big number.ui.ring(0.7, label=)shows a share as a ring.ui.progress(0.4)shows a bar;ui.progress()shows one that only says “working”.ui.chart([3, 5, 2], kind="bar", labels=[...])draws a line, bar or spark chart. Pass a dict for several series.ui.canvas(width, height, shapes, on_tap=, on_drag=, on_hold=)draws shapes made withui.rect,ui.circle,ui.lineandui.text_at. Coordinates are in your own units, scaled to fit. See the Tap the dot example. A canvas that takes drags also takes the swipes that would scroll the panel; passdrag_after_hold=Trueand a drag starts only after a long press, the way events move in the Calendar tool’s Day view.ui.empty(text, action=, on_click=)fills an empty screen with a message and a button, like “No notes yet. Add one”.
Colours are roles
Section titled “Colours are roles”You cannot pick a colour by value. Pass a role, and the keyboard maps it to the
user’s theme: primary, secondary, muted, danger, success, warning
or accent.
ui.label("Saved", color="success")ui.button("Delete all", on_click=wipe, color="danger")This keeps every plugin readable in every theme, light or dark, and stops a
plugin from imitating a system warning. Anything else raises ValueError.
Messages
Section titled “Messages”ui.toast(text)shows a short message over the panel.ui.dialog(title, text, buttons=("Delete", "Cancel"), on_result=fn)asks a question over the panel, with your plugin’s name above the title. Up to three buttons; list the answer first, as in("Delete", "Cancel"): it is drawn filled at the right, where Android puts an alert’s confirming button.fngets the label the user pressed, orNoneif they tapped outside it or the panel closed.
def ask_to_clear(): ui.dialog("Delete every note?", "This cannot be undone.", buttons=("Delete", "Cancel"), on_result=answered)
def answered(choice): if choice == "Delete": state.notes = []Limits
Section titled “Limits”A draw can hold up to 1,024 widgets and 128K characters of text. Past that the
keyboard drops or shortens what does not fit and notes it under the panel.
render() gets 1.2 million steps and half a second. A step is about one line
of Python or one turn of a loop. For long lists, show the first 100 rows and a
search box.
