Плагины

Автоматизации

Необязательный объект automation в файле .clinkplugin объявляет события, состояние, настройки, команды, готовые правила и слоты запуска. У каждого компонента есть стабильный ID, точная версия схемы и локализованные названия. Хост создаёт имена plugin/<plugin-id>/<kind>/<id>. Плагин не может занять системное пространство имён или пространство другого плагина.

Как работают плагины

Панель заменяет клавиши, а действие один раз обрабатывает фрагмент текста. У плагина нет собственного экрана на клавиатуре. Clink вызывает его функции в определённые моменты, например когда открывается клавиатура или вы заканчиваете слово, и плагин может обновить пробел или своё сохранённое состояние. Его настройки рисуются в приложении теми же конструкторами, что и панели. Ниже приведён WPM Spacebar, полноценный плагин.

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

Для плагинов нужен Clink Pro. Перед установкой плагина из репозитория Clink попросит разрешить код из этого репозитория, так же как для панелей и действий.

on_key и on_word получают то, что вы набираете: так работает, например, счётчик слов. У PyMini нет доступа к сети и файлам, поэтому плагин не может отправить набранный текст через интернет, а то, что он сохраняет, остаётся в Clink на вашем устройстве.

Ваш первый плагин

Быстрее всего начать со стартового скрипта, который приложение пишет за вас. Он ставит переключатель в «Клавиши» > «Пробел» и, пока тот включён, считает слова на пробеле. Пять шагов, ничего скачивать не нужно.

1. Откройте вкладку «Плагины», включите плагины сверху и нажмите + для нового плагина.
2. Редактор откроется на стартовом скрипте. Прочитайте его один раз: initial(), settings(), on_action(), on_open() и on_word() это всё.
3. Переключитесь на предпросмотр. Включите переключатель, затем несколько раз нажмите on_open и on_word и следите за макетом пробела и консолью.
4. Сохраните. Плагин включён в списке, а его переключатель теперь есть и в «Клавиши» > «Пробел».
5. Откройте клавиатуру где угодно и печатайте. Пробел считает вместе с вами.

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

Хуки

Определите нужные из этих 33 функций, остальные можно не писать. Каждая получает state последним аргументом. Те, что на что-то реагируют, возвращают state, изменённым или нет. Те, что отвечают на вопрос (elements, draw, effects, хуки оформления, haptics, hitboxes, suggestions и correct), возвращают свой ответ и при этом могут менять state на месте.

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

У приложения и клавиатуры одна общая копия состояния. Включите переключатель в приложении, и он будет включён при следующем открытии клавиатуры. Всё, что насчитала клавиатура, будет на месте, когда вы в следующий раз откроете настройки плагина. Клавиатура сохраняет состояние при закрытии, а не после каждой клавиши.

Текущая подсказка на клавише пробела

Читайте основную показанную подсказку через context()["suggestion"]. Подпишитесь на событие predictions, чтобы получать изменения в info["suggestion"]. Для обоих способов нужен доступ к данным ввода. on_suggestion вызывается после выбора подсказки, а не при обновлении вариантов. Вызов space_text(value or None) задаёт подпись или восстанавливает её, когда подсказок нет. Действие клавиши пробела не меняется.

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

Состояние

Состояние это один dict. initial() строит его в первый раз; после этого каждый хук получает тот же dict, меняет его и возвращает. В нём хранится всё, что умещается в JSON: числа, строки, списки, вложенные dict. Приложение сохраняет его после каждого использованного элемента, клавиатура при закрытии, и оба читают один файл, так что они никогда надолго не расходятся.

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

Возвращать state полезная привычка, но не строгое требование: dict это ссылка, так что менять его на месте тоже работает. Верните другой dict, как initial() выше, и он станет состоянием.

Настройки и разделы

settings(state) возвращает дерево узлов, собранное из конструкторов панелей: text, toggle, slider, stepper, segmented, button, row, field и контейнеров компоновки. Оно появляется на странице плагина на вкладке «Плагины». Оберните часть дерева в section(anchor, children, title), и эта часть появится также на одном из экранов настроек самого Clink, рядом с настройкой, к которой она относится.

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

Элементы, которые плагину нужны чаще всего. Каждый либо записывает новое значение в состояние под key, либо называет action для on_action, либо и то и другое. Полный список построителей, включая раскладки, на странице панелей.

Куда попадают разделы

Якорь это идентификатор карточки на одном из собственных экранов настроек Clink. Назовите его в section(), и элементы плагина будут нарисованы прямо под этой карточкой, с именем плагина над ними. Проще всего найти его так: в приложении откройте «Ещё» > «Разработчик» и включите «Показывать идентификаторы». У каждой карточки появится маленький значок с её идентификатором, нажатие копирует его; страницы показывают свой в заголовке.

У keys.spacebar есть собственное место на самом экране пробела. Раздел с якорем, которого нет в этом списке, всё равно показывается на странице плагина, так что опечатка стоит вам карточки, а не плагина.

Занятые элементы

Когда плагин управляет одной из настроек Clink, человек должен это видеть, и они не должны спорить. claim(control) говорит, что плагин владеет ей: приложение называет плагин на карточке этой настройки, а поле текста пробела блокируется, пока плагин её держит. release(control) возвращает её. Занимайте в том on_action, который включает вашу функцию, отпускайте в том, который выключает, и одновременно возвращайте значение в None или к прежнему. Плагин, выключенный в списке, отпускает всё, что удерживал.

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

Два плагина могут занять один элемент; приложение назовёт тот, что сделал это последним. Занятость записывает приложение, поэтому занимайте из on_action, который выполняется там. Занятость, сделанная внутри клавиатуры, не запоминается.

Команды и чтения

Плагинам доступны все команды панелей, а также шесть собственных команд и два чтения. Команды ставятся в очередь и применяются после возврата из вашей функции, поэтому на клавиатуре ничего не меняется посреди вызова. Чтения возвращают значения такими, какими они были непосредственно перед вызовом.

setting(name) и set_setting(name, value) используют один список имён, и claim(control) тоже принимает любое из них. Логические значения читаются как True или False, числа как числа, варианты по их id. Список длинный намеренно: плагин может реагировать почти на всё, что человек может настроить в приложении, или управлять этим.

Как и view() у панели, settings() должна только описывать элементы управления. Команды, вызванные из неё, игнорируются и записываются в консоль.

Примеры

Пять небольших плагинов, каждый законченный. Вставьте один в новый плагин, сохраните, и он работает.

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

Элементы в раскладке

Пользовательская раскладка собирается из клавиш и элементов: полоса недавних эмодзи, ряд цифр, курсорная площадка. Плагин может добавить свои. elements(state) сообщает, что он предлагает, а draw(id, state) рисует элемент, так что клавиша может показывать всё, что плагин умеет вычислять: график скорости набора, часы, обратный отсчёт или собственный индикатор заряда.

Элемент собирают два хука. elements(state) перечисляет, что вы предлагаете, по одной записи на элемент, и приложение читает это для палитры редактора раскладок. draw(id, state) получает один из этих идентификаторов и возвращает, что рисовать. Плагин может предложить несколько; draw спрашивают о каждом по имени.

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

Вид элемента это дерево узлов, как у страницы настроек, но клавиша не страница настроек: используются только рисующие узлы, а всё нажимаемое игнорируется. Клавиша уже принадлежит раскладке, поэтому внутри неё нет места для кнопки.

Рассчитывайте на клавишу. width измеряется в ширинах клавиши: 1 это буква, 3 примерно треть ряда, и человек потом может изменить размер. Текст занимает одну строку и ужимается, чтобы поместиться; цвета по умолчанию берутся от цвета текста клавиши, так что элемент подходит к соседним клавишам, пока вы не попросите другой. Sparkline хранит последние 120 точек, больше, чем клавиша способна показать.

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)

Элементы живут в пользовательских раскладках, так что сперва нужно собрать раскладку. Готовые её не удержат: скопировать готовую раскладку в свою это первое, что предложит редактор.

1. Установите плагин и включите его. Его элементы появятся сразу же.
2. Откройте «Раскладка», создайте или скопируйте свою раскладку и перейдите в «Расположение».
3. Нажмите «Элемент», выберите элемент плагина в полосе и задайте ширину.

Предпросмотр в редакторе рисует каждый элемент, который предлагает скрипт, примерно в размер клавиши, где он окажется, под макетом пробела. Сохраните, разместите один раз, и клавиатура нарисует то же самое.

Элемент показывает только то, что рисует плагин: нажатие на него ничего не делает, потому что клавиша уже принадлежит раскладке. Раскладка хранит элемент, даже когда плагин выключен или удалён, и клавиша снова заполняется, когда он возвращается.

Кнопки и регуляторы в верхней панели

Полоса над клавишами собирается в разделе «Раскладка» > «Верхняя панель», и плагин может предложить для неё свои элементы управления. bar_items(state) их возвращает: bar_button(...) для нажатия, bar_knob(...) для вращения. Список читается при открытии клавиатуры и заново после каждого нажатия, поэтому элемент может появляться и исчезать вместе с состоянием плагина.

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

И то и другое возвращается через on_action(action, value, state) по id элемента, так что элементы панели и настройки плагина делят один хук. Нажатие присылает None. Регулятор присылает значение на каждом щелчке, пока палец не отпущен, и ещё раз при отпускании, так что плагин может следить за движением или дождаться последнего значения.

Регулятор с setting= крутит значение, которое у приложения уже есть, из списка «Команды и чтения» выше, например sound.volume или haptics.intensity. Имя, которого приложение не знает, даёт KeyError в консоли. Диапазон и начальное положение берутся из этой настройки, собственная копия клавиатуры меняется прямо во время перетаскивания, так что следующее нажатие уже звучит на новом уровне, а значение сохраняется при отпускании. Регулятор громкости или отдачи, поднятый с нуля, на время жеста снова включает звук или вибрацию, чтобы щелчки были слышны и ощутимы по пути вверх; сохраняет этот переключатель сам плагин вызовом set_setting в on_action.

Регулятор можно нарисовать на Python. art= это неподвижная часть, оправа или корпус, а rotor= вращающаяся лицевая сторона: -135 градусов на минимуме и +135 градусов на максимуме. Оба принимают те же фигуры, заливки, градиенты и тени, что и графика клавиш, до шестнадцати фигур в каждом, а unit="key" масштабирует координаты к квадратному циферблату, где стрелка с отрицательным y смотрит вверх. Рисунку передаются цвет текста панели как "text" и акцент темы как "accent". Если опустить оба, регулятор будет кольцом со значком внутри; в редакторе уже стоящему в панели регулятору можно к тому же выбрать любую встроенную отделку.

Само по себе в панель ничего не попадает. Элемент ставят вручную, как меню и подсказки.

1. Установите плагин и включите его. Его элементы панели появятся сразу.
2. Откройте «Раскладка» > «Верхняя панель».
3. Добавьте кнопку или регулятор плагина и перетащите на нужное место. Для регулятора можно ещё выбрать отделку.

Конструкторы молча пропускают незнакомое ключевое слово, без ошибки. setting=, min=, max=, step=, value=, art= и rotor= принадлежат только bar_knob, так что bar_button с любым из них всё равно соберётся как обычная кнопка, и ничего об этом не скажут: работа кнопки живёт в on_action. И наоборот, title= принадлежит кнопке, а регулятор его пропускает.

Эффекты подсветки

Плагин может добавить свою подсветку клавиш. effects(state) возвращает записи light_effect(...), и каждая появляется в приложении в разделе «Эффекты > Из плагинов», рядом со встроенными стилями и эффектами, которые люди создают сами. Эффект это данные, а не рисунок: стопка слоёв, которую клавиатура анимирует сама. Поэтому в скрипте ничего не выполняется на каждом кадре, а поверхности клавиш, буквы, свечение, вспышка при нажатии и сон в простое работают так же, как у встроенных стилей.

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

Выбранный эффект копируется в настройки пользователя, поэтому работает и с выключенным плагином. Пока плагин включён и один из его эффектов активен, клавиатура перечитывает effects(state) при открытии и затем примерно раз в секунду и подставляет то, что изменилось. Так эффект следует за состоянием, временем или 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),
        ]),
    ]

Кнопка effects в редакторе показывает, что предлагает скрипт. Чтобы увидеть эффект в движении, сохраните плагин, выберите эффект в разделе «Эффекты > Из плагинов» и смотрите на клавиатуру вверху этого экрана.

Округляйте всё, что дёргается, например скорость печати. Эффект, который каждую секунду возвращается другим, каждую секунду заменяется впустую. Неизвестный узор или ключевое слово дают ValueError в консоли редактора, а эффект без слоёв пропускается.

Оформление

Семь хуков предлагают приложению варианты на выбор: key_styles, themes, popups, animations, backgrounds, trails и layouts. Каждый возвращает записи, собранные вызовами ниже, и они появляются в разделе «Из плагинов» рядом со встроенными вариантами. Исключение составляют темы: у них в редакторе тем своя вкладка «Плагины». Оформление состоит из чисел и слов, а не из кода рисования, поэтому в скрипте ничего не выполняется на каждом кадре. Выбранный вариант копируется в настройки человека, поэтому работает и с выключенным плагином, а выбор встроенного варианта после этого откладывает его в сторону.

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

Возвращайте узлы trail из trails(state). У каждого следа есть палитра colors и слои, например trail_line. При color=-1 цвета плавно переходят друг в друга вдоль свайпа. Включите плагин, затем выберите его след в разделе «Из плагинов» в списке следов. Само по себе сохранение графики в состоянии не рисует след.

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

Оформление копируется в момент выбора, поэтому изменение скрипта потом не меняет уже выбранный вариант; его нужно выбрать снова. Ключевое слово с опечаткой, слово не из своего списка или текст на месте числа дают ошибку в консоли редактора, а числа удерживаются в тех же пределах, что и у регуляторов самого приложения.

Рисунок на клавишах

key_art(state) возвращает dict из имён клавиш в рисунок, и клавиатура рисует его внутри клавиши. Имена клавиш те же, что у haptics, с запасными letters и keys. Рисунок это список shape(...), одна фигура, слой art([...]) или список слоёв, и каждый слой переходит к следующему рисунку по своим часам, так что одна клавиша может нести две вещи, движущиеся с разной скоростью.

Рисунок перечитывается после каждого события, которое слышит плагин, и в этом вся петля: меняете состояние в on_event(name, info, state) и рисуете из него в key_art(state). events(state) называет нужные события и читается один раз при загрузке плагина. Без него плагин слышит всё, кроме key, key_down, key_up, predictions и tick, которые запускают скрипт на каждое нажатие или каждую секунду и потому запрашиваются отдельно. Смена регистра и плоскости перерисовывает рисунок независимо от того, слушает ли кто-нибудь, и доходит также до 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)}

Шестнадцать фигур на клавишу, считая все её слои, и 64 точки на контур; всё сверх этого отбрасывается. Фигура рисуется внутри коробки своих width и height, а коробка без толщины не рисует ничего, поэтому горизонтальной линии нужна своя небольшая height с точками по её середине (height=0.03, points=[[0, 0.5], [1, 0.5]]), иначе она молча не появится.

Тактильная отдача, зоны нажатия и исправления

haptics(state) и hitboxes(state) возвращают dict с именами клавиш в ключах: сама буква, "space", "delete", "return", "shift" или "globe", затем "letters" для любой не названной буквы и "keys" для всего остального. Клавиши, которые плагин не назвал, сохраняют собственные настройки человека. Обе таблицы читаются при открытии клавиатуры и примерно раз в секунду, так что ради них ничего не выполняется на каждое нажатие.

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

on_touch(key, x, y, state) вызывается после каждого нажатия, когда оно уже обработано, с местом на клавише, куда опустился палец. Положение отсчитывается от нарисованной клавиши, а не от её сдвинутой цели, поэтому плагин может сдвигать каждую клавишу туда, куда по ней на самом деле попадают, не гоняясь за собственным сдвигом.

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) ставит слова в начало панели, пока набирается слово. correct(word, fix, state) вызывается один раз на слово, когда его завершает пробел, с исправлением клавиатуры или None, даже при выключенной автокоррекции. Верните слово, чтобы вставить его, False, чтобы оставить слово как набрано, или None, чтобы решила клавиатура. Побеждает первый ответивший плагин, а удаление сразу после отменяет замену, как любую автокоррекцию.

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

Ни один из этих хуков не вызывается в полях пароля. Подсказка исправления на панели показывает исправление клавиатуры, а не то, что вернул бы correct, и таблица, изменённая в on_touch, доходит до клавиатуры на следующем такте.

Проверка в редакторе

Предпросмотр в редакторе это клавиатура-заместитель. Он рисует settings(state) вживую, по нажатию запускает любой хук с образцовым словом, клавишей или типом поля, показывает пробел таким, каким его оставил плагин, и перечисляет всё, что плагин запросил у клавиатуры. stats() там возвращает выдуманные числа, так что скорость появляется без набора.

1. Используйте элементы в предпросмотре. Каждый запускает on_action и перерисовывает.
2. Нажимайте кнопки хуков в том порядке, в каком это делала бы клавиатура: on_open, затем несколько раз on_word или on_key, затем on_close.
3. Читайте консоль. Команды показаны так, как вы их написали, строки print() под ними, а ошибка называет свою строку.
4. Перезагрузите, чтобы начать состояние заново. Правка скрипта сама по себе его не сбрасывает.

В предпросмотре нет документа, поэтому insert() и replace() только пишут в журнал. Чтобы их проверить, сохраните и печатайте в любом поле с открытой клавиатурой.

Ограничения

Когда плагин приходит файлом или из репозитория, Clink проверяет его перед сохранением. Он должен быть меньше 64 000 байт и 1 600 строк, определять хотя бы один хук, импортировать только разрешённые модули и не содержать ничего из этого списка:

Каждый вызов хука получает 2 000 000 шагов интерпретатора, столько же, сколько отрисовка панели. Но on_key выполняется при каждом нажатии, поэтому тяжёлая работа в нём замедлит набор задолго до того, как упрётся в этот лимит.

Файл

Плагин это один JSON-документ. id не меняется между обновлениями, version это свободный текст, показанный в списке, icon это имя SF Symbol, а source это скрипт с экранированными переносами строк. Поделитесь им из инспектора редактора или импортируйте кнопкой со стрелкой на вкладке «Плагины».

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

Плагины распространяются как файлы .clinkplugin: это JSON-документ со скриптом внутри. Они публикуются через репозиторий так же, как панели, с папкой файлов, манифестом и выпуском. Официальный репозиторий: anti-ltd/clink-plugins.

Когда что-то не происходит

Чаще всего дело в одном из этого.