Skip to content
WM KeyboardWM Keyboard
Accessibility

State and events

Keep values between presses with plugin.state, and react to the user with callbacks.

A plugin is a loop. The keyboard draws the panel, the user does something, your code changes some values, and the keyboard draws the panel again. This page covers the two halves of that loop: where the values live, and how your code hears the user.

Every widget the user can act on takes a function. The keyboard calls it when the user acts, then draws the panel again:

from wm import plugin, ui
state = plugin.state(name="", dark=False)
def set_name(text):
state.name = text
def set_dark(on):
state.dark = on
def render():
with ui.column():
ui.input(label="Name", value=state.name, on_change=set_name)
ui.toggle("Dark mode", value=state.dark, on_change=set_dark)
ui.label(f"Hello, {state.name or 'stranger'}")

What a callback gets depends on the widget:

CallbackOnGets
on_clickbutton, card, item, image, emptynothing
on_holdbutton, icon button, cardnothing, after a long press; in the web editor, a right-click
on_changeinput, search, toggle, checkbox, slider, stepper, select, chips, date, tabsthe new value
on_submitinput, searchthe text, when the user presses Enter
on_selectlistthe index of the row pressed
on_presskeysthe key’s label
on_tapcanvasx and y, as two arguments
on_dragcanvasa dict: x, y, dx, dy and phase
on_holdcanvasx and y, as two arguments, after a long press

A function that takes no arguments works for any widget: the keyboard leaves the value out. So on_change=refresh works with a def refresh(): that takes nothing.

For a one-line change, a lambda saves a function:

ui.button("Reset", on_click=lambda: state.update(count=0))
ui.slider(state.size, min=8, max=32, on_change=lambda v: setattr(state, "size", v))

A lambda cannot hold =, which is why the second line uses setattr. Once it reads awkwardly, write a named function instead. In a loop, bind the loop variable as a default, or every lambda sees the last value:

for i, name in enumerate(state.names):
ui.button(name, on_click=lambda i=i: pick(i))

plugin.state(...) makes an object that holds named values. Give each one a starting value:

state = plugin.state(count=0, items=[], query="")

Then read and change them as attributes. You never need global:

def add(text):
state.items.append(text)
state.count += 1

It also works like a dict where that is handier:

state["count"]read a value by name
"count" in statewhether a value exists
state.update(count=0, query="")change several at once
state.as_dict()every value, as a plain dict

Pass persist=True and the values are saved on the phone after every event. The next time the panel opens, they come back. This needs the storage permission:

saved = plugin.state(notes=[], theme="auto", persist=True)
  • Values must be things JSON can hold: strings, numbers, True, False, None, lists and dicts.
  • Saving happens after each event. Call saved.save() to save at once, for example before a slow call.
  • Keep values that only make sense while the panel is open, such as “loading”, in a second state without persist. If the panel closes halfway through, a saved “loading” would come back stuck.
  • Two saved states need different names: plugin.state(persist=True, key="prefs", ...).
  • Saved state counts against your storage quota.

A variable at the top of your file also keeps its value while the panel is open. To change it inside a function, Python needs global:

count = 0
def add():
global count
count += 1

Leave out global and Python makes a new local count instead, with no error. That is the main reason to prefer plugin.state.

A text box shows what the user typed. Two rules keep it right:

  • Pass value=state.text and keep the text in state from on_change. The box then keeps its text when the panel draws again.
  • To clear or replace the box from code, change state.text. The box shows the new value on the next draw.

A box without on_change sends nothing while the user types. Its text arrives in on_submit when they press Enter. This costs less, and is right for a search box.

The keyboard needs to tell widgets apart from one draw to the next. It makes an id from each widget’s type and text, so you rarely think about it. Pass key= when two widgets would look the same, or when a box’s label changes but it is still the same box:

ui.input(label=f"Item {n}", key="new-item", on_submit=add)

Any event that no callback took goes to a function called on_event, if you write one. It gets the event as a dict:

def on_event(e):
print(e.type, e.get("id"), e.get("value"))

You rarely need it with API 5. It is how plugins written for API 4 work, and it can be handy while you learn what the keyboard sends. The Events tab in the web editor shows every event too.

After each of these, the keyboard calls render() again:

  • a callback or on_event
  • a timer from @plugin.every or plugin.after
  • an answer that arrives through then=
  • the panel opening, after @plugin.on_open

If something else changes what you show, call plugin.refresh(). You will rarely need to.