keyboard — Pythonista キーボードのためのユーティリティー

はじめに

　keyboard モジュールには Pythonista に付属のキーボード（PyKeys）を拡張するための様々な関数が用意されています。

　Pythonista 付属のキーボードは、 iOS 上のテキストの編集機能をもった非常に多くのアプリで使用されている画面上のキーボードです。スクリプトを書いてこのキーボードを拡張し、例えば、短いテキストを挿入したり、QWERTYキーボード上に全く独自のUI(ui.View)を使えるようにすることができるようになります。この独自の UI については、追加ボタンの表示をさせたり、ドキュメントや選択に応じて反応を変えたりすることもできます。

　もし、キーボード用のスクリプトにカスタマイズした view や UI を用意する場合には、カーソルを動かすとか付属のQWERTYレイアウトのキーを使うなどの、何らかのテキスト入力に関連したイベントが発生した際に通知を受けることできます。この目的のために、独自の ui.View サブクラスに以下のコールバックメソッドを設けることができます：

import keyboard
import ui
from datetime import datetime
from random import uniform

class MyView (ui.View):
        def __init__(self, *args, **kwargs):
                self.label = ui.Label(frame=self.bounds, flex='wh')
                self.add_subview(self.label)
                super().__init__(*args, **kwargs)

        def kb_should_insert(self, text):
                self.label.text = f'Insert: {text}'
                # You can modify the inserted text here:
                return text

        def kb_text_changed(self):
                self.background_color = (uniform(0.5, 1.0), uniform(0.5, 1.0), uniform(0.5, 1.0))

        def kb_should_delete(self):
                return True


v = MyView()
keyboard.set_view(v)

　独自のキーボードのユーザーインターフェイスについて、Pythonista の「keyboard examples」フォルダに多くの例が用意されています。

　Pythonista のショートカットのページに、キーボードを表示させたり使用したりする方法についてより詳細な情報があるので参照ください。

Functions

keyboard.backspace(times=1)

　現在のドキュメントを後退しながら削除します。（バックスペースキーと同様に動作します）引数の times で一度にどれだけの文字を削除するかを設定します。

keyboard.get_appearance()

　キーボードの現在の見た目（ダークモードかライトモード）を返します。

keyboard.get_document_id()

　キーボードでタイピングしている、現在のドキュメントのUUID(Universally Unique IDentifier)を返します。このIDは任意かつランダムであり、ドキュメントに関する情報を含んでいませんが、ユーザーが別のドキュメントのタイピングをしていることを判定するのに使用できます。

keyboard.get_input_context()

　カーソルのすぐ前と後のテキストの文字列の２つのタプルを返します。

keyboard.get_selected_text()

　現在選択しているテキスト、または選択していない場合には空の文字列を返します。

　（警告　2行以上、または1,000文字以上を選択した場合、この関数の戻り値は途中で途切れてしまいます。この現象は残念なことに、システム上の制約であり、技術的に解決することができません。さらには、途中で途切れたことを検知する方法もありません。

　一般的には、この関数の戻り値が複数行ある場合には、選択したテキストの置き換えに使うべきではありません。

keyboard.get_text_replacements()

　キーボードのグローバル設定（「設定＞一般＞キーボード＞ユーザー辞書」で設定した内容）のユーザー辞書のリストを返します。ユーザー辞書は「文字列」と「読み仮名」の2要素のタプルになっています。

　この関数は Pythonista キーボードが表示されている時のみ実行可能です。その他の状況では、None を返します。

keyboard.has_full_access()

　キーボードへの「フルアクセス」が許されている時には True を返します。その他の場合には False を返します。

　「フルアクセス」は、例えばネットワークへのアクセス、クリップボード、メインアプリにファイルを書き込む時などに必要になります。

keyboard.has_text()

　キーボードで編集しているドキュメント（テキストフィールド）に何らかの文字がある場合には True を返します。空の場合には False を返します。

keyboard.insert_text(text)

　キーボードで編集している現在のドキュメント（またはテキストフィールド）にテキストを挿入します。

keyboard.is_keyboard()

　pythonista キーボードでスクリプトが実行されている場合には True を返します。その他の場合には False を返します。

　この関数は、キーボードで実行した場合とメインアプリで実行した場合とで異なる挙動をする必要があるスクリプトに使用できます。

keyboard.move_cursor(offset)

　引数 offset で（正または負の整数で）指定した位置にカーソルを移動させます。

keyboard.play_input_click()

　入力の際のクリック音を出します。この機能はユーザーが「設定＞サウンド＞キーボードのクリック」でクリック音が許可されていて、デバイスが消音になっていない場合に実行されます。

keyboard.set_view(view=None, mode='current')

　キーボードのユーザーインターフェイスとして ui.View を設定します。modeが「minimized」の場合にはQWERTYレイアウトの上方、「expanded」の場合にはキーボードエリアの大部分を埋めるような形で機能します。「current」の場合にはアクティブモードが継続します。（緑の「ショートカット」キーをタップすれば手動で切り替えられます）

　view に None を設定して呼び出すことで、現在のビューを閉じることができます。

　テキスト入力イベントの発生を把握するための、独自のUIを設定できるコールバックの情報については「はじめに」をご覧ください。