Bővítmények

Automatizálások

A .clinkplugin fájl opcionális automation objektuma eseményeket, állapotot, beállításokat, parancsokat, kész szabályokat és parancsikonhelyeket deklarál. Minden elemnek stabil azonosítója, pontos sémaverziója és lokalizált címe van. A gazda hozza létre a plugin/<plugin-id>/<kind>/<id> neveket. Egy bővítmény nem használhat rendszerbeli vagy másik bővítményhez tartozó névteret.

Hogyan működnek a bővítmények

A panel a billentyűket váltja fel, a művelet pedig egyszer fut le egy szövegrészen. A bővítménynek nincs saját képernyője a billentyűzeten. A Clink meghatározott pillanatokban hívja a függvényeit, például amikor megnyílik a billentyűzet, vagy amikor befejezel egy szót, a bővítmény pedig frissítheti a szóközt vagy a saját mentett állapotát. A beállításai az appban jelennek meg, ugyanazokkal az építőelemekkel, amelyeket a panelek is használnak. A lenti WPM Spacebar egy teljes bővítmény.

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

A bővítményekhez Clink Pro szükséges. Mielőtt tárolóból telepítenél egyet, a Clink megkérdezi, engedélyezed-e az abból a tárolóból származó kódot, ugyanúgy, mint a paneleknél és a műveleteknél.

Az on_key és az on_word megkapja, amit gépelsz, egy szószámláló is így működik. A PyMini nem fér hozzá a hálózathoz és a fájlokhoz, ezért a bővítmény nem tudja elküldeni az interneten, amit gépelsz, amit pedig elment, az a Clinknél marad a készülékeden.

Az első bővítményed

A leggyorsabb út az indító szkript, amelyet az app ír meg neked. Egy kapcsolót tesz a Billentyűk > Szóköz alá, és amíg a kapcsoló be van kapcsolva, szavakat számol a szóközön. Öt lépés, letöltés nélkül.

1. Nyisd meg a Bővítmények lapot, kapcsold be a bővítményeket felül, és koppints a + jelre egy új bővítményhez.
2. A szerkesztő az indító szkripttel nyílik meg. Olvasd végig egyszer: initial(), settings(), on_action(), on_open() és on_word() az egész.
3. Válts az Előnézetre. Kapcsold át a kapcsolót, majd koppints néhányszor az on_open és on_word gombokra, és figyeld a szóköz makettjét és a konzolt.
4. Mentés. A bővítmény be van kapcsolva a listában, és a kapcsolója most már a Billentyűk > Szóköz alatt is ott van.
5. Nyisd meg a billentyűzetet bárhol, és gépelj. A szóköz számol veled.

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

Horogpontok

Definiáld a 33 függvény bármelyikét, a feleslegeseket pedig hagyd ki. Mindegyik utolsó argumentumként megkapja a state értéket. Amelyek valamire reagálnak, visszaadják a state értéket, akár módosították, akár nem. Amelyek egy kérdésre felelnek (elements, draw, effects, a megjelenési horogpontok, haptics, hitboxes, suggestions és correct), a válaszukat adják vissza, és közben helyben is módosíthatják a state értéket.

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

Az app és a billentyűzet az állapot egyetlen példányán osztozik. Ha az appban bekapcsolsz egy kapcsolót, a billentyűzet következő megnyitásakor be lesz kapcsolva. Amit a billentyűzet számol, az ott lesz, amikor legközelebb megnyitod a bővítmény beállításait. A billentyűzet bezáráskor menti az állapotot, nem minden billentyű után.

Aktuális javaslat a szóközbillentyűn

A fő megjelenített javaslatot a context()["suggestion"] értékéből olvashatod ki. Iratkozz fel a predictions eseményre, hogy a változásokat az info["suggestion"] mezőben kapd meg. Mindkettőhöz hozzáférés kell a gépelési adatokhoz. Az on_suggestion egy javaslat elfogadásakor fut le, nem a javaslatok változásakor. A space_text(value or None) beállítja a feliratot, vagy visszaállítja, ha nincs javaslat. A szóközbillentyű működése nem változik.

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

Állapot

Az állapot egyetlen dict. Az initial() építi fel először; utána minden horogpont ugyanazt a dict-et kapja, módosítja és visszaadja. Bármit tárol, amit a JSON tud: számokat, sztringeket, listákat, egymásba ágyazott dict-eket. Az app minden használt vezérlő után menti, a billentyűzet bezáráskor, és mindkettő ugyanazt a fájlt olvassa, így sosem térnek el sokáig.

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

Az állapot visszaadása jó szokás, de nem kötelező: a dict referencia, ezért a helyben módosítás is működik. Adj vissza egy másik dict-et, mint fent az initial(), és az lesz az állapot.

Beállítások és szakaszok

A settings(state) a panelépítőkkel készült csomópontfát ad vissza: text, toggle, slider, stepper, segmented, button, row, field és az elrendezések. Ez a bővítmény oldalán jelenik meg a Bővítmények lapon. Ha egy részét section(anchor, children, title) hívásba csomagolod, az a rész a Clink egyik saját beállításképernyőjén is megjelenik, amellett a beállítás mellett, amelyhez kapcsolódik.

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

A vezérlők, amelyekre egy bővítménynek a leggyakrabban szüksége van. Mindegyik vagy a key alá írja az új értékét az állapotba, vagy megnevez egy action-t az on_action számára, vagy mindkettőt. A teljes építőlista, az elrendezésekkel együtt, a panelek oldalán van.

Hová kerülnek a szakaszok

A horgony egy kártya azonosítója a Clink saját beállítási képernyőinek egyikén. Nevezd meg a section() hívásban, és a bővítmény vezérlői közvetlenül az alá a kártya alá rajzolódnak, fölöttük a bővítmény nevével. A legegyszerűbb megtalálni: az appban nyisd meg a Továbbiak > Fejlesztő menüt, és kapcsold be az Azonosítók megjelenítését. Minden kártya kap egy kis infójelvényt, amely megnevezi az azonosítóját és koppintásra másolja; az oldalak a címsorban mutatják a sajátjukat.

A keys.spacebar saját helyet kap, magán a Szóköz képernyőn. Egy szakasz olyan horgonnyal, amely nincs ebben a listában, továbbra is megjelenik a bővítmény oldalán, így egy elgépelés egy kártyába kerül, nem a bővítménybe.

Átvételek

Amikor egy bővítmény a Clink saját beállításainak egyikét vezérli, az embernek látnia kell ezt, és a kettő nem harcolhat egymással. A claim(control) kimondja, hogy a bővítményé: az app a beállítás kártyáján kiírja a bővítmény nevét, a szóköz szövegmezője pedig zárolva van, amíg a bővítmény tartja. A release(control) visszaadja. Az átvétel abban az on_action-ben legyen, amely bekapcsolja a funkciódat, az elengedés abban, amely kikapcsolja, és ugyanakkor állítsd vissza az értéket None-ra vagy a régi értékére. A listában kikapcsolt bővítmény mindent elenged, amit tartott.

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

Két bővítmény is átveheti ugyanazt a vezérlőt; az app azt nevezi meg, amelyik utoljára vette át. Az átvételeket az app jegyzi fel, ezért az on_action-ből vedd át, amely ott fut. A billentyűzeten belül tett átvétel nem marad meg.

Parancsok és olvasások

A bővítmények minden panelparancsot használhatnak, ezen felül van hat saját parancsuk és két olvasásuk. A parancsok sorba kerülnek, és azután hajtódnak végre, hogy a függvényed visszatért, így a billentyűzeten semmi sem változik egy hívás közepén. Az olvasások a közvetlenül a hívás előtti értékeket adják vissza.

A setting(name) és a set_setting(name, value) egyetlen névlistán osztozik, és a claim(control) is bármelyiket elfogadja. A logikai értékek True vagy False formában olvashatók, a számok számként, a választások az azonosítójukkal. A lista szándékosan hosszú: egy bővítmény szinte mindenre reagálhat, vagy majdnem mindent vezérelhet, amit egy személy az appban beállíthat.

Ahogy egy panel view() függvénye, a settings() is csak vezérlőket írjon le. Az onnan hívott parancsok nem hajtódnak végre, csak bekerülnek a konzolnaplóba.

Példák

Öt kis bővítmény, mindegyik teljes. Illessz be egyet egy új bővítménybe, mentsd el, és fut.

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

Elemek egy kiosztásban

Egy egyéni kiosztás billentyűkből és elemekből áll: egy sáv a legutóbbi emojikkal, egy számsor, egy kurzorpad. Egy bővítmény hozzáadhatja a sajátjait. Az elements(state) megmondja, mit kínál, a draw(id, state) pedig megrajzol egyet, így egy billentyű bármit mutathat, amit a bővítmény ki tud számolni: gépelési sebességet, órát, visszaszámlálást vagy saját töltöttségjelzőt.

Két horogpont épít egyet. Az elements(state) felsorolja, mit kínálsz, elemenként egy bejegyzést, és az app ebből tölti fel a kiosztásszerkesztő palettáját. A draw(id, state) megkapja az egyik azonosítót, és visszaadja, mit kell rajzolni. Egy bővítmény többet is kínálhat; a draw mindegyikre külön kérdez rá.

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

Az arc egy csomópontfa, mint egy beállítási oldal, de a billentyű nem beállítási oldal: csak a rajzoló csomópontok számítanak, minden koppintható kimarad. A billentyű már a kiosztásé, így nincs benne hely egy gombnak.

Billentyűméretre tervezd. A width billentyűszélességben mér: 1 egy betű, 3 nagyjából egy sor harmada, és utólag át lehet méretezni. A szöveg egy sort kap, és összehúzódik, hogy elférjen; a színek alapból a billentyű saját szövegszínét követik, így az elem illik a körülötte lévő billentyűkhöz, hacsak mást nem kérsz. Egy sparkline az utolsó 120 pontját tartja meg, többet, mint amennyit egy billentyű megmutathat.

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)

Az elemek egyéni kiosztásokban élnek, tehát előbb kiosztást kell építeni. Az előre elkészítettek nem tudnak elemet tartani: az első, amit a szerkesztő felajánl, hogy másold sajátoddá.

1. Telepítsd a bővítményt és kapcsold be. Az elemei azonnal megjelennek.
2. Nyisd meg a Kiosztást, hozz létre vagy másolj egy egyéni kiosztást, és lépj az Elrendezésre.
3. Koppints az Elem gombra, válaszd ki a bővítmény elemét a sávból, és állítsd be a szélességét.

A szerkesztő Előnézete minden elemet kirajzol, amit a szkript kínál, nagyjából akkorában, mint a billentyű, amelyre kerül, a szóköz makettje alatt. Mentsd el, tedd ki egyszer, és a billentyűzet ugyanazt rajzolja.

Egy elem csak azt mutatja, amit a bővítmény rajzol: a koppintás nem csinál semmit, mert a billentyű már a kiosztásé. A kiosztás akkor is megtartja az elemet, ha a bővítménye ki van kapcsolva vagy eltávolították, és a billentyű újra megtelik, amint visszakerül.

Gombok és tárcsák a felső sávon

A billentyűk fölötti sávot a Kiosztás > Felső sáv alatt lehet összerakni, és egy bővítmény saját vezérlőket kínálhat bele. A bar_items(state) adja vissza őket: a bar_button(...) koppintásra való, a bar_knob(...) tekerésre. A lista a billentyűzet megnyitásakor és minden koppintás után újra beolvasódik, így egy elem a bővítmény állapotával jöhet és mehet.

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

Mindkettő az on_action(action, value, state) hookon jön vissza, az elem id-je alapján, így a bővítmény sávelemei és a beállításvezérlői ugyanazt a hookot használják. Egy koppintás None-t küld. A tárcsa minden kattanásnál elküldi az értékét, amíg az ujj lent van, és még egyszer elengedéskor, így a bővítmény követheti a húzást, vagy megvárhatja az utolsó értéket.

A setting= paraméterrel ellátott tárcsa olyan beállítást tekeri, ami az appban már megvan, a fenti Parancsok és olvasások listájából, például sound.volume vagy haptics.intensity. Olyan név, amit az app nem ismer, KeyError a konzolon. A tartomány és a kiindulási állás ebből a vezérlőből jön, a billentyűzet saját másolata már húzás közben változik, így a következő leütés már az új szinten szól, az érték pedig elengedéskor mentődik. A nulláról felhúzott hangerő- vagy rezgéstárcsa a húzás idejére vissza is kapcsolja a hangot vagy a rezgést, hogy a kattanások felfelé menet hallatszódjanak és érezhetők legyenek; ezt a kapcsolót a bővítmény menti el, a saját set_setting hívásával az on_action-ben.

A tárcsa Pythonban is megrajzolható. Az art= az, ami a helyén marad, a foglalat vagy a test, a rotor= pedig a forgó lap, a minimumnál -135 fok, a maximumnál +135 fok. Mindkettő ugyanazokat az alakzatokat, festéseket, színátmeneteket és árnyékokat fogadja, mint a billentyűgrafika, egyenként legfeljebb tizenhat alakzatot, az unit="key" pedig a négyzetes számlapra méretezi a koordinátákat, ahol a negatív y-nál lévő mutató felfelé néz. A rajz megkapja a sáv szövegszínét "text" néven és a téma kiemelőszínét "accent" néven. Ha mindkettőt kihagyod, a tárcsa egy gyűrű az ikonnal a közepén; a szerkesztőben a sávba tett tárcsára bármelyik beépített kidolgozás rátehető.

A sávba magától nem kerül semmi. Az elemet kézzel kell odatenni, ugyanúgy, mint a menüt és a javaslatokat.

1. Telepítsd a bővítményt és kapcsold be. A sávelemei rögtön megjelennek.
2. Nyisd meg a Kiosztás > Felső sáv menüpontot.
3. Add hozzá a bővítmény gombját vagy tárcsáját, és húzd a helyére. A tárcsához ezen felül kidolgozást is lehet választani.

Az építők szó nélkül átlépnek egy kulcsszót, amit nem ismernek. A setting=, min=, max=, step=, value=, art= és rotor= csak a bar_knob sajátja, így a bar_button ettől még egyszerű gombként épül fel, és nem szól semmi: a gomb munkája az on_action-be való. Fordítva a title= a gombé, a tárcsa pedig átlépi.

Fényeffektek

Egy bővítmény saját billentyűvilágítást is adhat. Az effects(state) light_effect(...) bejegyzéseket ad vissza, és mindegyik megjelenik az appban a Hatások > Bővítményekből részben, a beépített stílusok és a felhasználók saját effektjei mellett. Az effekt adat, nem rajz: rétegek halmaza, amelyet a billentyűzet maga animál. A szkriptben tehát semmi sem fut képkockánként, és a billentyűfelületek, a betűk, a ragyogás, a leütéskori felvillanás és az alvó mód ugyanúgy működik, mint a beépített stílusoknál.

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

Egy effekt kiválasztása bemásolja azt a felhasználó beállításaiba, így kikapcsolt bővítménnyel is működik tovább. Amíg a bővítmény be van kapcsolva és valamelyik effektje fut, a billentyűzet megnyitáskor, majd nagyjából másodpercenként újra beolvassa az effects(state) eredményét, és átveszi, ami változott. Így követheti az effekt az állapotot, az időt vagy a stats() értékeit.

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

A szerkesztő effects gombja kilistázza, mit kínál a szkript. Ha mozgásban akarod látni, mentsd a bővítményt, válaszd ki az effektet a Hatások > Bővítményekből részben, és figyeld a képernyő tetején lévő billentyűzetet.

Kerekíts mindent, ami ugrál, például a gépelési sebességet. Egy effekt, amely minden másodpercben másképp érkezik vissza, minden másodpercben feleslegesen cserélődik. Ismeretlen minta vagy kulcsszó ValueError a szerkesztő konzoljában, a rétegek nélküli effekt pedig kimarad.

Megjelenések

Hét horogpont kínál választanivalót az appnak: key_styles, themes, popups, animations, backgrounds, trails és layouts. Mindegyik az alábbi hívásokkal épített bejegyzéseket ad vissza, és ezek a Bővítményekből alatt jelennek meg a beépített lehetőségek mellett. Kivételt a témák jelentenek: ezek saját Bővítmények lapot kapnak a témaszerkesztőben. Egy megjelenés számokból és szavakból áll, nem rajzoló kódból, így a szkriptben semmi sem fut képkockánként. A kiválasztás bemásolja a felhasználó beállításaiba, így kikapcsolt bővítménnyel is működik tovább, egy beépített lehetőség későbbi kiválasztása pedig félreteszi.

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

A trails(state) függvény trail csomópontokat adjon vissza. Minden nyomnak van colors színpalettája és rétegei, például trail_line. A color=-1 értékkel a vonal színei fokozatosan váltakoznak a húzás mentén. Kapcsold be a bővítményt, majd válaszd ki a nyomát a nyomválasztó Bővítményekből részében. A rajzelemek állapotban tárolása önmagában nem rajzol nyomot.

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

Egy megjelenés a kiválasztáskor másolódik, így a szkript későbbi módosítása nem változtatja meg a már használt megjelenést; újra ki kell választani. Egy elgépelt kulcsszó, a listáján kívüli szó vagy szám helyett szöveg hiba a szerkesztő konzoljában, a számok pedig az app saját vezérlőinek tartományaiban maradnak.

Rajz a billentyűkön

A key_art(state) billentyűnevekből rajzra mutató dictet ad vissza, a billentyűzet pedig a billentyű felületére festi. A billentyűnevek ugyanazok, mint a haptics-nál, a letters és keys tartalékokkal. A rajz lehet shape(...) lista, egyetlen alakzat, egy art([...]) réteg vagy rétegek listája, és minden réteg a saját órája szerint úszik át a következő rajzába, így egy billentyű két, eltérő sebességgel mozgó dolgot is hordozhat.

A rajz minden esemény után újra beolvasódik, amit a bővítmény hall, és ennyi az egész kör: állapotot módosítasz az on_event(name, info, state)-ben, és abból rajzolsz a key_art(state)-ben. Az events(state) nevezi meg a kívánt eseményeket, és a bővítmény betöltésekor olvasódik be egyszer. Enélkül a bővítmény mindent hall a key, key_down, key_up, predictions és tick kivételével, amelyek leütésenként vagy másodpercenként futtatnak szkriptet, ezért külön kell kérni őket. A shift és a sík változása akkor is újrarajzolja a rajzot, ha senki sem figyel, és a context()-be is eljut.

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

Billentyűnként tizenhat alakzat, az összes rétegét egybeszámolva, és útvonalanként 64 pont; ami ezen túl van, az kimarad. Az alakzat a saját width és height méretű dobozába rajzolódik, és a vastagság nélküli doboz semmit sem fest, ezért egy vízszintes vonalnak kell egy kis saját height, a pontjaival annak közepén (height=0.03, points=[[0, 0.5], [1, 0.5]]), különben szó nélkül nem jelenik meg.

Haptika, érintési területek és javítások

A haptics(state) és a hitboxes(state) billentyűnevekkel kulcsolt dicteket ad vissza: maga a betű, "space", "delete", "return", "shift" vagy "globe", aztán "letters" minden meg nem nevezett betűre és "keys" minden másra. A bővítmény által kihagyott billentyűk megtartják a felhasználó saját beállításait. Mindkét tábla a billentyűzet megnyitásakor, majd nagyjából másodpercenként olvasódik be, így miattuk semmi sem fut billentyűleütésenként.

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

Az on_touch(key, x, y, state) minden koppintás után fut, miután a koppintás feldolgozása megtörtént, azzal, hogy hol ért le az ujj a billentyűn. A helyet a kirajzolt billentyűhöz mérjük, nem az eltolt célhoz, így egy bővítmény minden billentyűt arrafelé tolhat, ahol valójában megnyomják, anélkül hogy a saját eltolását kergetné.

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

A suggestions(word, state) szavakat tesz a sáv elejére, amíg egy szó gépelése folyik. A correct(word, fix, state) szavanként egyszer fut, amikor a szóköz lezárja a szót, a billentyűzet saját javításával vagy None értékkel, kikapcsolt automatikus javításnál is. Adj vissza egy szót, hogy bekerüljön, False értéket, hogy a szó úgy maradjon, ahogy begépelték, vagy None értéket, hogy a billentyűzet döntsön. Az első válaszoló bővítmény nyer, és a közvetlenül utána nyomott törlés visszavonja, mint bármely automatikus javítást.

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

Egyik horogpont sem fut jelszómezőkben. A sáv javítási címkéje a billentyűzet saját javítását mutatja, nem azt, amit a correct visszaadna, és az on_touch-ban módosított tábla a következő ütemben jut el a billentyűzetig.

Tesztelés a szerkesztőben

A szerkesztő Előnézete egy helyettesítő billentyűzet. Élőben rajzolja a settings(state) függvényt, koppintásra bármely horogpontot elindít mintaszóval, billentyűvel vagy mezőtípussal, mutatja a szóközt úgy, ahogy a bővítmény hagyta, és felsorol mindent, amit a bővítmény a billentyűzettől kért. A stats() ott kitalált számokat ad vissza, így gépelés nélkül is megjelenik egy sebesség.

1. Használd az előnézet vezérlőit. Mindegyik lefuttatja az on_action-t és újrarajzol.
2. Koppints a horogpontgombokra abban a sorrendben, ahogy a billentyűzet tenné: on_open, aztán néhányszor on_word vagy on_key, majd on_close.
3. Olvasd a konzolt. A parancsok úgy jelennek meg, ahogy írtad őket, alattuk a print() sorai, a hiba pedig megnevezi a sorát.
4. Töltsd újra az állapot nullázásához. A szkript szerkesztése önmagában nem állítja vissza.

Az előnézetnek nincs dokumentuma, ezért az insert() és a replace() csak naplóz. Kipróbálásukhoz ments, és gépelj bármelyik mezőbe nyitott billentyűzettel.

Korlátok

Ha egy bővítmény fájlként vagy tárolóból érkezik, a Clink mentés előtt ellenőrzi. 64 000 bájtnál és 1600 sornál kisebbnek kell lennie, legalább egy horogpontot kell definiálnia, csak engedélyezett modulokat importálhat, és a következők egyikét sem tartalmazhatja:

Minden horogponthívás 2 000 000 értelmezőlépést kap, ugyanannyit, mint egy panel kirajzolása. Az on_key viszont minden leütésnél lefut, így az ott végzett nehéz munka jóval azelőtt lelassítja a gépelést, hogy elérné ezt a korlátot.

A fájl

A bővítmény egyetlen JSON-dokumentum. Az id frissítések között is állandó, a version szabad szöveg, amely a listában látszik, az icon egy SF Symbol neve, a source pedig a szkript escape-elt sortörésekkel. Oszd meg a szerkesztő ellenőrzőjéből, vagy importálj egyet a Bővítmények lap nyílgombjával.

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

A bővítményeket .clinkplugin fájlként lehet megosztani, ez egy JSON-dokumentum, benne a szkripttel. Tárolón keresztül lehet közzétenni őket, ugyanúgy, mint a paneleket: egy mappa fájllal, egy manifeszttel és egy kiadással. A hivatalos tároló: anti-ltd/clink-plugins.

Ha valami nem történik meg

Legtöbbször ezek egyike.