Quickstart
Make a working plugin in five minutes, then read it line by line.
This page makes a small plugin that flips a coin, and then explains every line of it. You need no tools on your computer. The plugin editor runs in your browser and on the phone.
The whole plugin
Section titled “The whole plugin”import randomfrom wm import plugin, ui
state = plugin.state(result="Press Flip")
def flip(): state.result = random.choice(["Heads", "Tails"])
def render(): with ui.column(): ui.title(state.result) ui.button("Flip", on_click=flip, primary=True)That is all of it. The keyboard shows a title and a button. Press the button and the title says Heads or Tails.
Run it
Section titled “Run it”-
Open the plugin editor.
-
Under Start from, choose A blank plugin. Type a name and press Create.
-
Open the menu (⋮) and choose Name and permissions. Turn on Use API 5 (the wm package). Press Save.
-
Delete the code in the editor. Paste the code from above.
-
Look at the Preview beside the code. Press Flip.
With Run as you type on, the preview runs your code again each time you stop typing. Errors show in the Console tab under the code.
-
Open the editor:
WM Keyboard Tools Plugins Write a plugin -
Choose A blank plugin. Type a name and press Create.
-
Open the menu (⋮) and choose Name and permissions. Turn on Use API 5 (the wm package). Press Save.
-
Replace the code with the code from above.
-
Press the run button. The preview shows the panel. Press Flip.
-
Press Install the plugin to put it in the keyboard’s Plugins tool.
What each line does
Section titled “What each line does”import randomrandom is part of the Python that plugins get. It picks things by chance.
The API reference lists every module
you can import.
from wm import plugin, uiwm is the keyboard’s own package. plugin is your plugin itself: its state,
its timers and its buttons. ui draws the panel.
state = plugin.state(result="Press Flip")state holds the values your plugin needs to remember while its panel is open.
Here there is one value, result, and it starts as "Press Flip". You read
and change it as state.result.
def flip(): state.result = random.choice(["Heads", "Tails"])A plain function. It sets result to Heads or Tails. Nothing calls it yet.
def render():The keyboard calls render() to find out what the panel looks like. It calls
it once when the panel opens, and again after anything happens.
with ui.column(): ui.title(state.result) ui.button("Flip", on_click=flip, primary=True)A column with two things in it, top to bottom: a title that shows result,
and a button. on_click=flip tells the keyboard to call flip when the user
presses the button. primary=True gives it the theme’s main colour.
So the loop is this:
- The keyboard calls
render()and draws the title and the button. - You press Flip. The keyboard calls
flip(), which changesstate.result. - The keyboard calls
render()again, and the title shows the new result.
You never change the screen yourself. You change state, and render()
describes what the panel looks like now.
Make it yours
Section titled “Make it yours”Try these small changes. Each one takes a line or two.
- Count the flips. Add
flips=0toplugin.state(...), addstate.flips += 1inflip(), and show it withui.caption(f"{state.flips} flips"). - Let the user put the result in their text. Add
ui.output(state.result)inrender(). The keyboard draws an Insert button under it, and no permission is needed. - Roll a die instead. Use
str(random.randint(1, 6)).
