Plugins

Automatizaciones

El objeto automation opcional de un archivo .clinkplugin declara eventos, estado, ajustes, comandos, preajustes y espacios para atajos. Cada aportación tiene un identificador estable, una versión de esquema exacta y títulos localizados. El anfitrión crea nombres con el formato plugin/<plugin-id>/<kind>/<id>. Un plugin no puede usar el espacio de nombres del sistema ni el de otro plugin.

Cómo funcionan los plugins

Un panel sustituye a las teclas y una acción se ejecuta una vez sobre un texto. Un plugin no tiene pantalla propia en el teclado. Clink llama a sus funciones en momentos concretos, como cuando se abre el teclado o terminas una palabra, y el plugin puede cambiar la barra espaciadora o su propio estado guardado. Sus ajustes se dibujan en la app con los mismos constructores que usan los paneles. WPM Spacebar, más abajo, es 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

Los plugins requieren Clink Pro. Antes de instalar uno desde un repositorio, Clink te pide que permitas el código de ese repositorio, igual que con los paneles y las acciones.

on_key y on_word reciben lo que escribes, que es lo que permite contar palabras. PyMini no tiene acceso a la red ni a archivos, así que un plugin no puede enviar lo que escribes por internet, y lo que guarda se queda en Clink, en tu dispositivo.

Tu primer plugin

La forma más rápida de empezar es el script inicial que la app escribe por ti. Pone un interruptor en Teclas > Barra espaciadora y, mientras está activo, cuenta palabras en la barra. Cinco pasos, sin archivos que descargar.

1. Abre la pestaña Plugins, activa los plugins arriba y toca + para crear uno nuevo.
2. El editor se abre con el script inicial. Léelo una vez: initial(), settings(), on_action(), on_open() y on_word() son todo.
3. Cambia a Vista previa. Activa el interruptor, toca on_open y on_word unas cuantas veces y observa la barra espaciadora simulada y la consola.
4. Guarda. El plugin queda activado en la lista y su interruptor aparece también en Teclas > Barra espaciadora.
5. Abre el teclado en cualquier sitio y escribe. La barra espaciadora va contando.

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

Define las funciones de estas 33 que necesites y omite las demás. Cada una recibe state como último argumento. Las que reaccionan a algo devuelven state, con cambios o sin ellos. Las que responden a una pregunta (elements, draw, effects, los hooks de aspecto, haptics, hitboxes, suggestions y correct) devuelven su respuesta, y aun así pueden cambiar state directamente.

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

La app y el teclado comparten una sola copia del estado. Si activas un interruptor en la app, estará activado la próxima vez que se abra el teclado. Lo que cuente el teclado estará ahí la próxima vez que abras los ajustes del plugin. El teclado guarda el estado al cerrarse, no después de cada tecla.

Sugerencia actual en la barra espaciadora

Lee la sugerencia principal que se muestra con context()["suggestion"]. Suscríbete al evento predictions para recibir los cambios en info["suggestion"]. Ambos requieren acceso a los datos de escritura. on_suggestion se ejecuta al aceptar una sugerencia, no al cambiar las predicciones. Usa space_text(value or None) para cambiar la etiqueta o restaurarla cuando no haya sugerencias. La acción de la barra espaciadora no 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

Estado

El estado es un solo dict. initial() lo construye la primera vez; después, cada hook recibe el mismo dict, lo cambia y lo devuelve. Guarda todo lo que puede guardar JSON: números, cadenas, listas, dicts anidados. La app lo guarda después de cada control que usas, el teclado al cerrarse, y ambos leen el mismo archivo, así que nunca discrepan mucho tiempo.

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

Devolver el estado es el hábito recomendable, pero no es estrictamente obligatorio: el dict es una referencia, así que cambiarlo en el sitio también funciona. Devuelve otro dict, como initial() arriba, y ese pasa a ser el estado.

Ajustes y secciones

settings(state) devuelve un árbol de nodos construido con los constructores de panel: text, toggle, slider, stepper, segmented, button, row, field y los diseños. Aparece en la página del plugin, en la pestaña Plugins. Envuelve una parte en section(anchor, children, title) y esa parte también aparece en una de las pantallas de ajustes de Clink, junto al ajuste con el que tiene que ver.

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

Los controles que un plugin necesita más a menudo. Cada uno escribe su nuevo valor en el estado bajo key, o indica una action para on_action, o ambas cosas. La lista completa de constructores, incluidos los diseños, está en la página de paneles.

Dónde van las secciones

Un ancla es el ID de una tarjeta en una de las pantallas de ajustes de Clink. Indícala en section() y los controles del plugin se dibujan justo debajo de esa tarjeta, con el nombre del plugin encima. La forma más fácil de encontrar una: en la app, abre Más > Desarrollador y activa Mostrar IDs. Cada tarjeta recibe una pequeña insignia de información que muestra su ID y lo copia al tocarla; las páginas muestran el suyo en la barra de título.

keys.spacebar tiene un lugar propio, en la propia pantalla de la barra espaciadora. Una sección con un ancla que no esté en esta lista sigue apareciendo en la página del plugin, así que una errata te cuesta una tarjeta, no el plugin.

Reclamaciones

Cuando un plugin maneja uno de los ajustes de Clink, la persona debe verlo, y los dos no deben pelearse. claim(control) declara que el plugin lo posee: la app muestra el nombre del plugin en la tarjeta de ese ajuste, y el campo de texto de la barra espaciadora se bloquea mientras lo tiene. release(control) lo devuelve. Reclama en el on_action que activa tu función, libera en el que la desactiva, y devuelve el valor a None o a su valor anterior al mismo tiempo. Un plugin desactivado en la lista libera todo lo que tenía.

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

Dos plugins pueden reclamar el mismo control; la app nombra al que lo reclamó por último. Las reclamaciones las registra la app, así que reclama desde on_action, que se ejecuta ahí. Una reclamación hecha dentro del teclado no se recuerda.

Comandos y lecturas

Los plugins pueden usar todos los comandos de panel, además de seis comandos y dos lecturas propios. Los comandos se ponen en cola y se aplican cuando tu función termina, así que nada cambia en el teclado a mitad de una llamada. Las lecturas devuelven los valores tal como estaban justo antes de la llamada.

setting(name) y set_setting(name, value) comparten una lista de nombres, y claim(control) también acepta cualquiera de ellos. Los booleanos se leen como True o False, los números como números, las opciones como su id. La lista es larga a propósito: un plugin puede reaccionar a casi todo lo que una persona puede ajustar en la app, o manejarlo.

Igual que el view() de un panel, settings() solo debe describir controles. Los comandos que se llamen desde ahí se ignoran y se registran en la consola.

Ejemplos

Cinco plugins pequeños, cada uno completo. Pega uno en un plugin nuevo, guarda y funciona.

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

Elementos en un diseño

Un diseño personalizado se construye con teclas y elementos: una tira de emojis recientes, una fila de dígitos, un panel de cursor. Un plugin puede añadir los suyos. elements(state) dice qué ofrece y draw(id, state) pinta uno, así que una tecla puede mostrar cualquier cosa que el plugin sepa calcular: un gráfico de velocidad, un reloj, una cuenta atrás, tu propia batería.

Dos hooks construyen uno. elements(state) enumera lo que ofreces, una entrada por elemento, y la app lo lee para llenar la paleta del editor de diseños. draw(id, state) recibe uno de esos ids y devuelve qué pintar. Un plugin puede ofrecer varios; a draw se le pregunta por cada uno por su nombre.

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

Una cara es un árbol de nodos, como una página de ajustes, pero una tecla no es una página de ajustes: solo se usan los nodos que dibujan y se ignora todo lo que se pueda tocar. La tecla ya pertenece al diseño, así que dentro no hay sitio para un botón.

Dimensiónalo para una tecla. width se mide en anchos de tecla: 1 es una letra y 3 es como un tercio de fila, y la persona puede cambiarlo después. El texto tiene una línea y se encoge para caber; los colores siguen por defecto al color de texto de la tecla, así que un elemento combina con las teclas de alrededor salvo que pidas otro. Una sparkline guarda sus últimos 120 puntos, más de los que cabe mostrar en una tecla.

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)

Los elementos viven en diseños personalizados, así que primero hay que construir uno. Los preajustes no pueden llevarlos: bifurcar un preajuste en tu propio diseño es lo primero que ofrece el editor.

1. Instala el plugin y actívalo. Sus elementos aparecen en cuanto lo haces.
2. Abre Diseño, crea o bifurca un diseño personalizado y ve a Organizar.
3. Toca Elemento, elige el elemento del plugin en la tira y ajusta su ancho.

La vista previa del editor dibuja cada elemento que ofrece el script, más o menos del tamaño de la tecla donde irá, bajo la maqueta de la barra espaciadora. Guarda y colócalo una vez, y el teclado dibuja lo mismo.

Un elemento solo muestra lo que el plugin dibuja: tocarlo no hace nada, porque la tecla ya es del diseño. El diseño conserva el elemento aunque su plugin esté apagado o desinstalado, y la tecla se vuelve a llenar cuando el plugin regresa.

Botones y ruedas en la barra superior

La franja sobre las teclas se organiza en Diseño > Barra superior, y un plugin puede ofrecer sus propios controles para ella. bar_items(state) los devuelve: bar_button(...) para algo que se toca, bar_knob(...) para algo que se gira. La lista se lee al abrirse el teclado y otra vez tras cada toque, así que un elemento puede aparecer y desaparecer con el estado 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

Ambos vuelven por on_action(action, value, state), identificados por el id del elemento, así que los elementos de barra de un plugin y sus controles de ajustes comparten un mismo hook. Un toque envía None. Una rueda envía su valor en cada muesca mientras el dedo sigue abajo y una vez más al soltarla, así que un plugin puede seguir el arrastre o esperar al último valor.

Una rueda con setting= gira un ajuste que la app ya tiene, tomado de la lista que hay más arriba en Comandos y lecturas, como sound.volume o haptics.intensity. Un nombre que la app no conoce es un KeyError en la consola. El rango y la posición inicial vienen de ese control, la copia del propio teclado cambia mientras arrastras, así que la siguiente tecla ya suena al nuevo nivel, y el valor se guarda al soltar. Una rueda de volumen o de vibración subida desde cero también vuelve a encender el sonido o la vibración durante el arrastre, para que las muescas se oigan y se sientan al subir; guardar ese interruptor es cosa del propio set_setting del plugin en on_action.

Una rueda se puede dibujar en Python. art= es la parte que se queda quieta, el aro o el cuerpo, y rotor= es la cara que gira, de -135 grados en el mínimo a +135 grados en el máximo. Las dos aceptan las mismas formas, pinturas, degradados y sombras que el arte de tecla, hasta dieciséis formas cada una, y unit="key" escala las coordenadas al dial cuadrado, donde una aguja con y negativa apunta hacia arriba. Al dibujo se le pasa el color de texto de la barra como "text" y el acento del tema como "accent". Si dejas las dos fuera, la rueda es un anillo con el icono dentro; en el editor también se le puede dar a una rueda ya puesta cualquiera de los acabados incluidos.

Nada llega a la barra por su cuenta. Un elemento se coloca a mano, igual que el menú y las sugerencias.

1. Instala el plugin y actívalo. Sus elementos de barra aparecen enseguida.
2. Abre Diseño > Barra superior.
3. Añade el botón o la rueda del plugin y arrástralo hasta su sitio. A una rueda además se le elige un acabado.

Los builders pasan por alto una palabra clave que no conocen, sin dar error. setting=, min=, max=, step=, value=, art= y rotor= son solo de bar_knob, así que un bar_button al que se le pasa una se construye igual como botón simple y no se dice nada: el trabajo de un botón va en on_action. Al revés, title= es del botón, y una rueda lo pasa por alto.

Efectos de luz

Un plugin puede añadir su propia iluminación de teclas. effects(state) devuelve entradas light_effect(...), y cada una aparece en la app en Efectos > De plugins, junto a los estilos de serie y los efectos que crea la gente. Un efecto son datos, no un dibujo: una pila de capas que el teclado anima por su cuenta, así que en el script no se ejecuta nada por fotograma, y las caras, las letras, el brillo, el destello al pulsar y el reposo funcionan igual que con los estilos de serie.

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

Al elegir un efecto, se copia en los ajustes de la persona, así que sigue funcionando con el plugin apagado. Mientras el plugin está activo y uno de sus efectos está en marcha, el teclado vuelve a leer effects(state) al abrirse y después más o menos una vez por segundo, y cambia lo que haya cambiado. Así un efecto sigue al estado, a la hora o a 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),
        ]),
    ]

El botón effects del editor muestra lo que ofrece el script. Para verlo en movimiento, guarda el plugin, elige el efecto en Efectos > De plugins y mira el teclado de la parte superior de esa pantalla.

Redondea lo que tiemble, como una velocidad de escritura. Un efecto que vuelve distinto cada segundo se sustituye cada segundo para nada. Un patrón o una palabra clave desconocidos son un ValueError en la consola del editor, y un efecto sin capas se descarta.

Aspectos

Siete hooks ofrecen a la app cosas para elegir: key_styles, themes, popups, animations, backgrounds, trails y layouts. Cada uno devuelve entradas creadas con las llamadas de abajo, y aparecen en De plugins junto a las opciones incluidas. Los temas son la excepción: tienen su propia pestaña Plugins en el editor de temas. Un aspecto son números y palabras, no código de dibujo, así que nada del script se ejecuta en cada fotograma. Al elegir uno se copia en los ajustes de la persona, así que sigue funcionando con el plugin desactivado, y elegir después una opción incluida lo aparta.

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

Devuelve nodos trail desde trails(state). Cada estela tiene una paleta colors y capas como trail_line. Con color=-1, la línea mezcla los colores a lo largo del deslizamiento. Activa el plugin y elige su estela en De plugins, dentro del selector de estelas. Guardar gráficos en el estado no dibuja una estela.

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 aspecto se copia al elegirlo, así que cambiar el script después no cambia un aspecto que alguien ya usa; hay que elegirlo otra vez. Una palabra clave mal escrita, una palabra fuera de su lista o texto donde va un número es un error en la consola del editor, y los números se mantienen en los rangos que usan los controles de la propia app.

Dibujo en las teclas

key_art(state) devuelve un dict de nombres de tecla a dibujo, y el teclado lo pinta dentro de la tecla. Los nombres de tecla son los de haptics, con los recursos letters y keys. El dibujo es una lista de shape(...), una sola forma, una capa art([...]) o una lista de capas, y cada capa pasa a su siguiente dibujo con su propio reloj, así que una tecla puede llevar dos cosas moviéndose a velocidades distintas.

El dibujo se vuelve a leer tras cada evento que el plugin escucha, y ese es todo el ciclo: cambia el estado en on_event(name, info, state) y dibuja a partir de él en key_art(state). events(state) nombra los eventos que quieres y se lee una vez al cargarse el plugin. Sin él, un plugin oye todo menos key, key_down, key_up, predictions y tick, que hacen correr un script por pulsación o por segundo y hay que pedirlos. Los cambios de mayúsculas y de plano redibujan el arte aunque nadie escuche, y también llegan a 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)}

Dieciséis formas por tecla, contando todas sus capas, y 64 puntos por trazado; lo que pase de ahí se descarta. Una forma se dibuja dentro de una caja de su propio width y height, y una caja sin grosor no pinta nada, así que una línea horizontal necesita un height pequeño propio con sus puntos por el medio (height=0.03, points=[[0, 0.5], [1, 0.5]]) o no aparece y no avisa.

Vibración, zonas de toque y correcciones

haptics(state) y hitboxes(state) devuelven dicts cuyas claves son nombres de tecla: la propia letra, "space", "delete", "return", "shift" o "globe", luego "letters" para cualquier letra no nombrada y "keys" para todo lo demás. Las teclas que un plugin no nombra conservan los ajustes de la persona. Ambas tablas se leen al abrirse el teclado y más o menos una vez por segundo, así que nada se ejecuta en cada pulsación por ellas.

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

on_touch(key, x, y, state) se ejecuta tras cada toque, una vez atendido, con el punto de la tecla donde cayó el dedo. La posición se mide respecto a la tecla dibujada, no a su objetivo desplazado, así que un plugin puede mover cada tecla hacia donde de verdad se toca sin perseguir su propio desplazamiento.

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) pone palabras al principio de la barra mientras se escribe una palabra. correct(word, fix, state) se ejecuta una vez por palabra cuando el espacio la termina, con la corrección del teclado o None, incluso con la autocorrección desactivada. Devuelve una palabra para escribirla, False para dejar la palabra como se escribió o None para dejarlo en manos del teclado. Gana el primer plugin que responde, y borrar justo después lo deshace como cualquier autocorrección.

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

Ninguno de los dos hooks se ejecuta en campos de contraseña. La sugerencia de corrección de la barra muestra la corrección del teclado, no lo que devolvería correct, y una tabla cambiada en on_touch llega al teclado en el siguiente ciclo.

Probar en el editor

La Vista previa del editor es un teclado sustituto. Dibuja settings(state) en vivo, dispara cualquier hook con un toque usando una palabra, tecla o tipo de campo de ejemplo, muestra la barra espaciadora tal como la dejó el plugin y enumera todo lo que el plugin le pidió al teclado. Allí stats() devuelve números inventados, así que aparece una velocidad sin escribir.

1. Usa los controles de la vista previa. Cada uno ejecuta on_action y vuelve a dibujar.
2. Toca los botones de hook en el orden en que lo haría el teclado: on_open, luego on_word u on_key unas cuantas veces, luego on_close.
3. Lee la consola. Los comandos aparecen tal como los escribiste, las líneas de print() debajo, y un error indica su línea.
4. Recarga para reiniciar el estado. Editar el script no lo reinicia por sí solo.

La vista previa no tiene documento, así que insert() y replace() solo se registran. Para probarlos, guarda y escribe en cualquier campo con el teclado abierto.

Límites

Cuando un plugin llega como archivo o desde un repositorio, Clink lo comprueba antes de guardarlo. Tiene que ocupar menos de 64.000 bytes y 1600 líneas, definir al menos un hook, importar solo los módulos permitidos y no contener nada de lo siguiente:

Cada llamada a un hook dispone de 2.000.000 pasos de intérprete, los mismos que el renderizado de un panel. Pero on_key se ejecuta en cada pulsación, así que un trabajo pesado ahí ralentizará la escritura mucho antes de llegar a ese límite.

El archivo

Un plugin es un solo documento JSON. id se mantiene estable entre actualizaciones, version es texto libre que se muestra en la lista, icon es el nombre de un SF Symbol y source es el script con los saltos de línea escapados. Compártelo desde el inspector del editor o importa uno con el botón de flecha de la pestaña 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..."
}

Los plugins se comparten como archivos .clinkplugin, un documento JSON con el script dentro. Se publican a través de un repositorio igual que los paneles, con una carpeta de archivos, un manifiesto y una versión. El repositorio oficial es anti-ltd/clink-plugins.

Cuando algo no pasa

Casi siempre es una de estas cosas.