Plugin

Automazioni

L’oggetto automation facoltativo in un file .clinkplugin dichiara eventi, stato, impostazioni, comandi, preimpostazioni e slot per scorciatoie. Ogni contributo ha un ID stabile, una versione esatta dello schema e titoli localizzati. L’host crea nomi nel formato plugin/<plugin-id>/<kind>/<id>. Un plugin non può usare lo spazio dei nomi del sistema o di un altro plugin.

Come funzionano i plugin

Un pannello sostituisce i tasti, e un'azione gira una volta su un pezzo di testo. Un plugin non ha una schermata propria sulla tastiera. Clink chiama le sue funzioni in momenti precisi, per esempio quando la tastiera si apre o quando finisci una parola, e il plugin può aggiornare la barra spaziatrice o il proprio stato salvato. Le sue impostazioni vengono disegnate nell'app con gli stessi costruttori dei pannelli. WPM Spacebar, qui sotto, è un plugin completo.

def initial():
    return {"on": False}

def settings(state):
    return section("keys.spacebar", [
        toggle("Show typing speed", state["on"], action="toggle"),
    ], title="WPM Spacebar")

def on_action(action, value, state):
    state["on"] = value
    if value:
        claim("spacebar.text")
    else:
        release("spacebar.text")
        space_text(None)
    return state

def on_word(word, state):
    if state["on"]:
        space_text(f"{stats()['wpm']} wpm")
    return state

I plugin richiedono Clink Pro. Prima di installarne uno da un repository, Clink ti chiede di consentire il codice di quel repository, come fa per pannelli e azioni.

on_key e on_word ricevono ciò che scrivi: è così che funziona un contatore di parole. PyMini non ha accesso alla rete né ai file, quindi un plugin non può inviare ciò che scrivi via internet, e ciò che salva resta in Clink sul tuo dispositivo.

Il tuo primo plugin

La via più rapida è lo script di partenza che l'app scrive per te. Mette un interruttore in Tasti > Barra spaziatrice e, finché è acceso, conta le parole sulla barra spaziatrice. Cinque passi, nessun file da scaricare.

1. Apri la scheda Plugin, attiva i plugin in alto e tocca + per un nuovo plugin.
2. L'editor si apre sullo script di partenza. Leggilo una volta: initial(), settings(), on_action(), on_open() e on_word() sono tutto.
3. Passa all'anteprima. Attiva l'interruttore, poi tocca on_open e on_word qualche volta e guarda la barra spaziatrice simulata e la console.
4. Salva. Il plugin è attivo nell'elenco e il suo interruttore ora sta anche in Tasti > Barra spaziatrice.
5. Apri la tastiera ovunque e scrivi. La barra spaziatrice conta insieme a te.

def initial():
    return {"on": False, "words": 0}

def settings(state):
    return section("keys.spacebar", [
        toggle("Count words on the space bar", state["on"], action="toggle"),
    ], title="Word count")

def on_action(action, value, state):
    if action == "toggle":
        state["on"] = value
        if value:
            claim("spacebar.text")
        else:
            release("spacebar.text")
            space_text(None)
    return state

def on_open(state):
    state["words"] = 0
    if state["on"]:
        space_text("0 words")
    return state

def on_word(word, state):
    state["words"] += 1
    if state["on"]:
        space_text(f"{state['words']} words")
    return state

Hook

Definisci quelle che ti servono fra queste 33 funzioni e tralascia le altre. Ognuna riceve state come ultimo argomento. Quelle che reagiscono a qualcosa restituiscono state, modificato o no. Quelle che rispondono a una domanda (elements, draw, effects, gli hook di aspetto, haptics, hitboxes, suggestions e correct) restituiscono la loro risposta, e possono comunque modificare state sul posto.

def on_key(key, state):
    if key == " " and setting("language") == "en":
        state["spaces"] = state.get("spaces", 0) + 1
    return state

def on_close(state):
    haptic("light")
    return state

L'app e la tastiera condividono un'unica copia dello stato. Se attivi un interruttore nell'app, è attivo alla prossima apertura della tastiera. Quello che la tastiera conta è lì la prossima volta che apri le impostazioni del plugin. La tastiera salva lo stato quando si chiude, non dopo ogni tasto.

Suggerimento attuale sulla barra spaziatrice

Leggi il suggerimento principale visualizzato con context()["suggestion"]. Iscriviti all’evento predictions per ricevere le modifiche in info["suggestion"]. Entrambe le operazioni richiedono l’accesso ai dati di digitazione. on_suggestion viene eseguito quando si accetta un suggerimento, non quando cambiano le previsioni. Usa space_text(value or None) per impostare l’etichetta o ripristinarla quando non ci sono suggerimenti. L’azione della barra spaziatrice non cambia.

def initial():
    return {}

def events(state):
    return ["predictions"]

def on_open(state):
    space_text(context()["suggestion"] or None)
    return state

def on_event(name, info, state):
    if name == "predictions":
        space_text(info["suggestion"] or None)
    return state

def on_close(state):
    space_text(None)
    return state

Stato

Lo stato è un unico dict. initial() lo costruisce la prima volta; poi ogni hook riceve lo stesso dict, lo modifica e lo restituisce. Contiene tutto ciò che JSON può contenere: numeri, stringhe, liste, dict annidati. L'app lo salva dopo ogni controllo che usi, la tastiera quando si chiude, ed entrambi leggono lo stesso file, quindi non restano mai in disaccordo a lungo.

def initial():
    return {"session": 0, "total": 0, "longest": ""}

def on_open(state):
    state["session"] = 0        # starts over each time the keyboard opens
    return state

def on_word(word, state):
    state["session"] += 1
    state["total"] += 1         # survives, it is saved when the keyboard closes
    if len(word) > len(state["longest"]):
        state["longest"] = word
    return state

def settings(state):
    return vstack([
        text(f"{state['total']:,} words so far"),
        text(f"Longest: {state['longest'] or '...'}", size=13, color="gray"),
        button("Start over", "reset", style="destructive"),
    ])

def on_action(action, value, state):
    if action == "reset":
        return initial()
    return state

Restituire lo stato è l'abitudine da tenere, ma non è strettamente necessario: il dict è un riferimento, quindi funziona anche modificarlo sul posto. Restituisci un dict diverso, come initial() qui sopra, e quello diventa lo stato.

Impostazioni e sezioni

settings(state) restituisce un albero di nodi fatto con i costruttori dei pannelli: text, toggle, slider, stepper, segmented, button, row, field e i layout. Compare nella pagina del plugin, nella scheda Plugin. Se ne avvolgi una parte in section(anchor, children, title), quella parte compare anche in una delle schermate di impostazioni di Clink, accanto all'impostazione a cui si riferisce.

def settings(state):
    return vstack([
        text("Counts words as you type.", size=13),
        section("keys.spacebar", [
            toggle("Count on the space bar", state["on"], action="toggle"),
            stepper(state["goal"], min=10, max=500, step=10, label="Goal", key="goal"),
        ], title="Word count"),
    ])

I controlli di cui un plugin ha più spesso bisogno. Ognuno scrive il suo nuovo valore nello stato sotto key, oppure indica una action per on_action, o entrambe le cose. L'elenco completo dei costruttori, layout compresi, è nella pagina dei pannelli.

Dove vanno le sezioni

Un'ancora è l'ID di una scheda in una delle schermate di impostazioni di Clink. Indicala in section() e i controlli del plugin vengono disegnati subito sotto quella scheda, con il nome del plugin sopra. Il modo più semplice per trovarne una: nell'app, apri Altro > Sviluppatore e attiva Mostra gli ID. Ogni scheda riceve un piccolo badge informativo che ne indica l'ID e lo copia al tocco; le pagine mostrano il proprio nella barra del titolo.

keys.spacebar ha un posto tutto suo, nella schermata della barra spaziatrice. Una sezione con un'ancora non in questo elenco compare comunque nella pagina del plugin, quindi un refuso ti costa una scheda, non il plugin.

Prese di controllo

Quando un plugin guida una delle impostazioni di Clink, la persona dovrebbe vederlo, e i due non dovrebbero litigare. claim(control) dice che il plugin ne è proprietario: l'app indica il plugin sulla scheda di quell'impostazione, e il campo del testo della barra spaziatrice resta bloccato finché lo tiene. release(control) la restituisce. Prendi nel on_action che accende la tua funzione, rilascia in quello che la spegne, e riporta il valore a None o al suo valore precedente nello stesso momento. Un plugin disattivato nell'elenco rilascia tutto ciò che teneva.

def on_action(action, value, state):
    if action == "toggle":
        state["on"] = value
        if value:
            claim("spacebar.text")
            space_text("...")
        else:
            release("spacebar.text")
            space_text(None)      # hand the person's own text back
    return state

Due plugin possono prendere lo stesso controllo; l'app indica quello che lo ha preso per ultimo. Le prese di controllo sono registrate dall'app, quindi prendi da on_action, che gira lì. Una presa fatta dentro la tastiera non viene ricordata.

Comandi e letture

I plugin possono usare tutti i comandi dei pannelli, più sei comandi e due letture tutti loro. I comandi vengono messi in coda e applicati quando la tua funzione è terminata, quindi niente cambia sulla tastiera a metà di una chiamata. Le letture restituiscono i valori com'erano subito prima della chiamata.

setting(name) e set_setting(name, value) condividono un unico elenco di nomi, e anche claim(control) accetta uno qualsiasi di essi. I booleani si leggono come True o False, i numeri come numeri, le scelte come il loro id. L'elenco è lungo apposta: un plugin può reagire a quasi tutto ciò che una persona può impostare nell'app, o guidarlo.

Come view() di un pannello, settings() deve solo descrivere i controlli. I comandi chiamati da lì vengono ignorati e registrati nella console.

Esempi

Cinque piccoli plugin, ognuno completo. Incollane uno in un nuovo plugin, salva, e gira.

def initial():
    return {"on": True}

def settings(state):
    return section("keys.spacebar", [
        toggle("Language on the space bar", state["on"], action="toggle"),
    ], title="Language badge")

def on_action(action, value, state):
    if action != "toggle":
        return state
    state["on"] = value
    if value:
        claim("spacebar.text")
        space_text(setting("language").upper())
    else:
        release("spacebar.text")
        space_text(None)
    return state

def on_open(state):
    if state["on"]:
        space_text(setting("language").upper())
    return state

def on_language(code, state):
    if state["on"]:
        space_text(code.upper())
    return state

SHORTCUTS = {"omw": "on my way", "brb": "be right back", "ty": "thank you"}

def on_key(key, state):
    if key != " ":
        return state
    words = context()["before"].split()
    if words and words[-1] in SHORTCUTS:
        # the space is already in the text, so it goes too and comes back after
        replace(len(words[-1]) + 1, SHORTCUTS[words[-1]] + " ")
    return state

def initial():
    return {"goal": 200, "count": 0}

def settings(state):
    return vstack([
        stepper(state["goal"], min=50, max=2000, step=50, label="Words per session", key="goal"),
        progress(state["count"], total=state["goal"], label=f"{state['count']} of {state['goal']}"),
    ])

def on_open(state):
    state["count"] = 0
    return state

def on_word(word, state):
    state["count"] += 1
    if state["count"] == state["goal"]:
        haptic("medium")
        banner("Goal reached")
    return state

def initial():
    return {"muted": False, "was_on": True}

def on_field(kind, state):
    # a password or a number field is not a place for key sounds
    quiet = kind in ("password", "number", "phone")
    if quiet and not state["muted"]:
        state["was_on"] = setting("sound.enabled")
        state["muted"] = True
        set_setting("sound.enabled", False)
    elif not quiet and state["muted"]:
        state["muted"] = False
        if state["was_on"]:
            set_setting("sound.enabled", True)
    return state

NAMES = ["sam", "ana", "team"]

def on_key(key, state):
    typing = context()["before"].split(" ")[-1]
    if typing.startswith("@"):
        start = typing[1:].lower()
        suggest([n for n in NAMES if n.startswith(start)])
        state["showing"] = True
    elif state.get("showing"):
        suggest([])                 # the mention is over, give the bar back
        state["showing"] = False
    return state

def on_swipe(direction, state):
    if direction == "left":
        delete_word()
    elif direction == "right":
        press("space")              # the space bar's own path, so it autocorrects
    elif direction == "up":
        pick_suggestion("center")
    elif direction == "up_left":
        pick_suggestion("left")
    elif direction == "up_right":
        pick_suggestion("right")
    return state

Elementi in un layout

Un layout personalizzato è fatto di tasti ed elementi: una striscia di emoji recenti, una fila di cifre, un pad per il cursore. Un plugin può aggiungere i suoi. elements(state) dice cosa offre e draw(id, state) ne disegna uno, così un tasto può mostrare qualsiasi cosa il plugin sappia calcolare: un grafico della velocità, un orologio, un conto alla rovescia, una batteria tutta tua.

Due hook ne costruiscono uno. elements(state) elenca ciò che offri, una voce per elemento, e l'app lo legge per riempire la palette dell'editor di layout. draw(id, state) riceve uno di quegli id e restituisce cosa disegnare. Un plugin può offrirne diversi; a draw viene chiesto ognuno per nome.

POINTS = 30

def initial():
    return {"history": []}

def elements(state):
    return [element("sparkline", "WPM sparkline", icon="waveform.path.ecg", width=3)]

def on_tick(state):
    history = state["history"]
    history.append(stats()["wpm"])
    state["history"] = history[-POINTS:]
    return state

def draw(id, state):
    rate = state["history"][-1] if state["history"] else 0
    return hstack([
        sparkline(state["history"], min=0, max=max(60, max(state["history"] or [0])), fill=True),
        text(f"{rate}", size=12, weight="semibold"),
    ], spacing=5, align="center")

Un volto è un albero di nodi, come una pagina di impostazioni, ma un tasto non è una pagina di impostazioni: si usano solo i nodi che disegnano e tutto ciò che si tocca viene ignorato. Il tasto appartiene già al layout, quindi dentro non c'è posto per un pulsante.

Dimensionalo per un tasto. width si misura in larghezze di tasto: 1 è una lettera e 3 circa un terzo di riga, e chi lo usa può ridimensionarlo dopo. Il testo ha una riga e si restringe per entrare; i colori seguono di default quello del testo del tasto, così un elemento si intona ai tasti attorno se non ne chiedi un altro. Una sparkline tiene i suoi ultimi 120 punti, più di quanti un tasto possa mostrarne.

import time

def elements(state):
    return [element("clock", "Clock", icon="clock", width=2)]

def draw(id, state):
    return text(time.format("HH:mm"), size=15, weight="semibold")

GOAL = 200

def initial():
    return {"words": 0}

def elements(state):
    return [element("goal", "Word goal", icon="target", width=2)]

def on_open(state):
    state["words"] = 0
    return state

def on_word(word, state):
    state["words"] += 1
    return state

def draw(id, state):
    return vstack([
        text(f"{state['words']}/{GOAL}", size=11),
        progress(state["words"], total=GOAL),
    ], spacing=2)

Gli elementi vivono nei layout personalizzati, quindi prima c'è un layout da costruire. I preset non possono ospitarne uno: duplicare un preset nel tuo layout è la prima cosa che l'editor propone.

1. Installa il plugin e accendilo. I suoi elementi compaiono subito.
2. Apri Layout, crea o duplica un layout personalizzato e vai su Disponi.
3. Tocca Elemento, scegli l'elemento del plugin dalla striscia e imposta quanto deve essere largo.

L'anteprima dell'editor disegna ogni elemento offerto dallo script, più o meno grande quanto il tasto che lo ospiterà, sotto il finto spazio. Salva e piazzalo una volta: la tastiera disegna la stessa cosa.

Un elemento mostra soltanto ciò che il plugin disegna: toccarlo non fa nulla, perché il tasto appartiene già al layout. Il layout conserva l'elemento anche con il plugin spento o disinstallato, e il tasto si riempie di nuovo quando il plugin torna.

Pulsanti e manopole nella barra superiore

La striscia sopra i tasti si compone in Layout > Barra superiore, e un plugin può offrirle i propri comandi. bar_items(state) li restituisce: bar_button(...) per qualcosa da toccare, bar_knob(...) per qualcosa da girare. L’elenco viene letto all’apertura della tastiera e di nuovo dopo ogni tocco, così un elemento può comparire e sparire insieme allo stato del plugin.

def initial():
    return {"width": 2.0}

def bar_items(state):
    return [
        bar_button("sig", "Sign off", icon="signature", title="Sign off"),
        bar_knob("volume", "Key volume", icon="speaker.wave.2", setting="sound.volume"),
        bar_knob("width", "Trail width", icon="scribble", min=1, max=6, step=0.5, value=state["width"]),
    ]

def on_action(action, value, state):
    if action == "sig":
        insert(" sent from Clink")
    elif action == "width":
        state["width"] = value
    return state

Entrambi tornano da on_action(action, value, state), indirizzati con l’id dell’elemento, così gli elementi di barra di un plugin e i suoi controlli delle impostazioni condividono lo stesso hook. Un tocco manda None. Una manopola manda il suo valore a ogni scatto finché il dito è giù e un’ultima volta quando lo si alza, così un plugin può seguire il trascinamento o aspettare il valore finale.

Una manopola con setting= gira un valore che l’app ha già, scelto dall’elenco Comandi e letture qui sopra, come sound.volume o haptics.intensity. Un nome che l’app non conosce è un KeyError in console. L’intervallo e la posizione iniziale vengono da quel controllo, la copia della tastiera cambia già mentre trascini, così il tasto successivo è già al nuovo livello, e il valore viene salvato quando lasci. Una manopola del volume o dell’aptica portata su da zero riaccende anche il suono o l’aptica per la durata del gesto, così gli scatti si sentono salendo; a salvare quell’interruttore è il set_setting del plugin dentro on_action.

Una manopola si può disegnare in Python. art= è la parte che resta ferma, la ghiera o il corpo, e rotor= è la faccia che gira, da -135 gradi al minimo a +135 gradi al massimo. Entrambe accettano le stesse forme, tinte, sfumature e ombre della grafica dei tasti, fino a sedici forme ciascuna, e unit="key" scala le coordinate sul quadrante quadrato, dove una lancetta con y negativa punta in alto. Al disegno arrivano il colore del testo della barra come "text" e l’accento del tema come "accent". Se le lasci fuori entrambe, la manopola è un anello con l’icona dentro; nell’editor si può anche dare a una manopola già messa nella barra una qualsiasi delle finiture integrate.

Nella barra non arriva niente da solo. Un elemento si mette a mano, come il menu e i suggerimenti.

1. Installa il plugin e accendilo. I suoi elementi di barra compaiono subito.
2. Apri Layout > Barra superiore.
3. Aggiungi il pulsante o la manopola del plugin e trascinalo al suo posto. Per una manopola si sceglie anche una finitura.

I builder saltano una parola chiave che non conoscono, senza errore. setting=, min=, max=, step=, value=, art= e rotor= sono solo di bar_knob, quindi un bar_button a cui ne passi una viene comunque costruito come semplice pulsante e nessuno lo segnala: il lavoro di un pulsante sta in on_action. Al contrario title= è del pulsante, e una manopola lo salta.

Effetti luce

Un plugin può aggiungere la propria illuminazione dei tasti. effects(state) restituisce voci light_effect(...), e ognuna compare nell’app in Effetti > Dai plugin, accanto agli stili inclusi e agli effetti che le persone creano da sé. Un effetto è un dato, non un disegno: una pila di livelli che la tastiera anima da sola. Nello script non gira quindi nulla a ogni fotogramma, e facce, lettere, alone, lampo alla pressione e riposo funzionano come per gli stili inclusi.

COLORS = ["#00e5ff", "#7c4dff", "#ff4081"]

def effects(state):
    return [
        light_effect("tide", "Tide", colors=COLORS, layers=[
            light_layer("solid", low=0.2, high=0.2),
            light_layer("wave", moves="both", speed=0.8, size=1.5,
                        direction="up"),
        ]),
    ]

def effects(state):
    return [
        light_effect("scanner", "Scanner", layers=[
            light_layer("wave", moves="color", speed=0.3),
            light_layer("sweep", mix="multiply", speed=1.2, size=1.5),
        ]),
    ]

Scegliere un effetto lo copia nelle impostazioni della persona, così continua a funzionare anche a plugin spento. Finché il plugin è attivo e uno dei suoi effetti è in uso, la tastiera rilegge effects(state) all’apertura e poi circa una volta al secondo, e adotta ciò che è cambiato. È così che un effetto segue lo stato, l’ora o stats().

def effects(state):
    # Rounded, so the effect only changes when the pace really does.
    tempo = round(0.3 + min(stats()["wpm"], 120) / 40, 1)
    return [
        light_effect("tempo", "Tempo", colors=["#ff3d7f", "#ffb000"], layers=[
            light_layer("wave", moves="both", speed=tempo, low=0.15),
        ]),
    ]

Il pulsante effects nell’editor elenca ciò che lo script offre. Per vederne uno in movimento, salva il plugin, scegli l’effetto in Effetti > Dai plugin e guarda la tastiera in cima a quella schermata.

Arrotonda tutto ciò che oscilla, come una velocità di scrittura. Un effetto che torna diverso ogni secondo viene sostituito ogni secondo per niente. Un motivo o una parola chiave sconosciuti sono un ValueError nella console dell’editor, e un effetto senza livelli viene scartato.

Aspetti

Sette hook offrono all’app cose da scegliere: key_styles, themes, popups, animations, backgrounds, trails e layouts. Ognuno restituisce voci costruite con le chiamate qui sotto, che compaiono in Dai plugin accanto alle scelte integrate. Fanno eccezione i temi, che hanno una propria scheda Plugin nell’editor dei temi. Un aspetto è fatto di numeri e parole, non di codice di disegno, quindi nello script non gira niente a ogni fotogramma. Sceglierlo lo copia nelle impostazioni della persona, quindi continua a funzionare con il plugin disattivato, e scegliere poi un’opzione integrata lo mette da parte.

def animations(state):
    return [
        entrance("swoop", "Swoop", y=90, scale=0.94, tilt=-20,
                 response=0.5, damping=0.72),
        press_animation("dip", "Dip", scale=0.93, y=2),
        letter_animation("bounce", "Bounce", y=-7, scale=1.12,
                         anchor="bottom"),
        transition("glide", "Glide", x=0.3, scale=0.96),
    ]

def backgrounds(state):
    return [
        background("snowfall", "Snowfall", colors=["#ffffff", "#cfe8ff"], layers=[
            particles(shape="dot", count=70, size=2.2, speed=28,
                      direction="down", spread=12, wobble=10, life=9),
            particles(shape="glow", count=0, size=3, life=1,
                      burst=8, burst_speed=90),
        ]),
    ]

Restituisci nodi trail da trails(state). Ogni scia ha una tavolozza colors e livelli come trail_line. Con color=-1, la linea sfuma i colori lungo lo scorrimento. Attiva il plugin, poi scegli la sua scia in Dai plugin nel selettore delle scie. Memorizzare elementi grafici nello stato non disegna una scia.

def trails(state):
    return [trail("rainbow", "Rainbow", colors=["#ff0000", "#ff8800", "#ffff00", "#00cc44", "#0066ff", "#9900ff"],
        layers=[trail_line(width=1.3, tail_width=0.2, color=-1)])]

Un aspetto viene copiato quando lo si sceglie, quindi cambiare lo script in seguito non cambia un aspetto già in uso; va scelto di nuovo. Una parola chiave scritta male, una parola fuori dalla sua lista o del testo dove va un numero è un errore nella console dell’editor, e i numeri restano negli intervalli usati dai controlli dell’app.

Grafica sui tasti

key_art(state) restituisce un dict dai nomi dei tasti alla grafica, e la tastiera la dipinge dentro il tasto. I nomi dei tasti sono quelli di haptics, con i ripieghi letters e keys. La grafica è una lista di shape(...), una forma sola, un livello art([...]) o una lista di livelli, e ogni livello passa al disegno successivo con il proprio orologio, così un tasto può portare due cose che si muovono a velocità diverse.

La grafica viene riletta dopo ogni evento che il plugin sente, ed è tutto qui il giro: cambi lo stato in on_event(name, info, state) e da lì disegni in key_art(state). events(state) nomina gli eventi voluti e viene letto una volta al caricamento del plugin. Senza di esso un plugin sente tutto tranne key, key_down, key_up, predictions e tick, che fanno girare uno script a ogni pressione o ogni secondo e vanno chiesti. I cambi di maiuscola e di piano ridisegnano la grafica che qualcuno ascolti o no, e arrivano anche in context().

def initial():
    return {"shift": "off"}

def events(state):
    return ["shift"]

def on_event(name, info, state):
    state["shift"] = info["state"]
    return state

def key_art(state):
    if state["shift"] != "locked":
        return {}
    lamp = shape("circle", anchor="top_right", x=-7, y=7, size=5,
                 fill="accent", shadow=shadow("accent", radius=4))
    return {"shift": art([lamp], animate=0.12)}

Sedici forme per tasto, contate su tutti i suoi livelli, e 64 punti per tracciato; quello che avanza viene lasciato cadere. Una forma si disegna dentro un riquadro dei suoi width e height, e un riquadro senza spessore non dipinge niente: una linea orizzontale ha quindi bisogno di un piccolo height suo, con i punti nel mezzo (height=0.03, points=[[0, 0.5], [1, 0.5]]), altrimenti non compare e non lo dice.

Feedback aptico, aree di tocco e correzioni

haptics(state) e hitboxes(state) restituiscono dict con i nomi dei tasti come chiavi: la lettera stessa, "space", "delete", "return", "shift" o "globe", poi "letters" per ogni lettera non nominata e "keys" per tutto il resto. I tasti che un plugin non nomina mantengono le impostazioni della persona. Entrambe le tabelle vengono lette all’apertura della tastiera e circa una volta al secondo, quindi per loro non gira niente a ogni tasto.

def haptics(state):
    return {
        "space": "heavy",
        "return": "rigid",
        "delete": feel(intensity=0.45, sharpness=0.9),
    }

on_touch(key, x, y, state) viene eseguito dopo ogni tocco, una volta gestito, con il punto del tasto in cui si è posato il dito. La posizione è misurata rispetto al tasto disegnato, non al suo bersaglio spostato, quindi un plugin può spostare ogni tasto verso dove viene davvero toccato senza inseguire il proprio spostamento.

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

def on_touch(key, x, y, state):
    if len(key) != 1:
        return state
    n, ax, ay = state["keys"].get(key, [0, 0.0, 0.0])
    n = min(n + 1, 50)
    ax += (x - ax) / n
    ay += (y - ay) / n
    state["keys"][key] = [n, ax, ay]
    return state

def hitboxes(state):
    boxes = {}
    for key in state["keys"]:
        n, x, y = state["keys"][key]
        if n >= 12:
            boxes[key] = hitbox(x=round(x * 0.6, 2), y=round(y * 0.6, 2))
    return boxes

suggestions(word, state) mette parole in testa alla barra mentre si scrive una parola. correct(word, fix, state) viene eseguito una volta per parola quando lo spazio la chiude, con la correzione della tastiera o None, anche con la correzione automatica disattivata. Restituisci una parola per inserirla, False per lasciare la parola com’è stata scritta o None per lasciar decidere la tastiera. Vince il primo plugin che risponde, e cancellare subito dopo lo annulla come qualsiasi correzione automatica.

SHORT = {"brb": "be right back", "omw": "on my way", "idk": "I don't know"}

def suggestions(word, state):
    long = SHORT.get(word.lower())
    return [long] if long else []

def correct(word, fix, state):
    if len(word) > 1 and word.isupper():
        return False
    return None

Nessuno dei due hook viene eseguito nei campi password. Il suggerimento di correzione nella barra mostra la correzione della tastiera, non quello che restituirebbe correct, e una tabella cambiata in on_touch raggiunge la tastiera al ciclo successivo.

Provare nell'editor

L'anteprima dell'editor è una tastiera sostitutiva. Disegna settings(state) dal vivo, attiva qualsiasi hook con un tocco usando una parola, un tasto o un tipo di campo di esempio, mostra la barra spaziatrice come l'ha lasciata il plugin ed elenca tutto ciò che il plugin ha chiesto alla tastiera. Lì stats() restituisce numeri inventati, quindi una velocità compare senza scrivere.

1. Usa i controlli nell'anteprima. Ognuno esegue on_action e ridisegna.
2. Tocca i pulsanti degli hook nell'ordine in cui lo farebbe la tastiera: on_open, poi on_word o on_key qualche volta, poi on_close.
3. Leggi la console. I comandi compaiono come li hai scritti, le righe di print() sotto, e un errore indica la sua riga.
4. Ricarica per ripartire con lo stato azzerato. Modificare lo script non lo azzera da solo.

L'anteprima non ha un documento, quindi insert() e replace() si limitano a registrare. Per provarli, salva e scrivi in un campo qualsiasi con la tastiera aperta.

Limiti

Quando un plugin arriva come file o da un repository, Clink lo controlla prima di salvarlo. Deve stare sotto i 64.000 byte e le 1600 righe, definire almeno un hook, importare solo i moduli consentiti e non contenere nessuno di questi elementi:

Ogni chiamata a un hook riceve 2.000.000 passi dell'interprete, gli stessi di un rendering di pannello. Però on_key gira a ogni pressione, quindi un lavoro pesante lì rallenta la scrittura molto prima di arrivare a quel limite.

Il file

Un plugin è un unico documento JSON. id resta stabile tra gli aggiornamenti, version è testo libero mostrato nell'elenco, icon è il nome di un SF Symbol e source è lo script con gli a capo con escape. Condividilo dall'ispettore dell'editor, oppure importane uno con il pulsante freccia della scheda Plugin.

{
  "id": "word-count",
  "name": "Word count",
  "icon": "text.word.spacing",
  "summary": "Counts words on the space bar",
  "version": "1.0",
  "author": "You",
  "enabled": true,
  "source": "def initial():\n    return {\"on\": False}\n..."
}

I plugin si condividono come file .clinkplugin, un documento JSON con dentro lo script. Si pubblicano tramite un repository come i pannelli, con una cartella di file, un manifest e una release. Il repository ufficiale è anti-ltd/clink-plugins.

Quando qualcosa non succede

Il più delle volte è una di queste.