Plugins

Automationen

Das optionale automation-Objekt in einer .clinkplugin-Datei deklariert Ereignisse, Zustand, Einstellungen, Befehle, Vorlagen und Kurzbefehlplätze. Jeder Beitrag hat eine stabile ID, eine genau passende Schemaversion und lokalisierte Titel. Der Host erstellt Namen nach plugin/<plugin-id>/<kind>/<id>. Ein Plugin kann keinen System-Namensraum und keinen Namensraum eines anderen Plugins beanspruchen.

Wie Plugins funktionieren

Ein Panel ersetzt die Tasten, eine Aktion läuft einmal über einen Text. Ein Plugin hat auf der Tastatur keine eigene Fläche. Clink ruft seine Funktionen zu festen Zeitpunkten auf, etwa wenn die Tastatur öffnet oder du ein Wort beendest, und das Plugin kann die Leertaste oder seinen eigenen gespeicherten Zustand ändern. Seine Einstellungen werden in der App mit denselben Bausteinen gezeichnet, die auch Panels verwenden. WPM Spacebar, unten, ist ein vollständiges Plugin.

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

Plugins brauchen Clink Pro. Bevor Clink eines aus einem Repository installiert, fragt es dich, ob du Code aus diesem Repository erlaubst, genau wie bei Panels und Aktionen.

on_key und on_word bekommen, was du tippst, denn so funktioniert ein Wortzähler. PyMini hat keinen Netzwerk- oder Dateizugriff, ein Plugin kann deine Eingaben also nicht über das Internet senden, und was es speichert, bleibt bei Clink auf deinem Gerät.

Dein erstes Plugin

Am schnellsten geht es mit dem Starter-Skript, das die App für dich schreibt. Es setzt einen Schalter unter Tasten > Leertaste und zählt, solange der Schalter an ist, Wörter auf der Leertaste. Fünf Schritte, keine Datei zum Herunterladen.

1. Öffne den Tab Plugins, schalte Plugins oben ein und tippe auf + für ein neues Plugin.
2. Der Editor öffnet sich mit dem Starter-Skript. Lies es einmal durch: initial(), settings(), on_action(), on_open() und on_word() sind das Ganze.
3. Wechsle zur Vorschau. Lege den Schalter um, tippe dann ein paar Mal auf on_open und on_word und beobachte die Leertasten-Attrappe und die Konsole.
4. Speichern. Das Plugin ist in der Liste eingeschaltet, und sein Schalter sitzt jetzt auch unter Tasten > Leertaste.
5. Öffne die Tastatur irgendwo und tippe. Die Leertaste zählt mit.

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

Hooks

Definiere beliebige dieser 33 Funktionen und lass die weg, die du nicht brauchst. Jede bekommt state als letztes Argument. Die, die auf etwas reagieren, geben state zurück, verändert oder nicht. Die, die eine Frage beantworten (elements, draw, effects, die Hooks für Look-Vorlagen, haptics, hitboxes, suggestions und correct), geben ihre Antwort zurück und können state trotzdem direkt ändern.

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

Die App und die Tastatur teilen sich eine Kopie des Zustands. Schaltest du in der App einen Schalter ein, ist er beim nächsten Öffnen der Tastatur an. Was die Tastatur zählt, ist da, wenn du die Einstellungen des Plugins das nächste Mal öffnest. Die Tastatur speichert den Zustand beim Schließen, nicht nach jeder Taste.

Aktueller Vorschlag auf der Leertaste

Mit context()["suggestion"] liest du den wichtigsten angezeigten Vorschlag. Abonniere das Ereignis predictions, um Änderungen über info["suggestion"] zu erhalten. Beides erfordert Zugriff auf Eingabedaten. on_suggestion wird erst beim Übernehmen eines Vorschlags aufgerufen. Mit space_text(value or None) setzt du die Beschriftung oder stellst sie wieder her, wenn keine Vorschläge mehr angezeigt werden. Die Funktion der Leertaste bleibt gleich.

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

Zustand

Der Zustand ist ein einzelnes Dict. initial() baut es beim ersten Mal; danach bekommt jeder Hook dasselbe Dict, ändert es und gibt es zurück. Es fasst alles, was JSON fassen kann: Zahlen, Strings, Listen, verschachtelte Dicts. Die App speichert es nach jedem Bedienelement, das du benutzt, die Tastatur beim Schließen, und beide lesen dieselbe Datei, sodass sie nie lange auseinanderliegen.

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

Den Zustand zurückzugeben ist die Gewohnheit, die man beibehalten sollte, aber nicht zwingend nötig: Das Dict ist eine Referenz, also funktioniert auch das Ändern an Ort und Stelle. Gib ein anderes Dict zurück, wie oben initial(), und das wird zum Zustand.

Einstellungen und Abschnitte

settings(state) gibt einen Knotenbaum zurück, gebaut mit den Panel-Bausteinen: text, toggle, slider, stepper, segmented, button, row, field und die Layouts. Er erscheint auf der Seite des Plugins im Tab Plugins. Umschließe einen Teil davon mit section(anchor, children, title), dann erscheint dieser Teil auch auf einem von Clinks eigenen Einstellungsbildschirmen, neben der Einstellung, zu der er gehört.

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"),
    ])

Die Bedienelemente, die ein Plugin am häufigsten braucht. Jedes schreibt entweder seinen neuen Wert unter key in den Zustand oder nennt eine action für on_action, oder beides. Die vollständige Liste der Bausteine, samt Layouts, steht auf der Panel-Seite.

Wo Abschnitte landen

Ein Anker ist die ID einer Karte auf einem der eigenen Einstellungsbildschirme von Clink. Nenne ihn in section(), und die Bedienelemente des Plugins werden direkt unter dieser Karte gezeichnet, mit dem Namen des Plugins darüber. Am einfachsten findest du einen so: Öffne in der App Mehr > Entwickler und schalte IDs anzeigen ein. Jede Karte bekommt ein kleines Info-Symbol, das ihre ID nennt und beim Tippen kopiert; Seiten zeigen ihre in der Titelleiste.

keys.spacebar hat einen eigenen Platz, auf dem Leertasten-Bildschirm selbst. Ein Abschnitt mit einem Anker, der nicht in dieser Liste steht, erscheint trotzdem auf der Seite des Plugins, ein Tippfehler kostet dich also eine Karte, nicht das Plugin.

Übernahmen

Wenn ein Plugin eine der eigenen Einstellungen von Clink steuert, sollte die Person das sehen, und die beiden sollten sich nicht streiten. claim(control) sagt, dass das Plugin sie besitzt: Die App nennt das Plugin auf der Karte dieser Einstellung, und das Feld für den Leertastentext ist gesperrt, solange es gehalten wird. release(control) gibt sie zurück. Übernimm in der on_action, die dein Feature einschaltet, gib in derjenigen frei, die es ausschaltet, und setze den Wert gleichzeitig auf None oder seinen alten Wert zurück. Ein in der Liste ausgeschaltetes Plugin gibt alles frei, was es hielt.

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

Zwei Plugins können dasselbe Bedienelement übernehmen; die App nennt das, das zuletzt übernommen hat. Übernahmen werden von der App aufgezeichnet, also übernimm in on_action, das dort läuft. Eine Übernahme aus der Tastatur heraus wird nicht gemerkt.

Befehle und Lesezugriffe

Plugins können jeden Panel-Befehl verwenden, dazu sechs eigene Befehle und zwei eigene Lesezugriffe. Befehle werden gesammelt und erst angewendet, nachdem deine Funktion zurückgekehrt ist, damit sich auf der Tastatur nichts mitten in einem Aufruf ändert. Lesezugriffe liefern die Werte, wie sie direkt vor dem Aufruf waren.

setting(name) und set_setting(name, value) teilen sich eine Liste von Namen, und claim(control) nimmt ebenfalls jeden davon. Booleans lesen sich als True oder False, Zahlen als Zahlen, Auswahlen als ihre ID. Die Liste ist absichtlich lang: Ein Plugin kann auf fast alles reagieren oder es steuern, was eine Person in der App einstellen kann.

Wie das view() eines Panels sollte settings() nur Bedienelemente beschreiben. Befehle, die dort aufgerufen werden, werden ignoriert und in der Konsole protokolliert.

Beispiele

Fünf kleine Plugins, jedes vollständig. Füge eines in ein neues Plugin ein, speichere, und es läuft.

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

Elemente in einem Layout

Ein eigenes Layout besteht aus Tasten und Elementen: eine Leiste zuletzt benutzter Emoji, eine Ziffernreihe, ein Cursor-Pad. Ein Plugin kann eigene hinzufügen. elements(state) sagt, was es anbietet, und draw(id, state) zeichnet eines davon. So kann eine Taste alles zeigen, was das Plugin berechnen kann: eine Tempokurve, eine Uhr, einen Countdown, eine eigene Batterieanzeige.

Zwei Hooks bauen eines. elements(state) listet auf, was du anbietest, einen Eintrag pro Element, und die App liest das für die Palette des Layout-Editors. draw(id, state) bekommt eine dieser IDs und gibt zurück, was gezeichnet werden soll. Ein Plugin darf mehrere anbieten; draw wird für jedes einzeln gefragt.

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")

Ein Gesicht ist ein Knotenbaum wie eine Einstellungsseite, aber eine Taste ist keine Einstellungsseite: nur die zeichnenden Knoten werden verwendet, alles Antippbare wird ignoriert. Die Taste gehört bereits dem Layout, also ist darin kein Platz für eine Schaltfläche.

Bemiss es für eine Taste. width zählt in Tastenbreiten: 1 ist ein Buchstabe, 3 etwa ein Drittel einer Reihe, und die Person kann es danach ändern. Text bekommt eine Zeile und schrumpft, damit er passt; Farben folgen standardmäßig der Textfarbe der Taste, sodass ein Element zu den Tasten ringsum passt, wenn du nichts anderes verlangst. Eine Sparkline behält ihre letzten 120 Punkte, mehr als eine Taste zeigen kann.

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)

Elemente leben in eigenen Layouts, also gibt es zuerst ein Layout zu bauen. Vorlagen können keines aufnehmen: Eine Vorlage in ein eigenes Layout zu kopieren, ist das Erste, was der Editor anbietet.

1. Installiere das Plugin und schalte es ein. Seine Elemente erscheinen im selben Moment.
2. Öffne Layout, erstelle oder kopiere ein eigenes Layout und geh zu Anordnen.
3. Tippe auf Element, wähle das Element des Plugins aus der Leiste und stelle seine Breite ein.

Die Vorschau im Editor zeichnet jedes Element, das das Skript anbietet, etwa so groß wie die Taste, auf der es sitzen wird, unter der Leertasten-Attrappe. Einmal speichern und platzieren, und die Tastatur zeichnet dasselbe.

Ein Element zeigt nur, was das Plugin zeichnet: Ein Tipp darauf macht nichts, weil die Taste schon zum Layout gehört. Ein Layout behält das Element auch dann, wenn sein Plugin aus oder deinstalliert ist, und die Taste füllt sich wieder, sobald es zurück ist.

Schaltflächen und Regler in der oberen Leiste

Die Leiste über den Tasten wird unter Layout > Obere Leiste zusammengestellt, und ein Plugin kann eigene Bedienelemente dafür anbieten. bar_items(state) gibt sie zurück: bar_button(...) zum Antippen, bar_knob(...) zum Drehen. Die Liste wird beim Öffnen der Tastatur und nach jedem Tippen erneut gelesen, ein Element kann also mit dem Zustand des Plugins kommen und gehen.

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

Beides kommt über on_action(action, value, state) zurück, adressiert über die id des Elements, sodass Leistenelemente und Einstellungen eines Plugins denselben Hook teilen. Ein Tippen schickt None. Ein Regler schickt seinen Wert bei jeder Raste, solange der Finger unten ist, und noch einmal beim Loslassen, ein Plugin kann die Bewegung also mitlesen oder auf den letzten Wert warten.

Ein Regler mit setting= dreht an einem Wert, den die App schon hat, benannt aus der Liste unter Befehle und Lesezugriffe weiter oben, etwa sound.volume oder haptics.intensity. Ein Name, den die App nicht kennt, ist ein KeyError in der Konsole. Bereich und Startstand kommen von diesem Bedienelement, die Kopie der Tastatur ändert sich schon beim Ziehen, sodass der nächste Tastendruck bereits auf dem neuen Stand ist, und gespeichert wird beim Loslassen. Ein Lautstärke- oder Haptikregler, der aus dem Nichts aufgedreht wird, schaltet Ton oder Haptik für die Bewegung wieder ein, damit die Rasten auf dem Weg nach oben zu hören und zu spüren sind; diesen Schalter speichert das Plugin selbst mit set_setting in on_action.

Ein Regler lässt sich in Python zeichnen. art= ist der Teil, der stehen bleibt, Fassung oder Körper, und rotor= ist die Scheibe, die sich dreht, von -135 Grad am Minimum bis +135 Grad am Maximum. Beide nehmen dieselben Formen, Farben, Verläufe und Schatten wie Tastengrafik, je bis zu sechzehn Formen, und unit="key" skaliert die Koordinaten auf das quadratische Zifferblatt, wo ein Zeiger bei negativem y nach oben zeigt. Die Grafik bekommt die Textfarbe der Leiste als "text" und die Akzentfarbe des Themes als "accent". Lässt du beides weg, ist der Regler ein Ring mit dem Icon darin; im Editor lässt sich einem Regler in der Leiste auch jede eingebaute Optik geben.

Von allein landet nichts in der Leiste. Ein Element wird von Hand platziert, genau wie das Menü und die Vorschläge.

1. Installiere das Plugin und schalte es ein. Seine Leistenelemente erscheinen sofort.
2. Öffne Layout > Obere Leiste.
3. Füge die Schaltfläche oder den Regler des Plugins hinzu und zieh sie an ihren Platz. Für einen Regler lässt sich außerdem eine Optik wählen.

Die Builder übergehen ein Schlüsselwort, das sie nicht kennen, ohne Fehler. setting=, min=, max=, step=, value=, art= und rotor= gehören allein zu bar_knob; ein bar_button, dem man eines mitgibt, wird trotzdem als schlichte Schaltfläche gebaut, ohne einen Hinweis: Die Arbeit einer Schaltfläche gehört in on_action. Umgekehrt gehört title= zur Schaltfläche, und ein Regler übergeht es.

Lichteffekte

Ein Plugin kann eigene Tastenbeleuchtung beisteuern. effects(state) gibt light_effect(...)-Einträge zurück, und jeder erscheint in der App unter Effekte > Aus Plugins, neben den eingebauten Stilen und den Effekten, die Leute selbst bauen. Ein Effekt ist Daten, keine Zeichnung: ein Stapel Ebenen, den die Tastatur selbst animiert. Im Skript läuft also nichts pro Bild, und Tastenflächen, Buchstaben, Glühen, das Aufleuchten beim Anschlag und der Ruhemodus funktionieren wie bei den eingebauten Stilen.

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),
        ]),
    ]

Wer einen Effekt auswählt, kopiert ihn in die eigenen Einstellungen, also läuft er auch mit ausgeschaltetem Plugin weiter. Solange das Plugin an ist und einer seiner Effekte läuft, liest die Tastatur effects(state) beim Öffnen und danach etwa einmal pro Sekunde neu und übernimmt, was sich geändert hat. So folgt ein Effekt dem Zustand, der Uhrzeit oder 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),
        ]),
    ]

Der Button effects im Editor listet, was das Skript anbietet. Um einen Effekt in Bewegung zu sehen, sichere das Plugin, wähle den Effekt unter Effekte > Aus Plugins und schau auf die Tastatur oben auf dieser Seite.

Runde alles, was zappelt, etwa eine Tipprate. Ein Effekt, der jede Sekunde anders zurückkommt, wird jede Sekunde für nichts ausgetauscht. Ein unbekanntes Muster oder Schlüsselwort ist ein ValueError in der Editor-Konsole, und ein Effekt ohne Ebenen wird weggelassen.

Look-Vorlagen

Sieben Hooks bieten der App etwas zur Auswahl an: key_styles, themes, popups, animations, backgrounds, trails und layouts. Jeder gibt Einträge zurück, die mit den Aufrufen unten gebaut werden, und sie erscheinen unter Aus Plugins neben den eingebauten Optionen. Nur Themes haben im Theme-Editor einen eigenen Tab Plugins. Eine Look-Vorlage besteht aus Zahlen und Wörtern, nicht aus Zeichencode, also läuft im Skript nichts pro Frame. Wer einen auswählt, kopiert ihn in die eigenen Einstellungen, also läuft er auch mit ausgeschaltetem Plugin weiter, und wer danach eine eingebaute Option wählt, legt ihn beiseite.

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),
        ]),
    ]

Gib in trails(state) trail-Knoten zurück. Jede Spur hat eine colors-Palette und Ebenen wie trail_line. Mit color=-1 gehen die Farben entlang der Wischspur ineinander über. Aktiviere das Plugin und wähle dann seine Spur unter Aus Plugins in der Spurauswahl. Zeichendaten im Zustand allein erzeugen keine Spur.

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)])]

Ein Look wird beim Auswählen kopiert, also ändert ein späteres Ändern des Skripts keinen Look, den jemand schon benutzt; man wählt ihn neu aus. Ein falsch geschriebenes Schlüsselwort, ein Wort außerhalb seiner Liste oder Text, wo eine Zahl hingehört, ist ein Fehler in der Editor-Konsole, und Zahlen bleiben in den Bereichen, die auch die Regler der App nutzen.

Grafik auf den Tasten

key_art(state) gibt ein Dict von Tastennamen zu Grafik zurück, und die Tastatur malt sie in die Tastenkappe. Die Tastennamen sind die von haptics, mit den Rückfällen letters und keys. Grafik ist eine Liste von shape(...), eine einzelne Form, eine Ebene art([...]) oder eine Liste von Ebenen, und jede Ebene blendet nach ihrer eigenen Uhr in ihr nächstes Bild über, sodass eine Taste zwei verschieden schnelle Dinge tragen kann.

Die Grafik wird nach jedem Ereignis, das das Plugin hört, neu gelesen, und das ist die ganze Schleife: Zustand in on_event(name, info, state) ändern, in key_art(state) daraus zeichnen. events(state) nennt die gewünschten Ereignisse und wird einmal beim Laden des Plugins gelesen. Ohne den Hook hört ein Plugin alles außer key, key_down, key_up, predictions und tick, die ein Skript pro Anschlag oder pro Sekunde laufen lassen und deshalb angefordert werden müssen. Änderungen an Shift und Ebene zeichnen die Grafik neu, ob jemand zuhört oder nicht, und sie erreichen auch 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)}

Sechzehn Formen pro Taste, über alle Ebenen darauf zusammengezählt, und 64 Punkte pro Pfad; alles darüber fällt weg. Eine Form wird in einem Kasten ihrer eigenen width und height gezeichnet, und ein Kasten ohne Dicke malt nichts. Eine waagerechte Linie braucht darum eine kleine eigene height mit ihren Punkten in deren Mitte (height=0.03, points=[[0, 0.5], [1, 0.5]]), sonst erscheint sie stillschweigend nicht.

Haptik, Trefferflächen und Korrekturen

haptics(state) und hitboxes(state) geben Dicts zurück, deren Schlüssel Tastennamen sind: der Buchstabe selbst, "space", "delete", "return", "shift" oder "globe", dann "letters" für jeden nicht genannten Buchstaben und "keys" für alles andere. Tasten, die ein Plugin auslässt, behalten die eigenen Einstellungen der Person. Beide Tabellen werden beim Öffnen der Tastatur und etwa einmal pro Sekunde gelesen, also läuft für sie nichts pro Tastendruck.

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

on_touch(key, x, y, state) läuft nach jedem Tipp, sobald er verarbeitet ist, mit der Stelle auf der Taste, an der der Finger aufkam. Gemessen wird an der gezeichneten Taste, nicht an ihrem verschobenen Ziel, also kann ein Plugin jede Taste dorthin schieben, wo sie wirklich getroffen wird, ohne der eigenen Verschiebung hinterherzulaufen.

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) setzt Wörter an den Anfang der Leiste, während ein Wort getippt wird. correct(word, fix, state) läuft einmal pro Wort, wenn die Leertaste es beendet, mit der Korrektur der Tastatur oder None, auch bei ausgeschalteter Autokorrektur. Gib ein Wort zurück, um es einzufügen, False, um das Wort wie getippt zu lassen, oder None, um es der Tastatur zu überlassen. Das erste Plugin mit einer Antwort gewinnt, und Löschen direkt danach macht es rückgängig wie jede Autokorrektur.

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

Keiner der beiden Hooks läuft in Passwortfeldern. Der Korrektur-Chip in der Leiste zeigt die Korrektur der Tastatur, nicht das, was correct zurückgäbe, und eine in on_touch geänderte Tabelle erreicht die Tastatur beim nächsten Takt.

Testen im Editor

Die Vorschau des Editors ist eine Ersatztastatur. Sie zeichnet settings(state) live, löst jeden Hook auf Tipp mit einem Beispielwort, einer Taste oder einer Feldart aus, zeigt die Leertaste, wie das Plugin sie hinterlassen hat, und listet alles auf, was das Plugin von der Tastatur verlangt hat. stats() liefert dort erfundene Zahlen, sodass eine Rate ohne Tippen erscheint.

1. Nutze die Bedienelemente in der Vorschau. Jedes führt on_action aus und zeichnet neu.
2. Tippe die Hook-Schaltflächen in der Reihenfolge, in der die Tastatur sie aufrufen würde: on_open, dann ein paar Mal on_word oder on_key, dann on_close.
3. Lies die Konsole. Befehle erscheinen so, wie du sie geschrieben hast, print()-Zeilen darunter, und ein Fehler nennt seine Zeile.
4. Lade neu, um den Zustand zurückzusetzen. Das Bearbeiten des Skripts setzt ihn nicht von allein zurück.

Die Vorschau hat kein Dokument, deshalb protokollieren insert() und replace() nur. Um sie auszuprobieren, speichere und tippe bei geöffneter Tastatur in irgendein Feld.

Grenzen

Wenn ein Plugin als Datei oder aus einem Repository kommt, prüft Clink es vor dem Speichern. Es muss unter 64.000 Bytes und 1.600 Zeilen bleiben, mindestens einen Hook definieren, nur die erlaubten Module importieren und darf nichts hiervon enthalten:

Jeder Hook-Aufruf bekommt 2.000.000 Interpreterschritte, genauso viele wie das Rendern eines Panels. on_key läuft aber bei jedem Tastendruck, deshalb bremst aufwendige Arbeit dort das Tippen, lange bevor sie diese Grenze erreicht.

Die Datei

Ein Plugin ist ein einzelnes JSON-Dokument. id bleibt über Updates stabil, version ist Freitext, der in der Liste erscheint, icon ist ein SF-Symbol-Name, und source ist das Skript mit maskierten Zeilenumbrüchen. Teile es aus dem Inspektor des Editors, oder importiere eines mit der Pfeiltaste im Tab Plugins.

{
  "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..."
}

Plugins werden als .clinkplugin-Dateien geteilt, einem JSON-Dokument mit dem Skript darin. Sie werden wie Panels über ein Repository veröffentlicht, mit einem Ordner voller Dateien, einem Manifest und einem Release. Das offizielle Repository ist anti-ltd/clink-plugins.

Wenn etwas nicht passiert

Meistens ist es eines von diesen.