Plugins

Automatisations

L’objet automation facultatif d’un fichier .clinkplugin déclare événements, état, réglages, commandes, préréglages et emplacements de raccourcis. Chaque contribution possède un identifiant stable, une version de schéma exacte et des titres localisés. L’hôte crée les noms plugin/<plugin-id>/<kind>/<id>. Un plugin ne peut pas utiliser l’espace de noms du système ou d’un autre plugin.

Comment fonctionnent les plugins

Un panneau remplace les touches, et une action s'exécute une fois sur un texte. Un plugin n'a pas d'écran à lui sur le clavier. Clink appelle ses fonctions à des moments précis, par exemple quand le clavier s'ouvre ou que vous terminez un mot, et le plugin peut modifier la barre d'espace ou son propre état enregistré. Ses réglages sont dessinés dans l'app avec les mêmes constructeurs que ceux des panneaux. WPM Spacebar, plus bas, est un plugin complet.

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

Les plugins nécessitent Clink Pro. Avant d'en installer un depuis un dépôt, Clink vous demande d'autoriser le code de ce dépôt, comme pour les panneaux et les actions.

on_key et on_word reçoivent ce que vous tapez, c'est ce qui permet de compter les mots. PyMini n'a accès ni au réseau ni aux fichiers, donc un plugin ne peut pas envoyer ce que vous tapez sur Internet, et ce qu'il enregistre reste dans Clink, sur votre appareil.

Votre premier plugin

Le plus rapide est le script de départ que l'app écrit pour vous. Il place un interrupteur sous Touches > Barre d'espace et, tant qu'il est actif, compte les mots sur la barre d'espace. Cinq étapes, rien à télécharger.

1. Ouvrez l'onglet Plugins, activez les plugins en haut, puis touchez + pour un nouveau plugin.
2. L'éditeur s'ouvre sur le script de départ. Lisez-le une fois : initial(), settings(), on_action(), on_open() et on_word(), c'est tout.
3. Passez à l'aperçu. Basculez l'interrupteur, puis touchez on_open et on_word plusieurs fois et regardez la fausse barre d'espace et la console.
4. Enregistrez. Le plugin est actif dans la liste, et son interrupteur se trouve maintenant aussi sous Touches > Barre d'espace.
5. Ouvrez le clavier n'importe où et tapez. La barre d'espace compte avec vous.

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

Définissez celles de ces 33 fonctions dont vous avez besoin et laissez de côté les autres. Chacune reçoit state en dernier argument. Celles qui réagissent à quelque chose renvoient state, modifié ou non. Celles qui répondent à une question (elements, draw, effects, les hooks d’apparence, haptics, hitboxes, suggestions et correct) renvoient leur réponse, et peuvent quand même modifier state sur place.

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 et le clavier partagent une seule copie de l'état. Activez un interrupteur dans l'app et il sera actif à la prochaine ouverture du clavier. Ce que le clavier compte est là la prochaine fois que vous ouvrez les réglages du plugin. Le clavier enregistre l'état à sa fermeture, pas après chaque touche.

Suggestion actuelle sur la barre d’espace

Lisez la suggestion principale affichée avec context()["suggestion"]. Abonnez-vous à l’événement predictions pour recevoir les changements dans info["suggestion"]. Ces deux opérations nécessitent l’accès aux données de saisie. on_suggestion s’exécute après l’acceptation d’une suggestion, pas lorsque les prédictions changent. Appelez space_text(value or None) pour définir le libellé ou le rétablir lorsqu’il n’y a plus de suggestions. L’action de la barre d’espace ne change pas.

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

État

L'état est un seul dict. initial() le construit la première fois ; ensuite chaque hook reçoit le même dict, le modifie et le rend. Il contient tout ce que JSON peut contenir : nombres, chaînes, listes, dicts imbriqués. L'app l'enregistre après chaque commande que vous utilisez, le clavier à sa fermeture, et les deux lisent le même fichier, donc ils ne divergent jamais longtemps.

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

Renvoyer l'état est une bonne habitude, mais ce n'est pas strictement obligatoire : le dict est une référence, donc le modifier sur place marche aussi. Renvoyez un autre dict, comme initial() ci-dessus, et il devient l'état.

Réglages et sections

settings(state) renvoie un arbre de nœuds construit avec les constructeurs de panneau : text, toggle, slider, stepper, segmented, button, row, field et les dispositions. Il apparaît sur la page du plugin dans l'onglet Plugins. Enveloppez-en une partie dans section(anchor, children, title) et cette partie apparaît aussi sur l'un des écrans de réglages de Clink, à côté du réglage qu'elle concerne.

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

Les commandes dont un plugin a le plus souvent besoin. Chacune écrit sa nouvelle valeur dans l'état sous key, ou nomme une action pour on_action, ou les deux. La liste complète des constructeurs, dispositions comprises, est sur la page des panneaux.

Où vont les sections

Une ancre est l'identifiant d'une carte sur l'un des écrans de réglages de Clink. Nommez-la dans section() et les commandes du plugin sont dessinées juste sous cette carte, avec le nom du plugin au-dessus. Le plus simple pour en trouver une : dans l'app, ouvrez Plus > Développeur et activez Afficher les identifiants. Chaque carte reçoit un petit badge d'information qui donne son identifiant et le copie d'une touche ; les pages affichent le leur dans la barre de titre.

keys.spacebar a une place à elle, sur l'écran de la barre d'espace lui-même. Une section dont l'ancre n'est pas dans cette liste s'affiche quand même sur la page du plugin ; une faute de frappe vous coûte donc une carte, pas le plugin.

Prises de contrôle

Quand un plugin pilote un réglage de Clink, la personne doit le voir, et les deux ne doivent pas se battre. claim(control) déclare que le plugin en est propriétaire : l'app nomme le plugin sur la carte de ce réglage, et le champ du texte de la barre d'espace est verrouillé tant qu'il le détient. release(control) le rend. Prenez-le dans le on_action qui active votre fonction, rendez-le dans celui qui la désactive, et remettez la valeur à None ou à son ancienne valeur en même temps. Un plugin désactivé dans la liste libère tout ce qu'il tenait.

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

Deux plugins peuvent prendre la même commande ; l'app nomme celui qui l'a prise en dernier. Les prises de contrôle sont enregistrées par l'app, donc prenez-les depuis on_action, qui s'exécute là. Une prise faite dans le clavier n'est pas mémorisée.

Commandes et lectures

Les plugins peuvent utiliser toutes les commandes de panneau, plus six commandes et deux lectures qui leur sont propres. Les commandes sont mises en file et appliquées après le retour de votre fonction, pour que rien ne change sur le clavier au milieu d'un appel. Les lectures renvoient les valeurs telles qu'elles étaient juste avant l'appel.

setting(name) et set_setting(name, value) partagent une même liste de noms, et claim(control) accepte aussi n'importe lequel d'entre eux. Les booléens se lisent True ou False, les nombres comme des nombres, les choix par leur identifiant. La liste est longue à dessein : un plugin peut réagir à presque tout ce qu'une personne peut régler dans l'app, ou le piloter.

Comme le view() d'un panneau, settings() ne doit que décrire des contrôles. Les commandes appelées depuis cette fonction sont ignorées et notées dans la console.

Exemples

Cinq petits plugins, chacun complet. Collez-en un dans un nouveau plugin, enregistrez, et il tourne.

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

Éléments dans une disposition

Une disposition personnalisée se construit avec des touches et des éléments : une bande d'emojis récents, une rangée de chiffres, un pavé de curseur. Un plugin peut ajouter les siens. elements(state) dit ce qu'il propose et draw(id, state) en dessine un, si bien qu'une touche peut montrer tout ce que le plugin sait calculer : une courbe de vitesse, une horloge, un compte à rebours, votre propre batterie.

Deux hooks en construisent un. elements(state) énumère ce que vous proposez, une entrée par élément, et l'app le lit pour remplir la palette de l'éditeur de disposition. draw(id, state) reçoit l'un de ces identifiants et renvoie quoi peindre. Un plugin peut en proposer plusieurs ; draw est appelé pour chacun, par son nom.

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 visage est un arbre de nœuds, comme une page de réglages, mais une touche n'est pas une page de réglages : seuls les nœuds qui dessinent servent, et tout ce qui se touche est ignoré. La touche appartient déjà à la disposition, il n'y a donc pas de place pour un bouton à l'intérieur.

Dimensionnez-le pour une touche. width se compte en largeurs de touche : 1 est une lettre, 3 environ un tiers de rangée, et la personne peut le changer ensuite. Le texte tient sur une ligne et rétrécit pour entrer ; les couleurs suivent par défaut celle du texte de la touche, si bien qu'un élément s'accorde aux touches voisines sauf demande contraire. Une sparkline garde ses 120 derniers points, plus qu'une touche ne peut montrer.

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)

Les éléments vivent dans les dispositions personnalisées : il faut donc d'abord en construire une. Les préréglages n'en acceptent pas ; dupliquer un préréglage en votre propre disposition est la première chose que propose l'éditeur.

1. Installez le plugin et activez-le. Ses éléments apparaissent aussitôt.
2. Ouvrez Disposition, créez ou dupliquez une disposition personnalisée, puis allez dans Agencer.
3. Touchez Élément, choisissez l'élément du plugin dans la bande et réglez sa largeur.

L'aperçu de l'éditeur dessine chaque élément proposé par le script, à peu près à la taille de la touche qui l'accueillera, sous la maquette de barre d'espace. Enregistrez et placez-le une fois : le clavier dessine la même chose.

Un élément ne fait que montrer ce que le plugin dessine : le toucher ne fait rien, car la touche appartient déjà à la disposition. La disposition garde l'élément même quand son plugin est désactivé ou désinstallé, et la touche se remplit à nouveau dès son retour.

Boutons et molettes dans la barre supérieure

La bande au-dessus des touches se compose dans Disposition > Barre supérieure, et un plugin peut y proposer ses propres commandes. bar_items(state) les renvoie : bar_button(...) pour ce qui se touche, bar_knob(...) pour ce qui se tourne. La liste est lue à l’ouverture du clavier puis après chaque appui, un élément peut donc apparaître et disparaître avec l’état du 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

Les deux reviennent par on_action(action, value, state), identifiés par l’id de l’élément : les éléments de barre d’un plugin et ses réglages partagent donc le même hook. Un appui envoie None. Une molette envoie sa valeur à chaque cran tant que le doigt est posé, puis une dernière fois au relâchement, un plugin peut donc suivre le geste ou attendre la valeur finale.

Une molette avec setting= tourne un réglage que l’app possède déjà, nommé dans la liste Commandes et lectures plus haut, comme sound.volume ou haptics.intensity. Un nom que l’app ne connaît pas donne un KeyError dans la console. La plage et la position de départ viennent de ce réglage, la copie propre au clavier change pendant le glissement, si bien que la touche suivante est déjà au nouveau niveau, et la valeur est enregistrée au relâchement. Une molette de volume ou de retour haptique remontée depuis zéro rallume aussi le son ou l’haptique le temps du geste, pour qu’on entende et sente les crans en montant ; c’est au plugin d’enregistrer cet interrupteur avec set_setting dans on_action.

Une molette peut être dessinée en Python. art= est la partie qui ne bouge pas, la lunette ou le corps, et rotor= la face qui tourne, de -135 degrés au minimum à +135 degrés au maximum. Les deux acceptent les mêmes formes, peintures, dégradés et ombres que le dessin de touche, jusqu’à seize formes chacune, et unit="key" met les coordonnées à l’échelle du cadran carré, où une aiguille à y négatif pointe vers le haut. Le dessin reçoit la couleur de texte de la barre sous le nom "text" et l’accent du thème sous le nom "accent". Si vous omettez les deux, la molette est un anneau avec l’icône au centre ; l’éditeur permet aussi de donner à une molette déjà posée n’importe quelle finition intégrée.

Rien n’arrive tout seul dans la barre. Un élément se place à la main, comme le menu et les suggestions.

1. Installez le plugin et activez-le. Ses éléments de barre apparaissent aussitôt.
2. Ouvrez Disposition > Barre supérieure.
3. Ajoutez le bouton ou la molette du plugin et faites-le glisser à sa place. Une molette reçoit en plus une finition à choisir.

Les constructeurs ignorent sans erreur un mot-clé qu’ils ne connaissent pas. setting=, min=, max=, step=, value=, art= et rotor= n’appartiennent qu’à bar_knob : un bar_button à qui on en passe un est quand même construit en simple bouton, sans rien signaler ; le travail d’un bouton se fait dans on_action. À l’inverse, title= appartient au bouton, et une molette l’ignore.

Effets lumineux

Un plugin peut ajouter son propre éclairage des touches. effects(state) renvoie des entrées light_effect(...), et chacune apparaît dans l’app sous Effets > Des plugins, à côté des styles intégrés et des effets que les gens créent eux-mêmes. Un effet, ce sont des données et non un dessin : une pile de calques que le clavier anime lui-même. Rien ne tourne donc dans le script à chaque image, et les faces, les lettres, le halo, l’éclat à la frappe et la mise en veille fonctionnent comme pour les styles intégrés.

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

Choisir un effet le copie dans les réglages de la personne, il continue donc de fonctionner plugin désactivé. Tant que le plugin est actif et qu’un de ses effets tourne, le clavier relit effects(state) à l’ouverture puis environ une fois par seconde, et reprend ce qui a changé. C’est ainsi qu’un effet suit l’état, l’heure ou 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),
        ]),
    ]

Le bouton effects de l’éditeur liste ce que propose le script. Pour voir un effet bouger, enregistrez le plugin, choisissez l’effet sous Effets > Des plugins et regardez le clavier en haut de cet écran.

Arrondissez tout ce qui fluctue, comme une vitesse de frappe. Un effet qui revient différent à chaque seconde est remplacé à chaque seconde pour rien. Un motif ou un mot-clé inconnu donne une ValueError dans la console de l’éditeur, et un effet sans calque est ignoré.

Apparences

Sept hooks proposent à l’app des choses à choisir : key_styles, themes, popups, animations, backgrounds, trails et layouts. Chacun renvoie des entrées construites avec les appels ci-dessous, et elles apparaissent sous Des plugins à côté des choix intégrés. Les thèmes font exception : ils ont leur propre onglet Plugins dans l’éditeur de thème. Une apparence, ce sont des nombres et des mots, pas du code de dessin, donc rien dans le script ne s’exécute à chaque image. La choisir la copie dans les réglages de la personne, elle continue donc de fonctionner plugin désactivé, et choisir ensuite un choix intégré la met de côté.

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

Renvoyez des nœuds trail depuis trails(state). Chaque traînée possède une palette colors et des couches comme trail_line. Avec color=-1, la ligne forme un dégradé le long du glissement. Activez le plugin, puis choisissez sa traînée dans Des plugins, dans le sélecteur de traînées. Stocker des éléments graphiques dans l’état ne dessine pas de traînée.

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

Une apparence est copiée au moment où on la choisit, donc modifier le script plus tard ne change pas une apparence déjà utilisée ; il faut la choisir à nouveau. Un mot-clé mal orthographié, un mot hors de sa liste ou du texte à la place d’un nombre donne une erreur dans la console de l’éditeur, et les nombres restent dans les plages des réglages de l’app.

Du dessin sur les touches

key_art(state) renvoie un dict des noms de touches vers du dessin, que le clavier peint à l’intérieur de la touche. Les noms de touches sont ceux de haptics, avec les replis letters et keys. Le dessin est une liste de shape(...), une forme seule, un calque art([...]) ou une liste de calques, et chaque calque passe à son dessin suivant à son propre rythme : une touche peut donc porter deux choses qui bougent à des vitesses différentes.

Le dessin est relu après chaque événement entendu par le plugin, et c’est toute la boucle : changer l’état dans on_event(name, info, state), dessiner à partir de lui dans key_art(state). events(state) nomme les événements voulus et est lu une fois au chargement du plugin. Sans lui, un plugin entend tout sauf key, key_down, key_up, predictions et tick, qui font tourner un script à chaque appui ou chaque seconde et doivent être demandés. Les changements de majuscule et de plan redessinent le dessin même si personne n’écoute, et ils arrivent aussi dans 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)}

Seize formes par touche, comptées sur tous ses calques, et 64 points par tracé ; le reste est abandonné. Une forme est dessinée dans une boîte de ses propres width et height, et une boîte sans épaisseur ne peint rien : une ligne horizontale a donc besoin d’un petit height à elle, avec ses points au milieu (height=0.03, points=[[0, 0.5], [1, 0.5]]), sinon elle n’apparaît pas, sans rien dire.

Retour haptique, zones de touche et corrections

haptics(state) et hitboxes(state) renvoient des dicts indexés par nom de touche : la lettre elle-même, "space", "delete", "return", "shift" ou "globe", puis "letters" pour toute lettre non nommée et "keys" pour tout le reste. Les touches qu’un plugin omet gardent les réglages de la personne. Les deux tables sont lues à l’ouverture du clavier puis environ une fois par seconde, donc rien ne s’exécute à chaque frappe pour elles.

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

on_touch(key, x, y, state) s’exécute après chaque appui, une fois l’appui traité, avec l’endroit de la touche où le doigt s’est posé. La position est mesurée par rapport à la touche dessinée, pas à sa cible déplacée, donc un plugin peut déplacer chaque touche vers l’endroit où elle est vraiment touchée sans courir après son propre décalage.

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) place des mots en tête de la barre pendant la saisie d’un mot. correct(word, fix, state) s’exécute une fois par mot quand l’espace le termine, avec la correction du clavier ou None, même avec la correction automatique désactivée. Renvoyez un mot pour l’insérer, False pour garder le mot tel que tapé, ou None pour laisser faire le clavier. Le premier plugin qui répond l’emporte, et une suppression juste après l’annule comme toute correction automatique.

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

Aucun des deux hooks ne s’exécute dans les champs de mot de passe. La puce de correction de la barre montre la correction du clavier, pas ce que correct renverrait, et une table modifiée dans on_touch atteint le clavier au rythme suivant.

Tester dans l'éditeur

L'aperçu de l'éditeur est un clavier de substitution. Il dessine settings(state) en direct, déclenche n'importe quel hook d'une touche avec un mot, une touche ou un type de champ d'exemple, montre la barre d'espace telle que le plugin l'a laissée, et liste tout ce que le plugin a demandé au clavier. stats() y renvoie des chiffres inventés, donc une vitesse s'affiche sans taper.

1. Utilisez les commandes de l'aperçu. Chacune exécute on_action et redessine.
2. Touchez les boutons de hook dans l'ordre où le clavier le ferait : on_open, puis on_word ou on_key quelques fois, puis on_close.
3. Lisez la console. Les commandes apparaissent telles que vous les avez écrites, les lignes de print() en dessous, et une erreur indique sa ligne.
4. Rechargez pour repartir d'un état neuf. Modifier le script ne le réinitialise pas tout seul.

L'aperçu n'a pas de document, donc insert() et replace() ne font que journaliser. Pour les essayer, enregistrez et tapez dans n'importe quel champ avec le clavier ouvert.

Limites

Quand un plugin arrive sous forme de fichier ou depuis un dépôt, Clink le vérifie avant de l'enregistrer. Il doit faire moins de 64 000 octets et 1 600 lignes, définir au moins un hook, n'importer que les modules autorisés et ne contenir aucun des éléments suivants :

Chaque appel de hook dispose de 2 000 000 pas d'interprète, comme un rendu de panneau. Mais on_key s'exécute à chaque frappe, donc un traitement lourd à cet endroit ralentira la saisie bien avant d'atteindre cette limite.

Le fichier

Un plugin est un seul document JSON. id reste stable d'une mise à jour à l'autre, version est du texte libre affiché dans la liste, icon est un nom de SF Symbol, et source est le script avec ses retours à la ligne échappés. Partagez-le depuis l'inspecteur de l'éditeur, ou importez-en un avec le bouton flèche de l'onglet 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..."
}

Les plugins se partagent sous forme de fichiers .clinkplugin, un document JSON qui contient le script. Ils se publient via un dépôt, comme les panneaux, avec un dossier de fichiers, un manifeste et une version. Le dépôt officiel est anti-ltd/clink-plugins.

Quand rien ne se passe

La plupart du temps, c'est l'un de ces cas.