パネル

ループ

パネルは view(state) を定義し、必要に応じて initial()、on_open(state)、on_action(action, state) も定義します。Clink は初期状態のために initial() を一度、パネルが現れるたびに on_open を、そして view(state) を呼んで画面を組み立てます。コントロールは、書いている場所に文字を挿入するか、新しい状態を設定するか、on_action に渡すアクション名を持つかのいずれかで、そのたびに画面が組み立て直されます。

def initial():
    return {"count": 0, "step": 1}

def view(state):
    return vstack([
        text(f"{state['count']}", size=34, weight="bold", align="center"),
        segmented(["1", "5", "10"], value=str(state["step"]), action="step"),
        hstack([
            button("−", "bump", value=-1),
            button("+", "bump", value=1, style="primary"),
        ]),
        button("Type it", "type", icon="keyboard"),
    ])

def on_action(action, value, state):
    if action == "bump":
        state["count"] = state["count"] + value * state["step"]
    elif action == "step":
        state["step"] = int(value)
    elif action == "type":
        insert(str(state["count"]))
        close()
    return state

電卓、スニペット集、ピッカー。あなたのパネルはキーボードのパネルボタンの奥に表示されます。

ビルダー

view(state) は、これら 19 個の関数が作るノードを返します。自由に入れ子にできます。スタックとグリッドは子要素のリストを受け取ります。

ただの文字列も、ノードが使える場所ならそのまま使えます。既定のサイズのテキストとして描かれます。

タップに応える

何かを計算する必要があるコントロールは、決め打ちの set ではなく action を名前で指定します。すると Clink が on_action(action, state) を呼びます。コントロールが運ぶ値も使いたいときは on_action(action, value, state) にします。state はふつうの辞書なので、その場で書き換えて何も返さなくても、新しい辞書を返してもかまいません。

def initial():
    return {"items": [], "draft": ""}

def view(state):
    return vstack([
        field("draft", placeholder="Add one…", submit="add"),
        scroll([row(item, action="use", value=item) for item in state["items"]]),
    ])

def on_action(action, value, state):
    if action == "add" and value:
        state["items"].append(value)
        state["draft"] = ""
    elif action == "use":
        insert(value)
        close()
    return state

on_open(state) はパネルが現れるたびに走ります。いま書いている文章から初期値を取るのはここです。

キーボードに頼む

on_action と on_open からは、戻り値では表せないことをキーボードに頼めます。呼び出しはいったん記録され、関数が終わってから実行されるので、パネルが自分のビューを組み立てている最中に入力欄を書き換えることはありません。

def on_action(action, state):
    if action == "quote":
        word = context()["word"]
        replace(len(word), "“" + word + "”")
        haptic("light")
    return state

context() はカーソルの周りを読みます。before、selected、after、word、clipboard、locale、language、full_access、time です。呼び出しが始まった時点のスナップショットなので、描画の途中で書き換わることはありません。

状態

state はふつうの辞書で、スクリプトが作れるものなら何でも入ります。数値、文字列、真偽値、None、そしてそれらのリストや辞書です。呼び出しのたびに返ってくるので、あるタップで追加したリストは次のタップでもそのままです。

def initial():
    return {"name": ""}

def view(state):
    return vstack([
        field("name", placeholder="Who?"),
        button("Greet", insert="Hi " + state["name"] + "!", style="primary"),
    ])

「状態を保持」を入れると、パネルの内容が開き直しても、キーボードを起動し直しても残ります。電卓なら切ったまま、リストなら入れておくとよいでしょう。

state はキーボードが画面に出ているあいだ生きています。パネルが記憶する設定なら、それより長く残ります。パネルは context() でカーソル周辺の文字を読めますが、あなたについてそれ以外は読めません。

制限

キーボードに与えられるメモリはアプリのごく一部です。だからパネルは信用ではなく上限で守られています。描画1回につきインタプリタのステップは 2,000,000 回までで、暴走したループは画面上のエラーで終わります。キーボードが応答しなくなることはありません。

ファイルやリポジトリから届いたパネルは、保存する前に検査されます。48,000 バイトと 1,200 行を超えないこと、def view( を定義していること、import はすべてサンドボックス内の名前空間のいずれかを指していること。そして次の断片はその場で拒否されます。

アプリの中で自分が書くパネルは、この一覧の対象外です。その場合、暴走したループを止めるのはステップ予算だけなので、抜け道を用意しておいてください。

配置

各パネルに専用ボタンをピッカー内に用意し、1つのパネルボタンの奥にまとめないようにします。個々のパネルはエディタでこの設定を上書きできます。

「デフォルト」はその設定に従い、「単独」は常に自分のボタンを持ち、「グループ化」は常に中にまとまります。

書いてみる

1. Clink でカスタムパネルを開き、「新規パネル」をタップします。
2. スクリプトを書きます。隣では本物のパネルのプレビューが動き、エラーは入力しながら表示されます。
3. 保存してパネルをオンにし、キーボードのパネルボタンを開きます。

「共有パネル」は .clinkpanel ファイル、つまりJSONを書き出します。Clink で開き直すと新しいIDで保存されるので、同じパネルを2回読み込んでも最初のものが上書きされることはありません。