Panels

The loop

A panel defines view(state), and optionally initial(), on_open(state) and on_action(action, state). Clink calls initial() once for the starting state, on_open each time the panel appears, then view(state) to build the interface. A control either inserts text where you are writing, sets new state, or names an action for on_action to handle, and the view is built again.

def initial():
    return {"count": 0, "step": 1}

def view(state):
    return vstack([
        text(f"{state['count']}", size=34, weight="bold", align="center"),
        segmented(["1", "5", "10"], value=str(state["step"]), action="step"),
        hstack([
            button("−", "bump", value=-1),
            button("+", "bump", value=1, style="primary"),
        ]),
        button("Type it", "type", icon="keyboard"),
    ])

def on_action(action, value, state):
    if action == "bump":
        state["count"] = state["count"] + value * state["step"]
    elif action == "step":
        state["step"] = int(value)
    elif action == "type":
        insert(str(state["count"]))
        close()
    return state

Calculators, snippet boards, pickers: your panels appear behind the keyboard's panel button.

Builders

view(state) returns nodes made by these 19 functions. Nest them freely: stacks and grids take a list of children.

Handling a tap

A control that has to work something out names an action instead of carrying a literal set. Clink then calls on_action(action, state), or on_action(action, value, state) when you want the value the control carries. State is an ordinary dictionary, so you can change it in place and return nothing, or return a new one.

def initial():
    return {"items": [], "draft": ""}

def view(state):
    return vstack([
        field("draft", placeholder="Add one…", submit="add"),
        scroll([row(item, action="use", value=item) for item in state["items"]]),
    ])

def on_action(action, value, state):
    if action == "add" and value:
        state["items"].append(value)
        state["draft"] = ""
    elif action == "use":
        insert(value)
        close()
    return state

Asking the keyboard

From on_action and on_open a panel can ask the keyboard for things a return value cannot express. Each call is recorded and applied after your function returns, so a panel never edits the field while its own view is being built.

Commands

• insert()
• backspace()
• delete_word()
• replace()
• move_cursor()
• copy()
• close()
• haptic()
• toast()

def on_action(action, state):
    if action == "quote":
        word = context()["word"]
        replace(len(word), "“" + word + "”")
        haptic("light")
    return state

State

State is an ordinary dictionary, and it holds whatever a script can build: numbers, strings, booleans, None, and lists and dictionaries of them. It is handed back to you on every call, so a list you appended to on one tap is still there on the next.

def initial():
    return {"name": ""}

def view(state):
    return vstack([
        field("name", placeholder="Who?"),
        button("Greet", insert="Hi " + state["name"] + "!", style="primary"),
    ])

Remember state keeps what the panel holds between openings, and between keyboard launches. Leave it off for a calculator; turn it on for a list.

Limits

Each panel render has a 2,000,000-step limit. If a script runs too long, Clink shows an error. Keep loops finite and reduce repeated work if your panel reaches the limit.

A panel that arrives as a file or from a repository is checked before it is stored. It has to be under 48,000 bytes and 1,200 lines, it has to define def view(, every import has to name one of the sandboxed namespaces, and these fragments are refused outright:

Refused in a shared panel

• __
• exec(
• eval(
• open(
• compile(

Importable in a shared panel

• json
• math
• random
• re
• sys
• time

Placement

Give each panel its own button in the picker instead of nesting them behind one Panels button. Individual panels can override this in their editor.

Default follows that switch, Standalone always takes its own button, and Grouped always nests.

Writing one

1. Open Custom Panels in Clink and tap New panel.
2. Write the script. A live preview runs the real panel beside it, and errors show as you type.
3. Save, switch the panel on, then open the panel button on the keyboard.

Open the panel in Plugins and select its Share tab to open the export popup and send its QR card. Choose File in the popup to export a .clinkpanel file, which is JSON. Opening one back in Clink stores it with a fresh id, so importing the same panel twice never overwrites the first.