Pythonスクリプティング APIリファレンス

このドキュメントは、Pythonスクリプティングで利用可能なAPIの概要を説明します。スクリプトは、グローバルな host オブジェクトを通じてアプリケーションと対話できます。

APIはまだ発展段階にあり、現状は十分足りている状態ではありません。リクエストなどあればぜひお伝えください。

English

host オブジェクト

host オブジェクトは、すべてのAPI機能へのメインエントリーポイントです。

host.install(package_name: str) -> bool

指定されたPythonパッケージをインストールします。パッケージがすでにインポート可能な場合、インストールはスキップされます。

  • 引数:
    • package_name (str): インストールするパッケージの名前 (例: "requests")。
  • 戻り値:
    • bool: インストールが成功したか、すでに存在する場合は True、それ以外は False。
  • 例:
    if host.install("requests"):
    import requests

host.log(message: str, level: int = LogLevel.INFO)

ホストアプリケーションにログメッセージを送信します。

  • 引数:
    • message (str): ログに記録するメッセージ。
    • level (int, optional): ログレベル。デフォルトは LogLevel.INFO。

host.LogLevel

ログレベルの列挙型。

  • 定数:
    • DEBUG (0)
    • INFO (1)
    • WARNING (2)
    • ERROR (3)

host.state モジュール

アプリケーションの現在の状態へのアクセスを提供します。

state.get_current_folder_path() -> Optional[str]

現在アクティブなフォルダのパスを取得します。

  • 戻り値:
    • Optional[str]: フォルダのパス。取得できない場合は None。

state.get_cursor_path() -> Optional[str]

現在カーソル下にあるアイテムのパスを取得します。

  • 戻り値:
    • Optional[str]: アイテムのパス。取得できない場合は None。

state.get_selected_paths() -> Optional[Iterable[str]]

現在選択されているすべてのアイテムのパスを取得します。

  • 戻り値:
    • Optional[Iterable[str]]: アイテムのパスのイテラブル。取得できない場合は None。

host.scheduler モジュール

タスクの定期的な実行を管理します。

scheduler.start(interval_sec: int, function_name: str) -> Optional[str]

定期的に実行する関数を登録します。

  • 引数:
    • interval_sec (int): 実行間隔（秒）。
    • function_name (str): 実行する関数の名前。
  • 戻り値:
    • Optional[str]: 成功した場合は一意のスケジュールID、それ以外は None。

scheduler.stop(schedule_id: str) -> None

定期的なタスクを停止します。

  • 引数:
    • schedule_id (str): scheduler.start() によって返されたスケジュールID。

host.ui モジュール

ダイアログのようなユーザーインターフェース要素を作成するための関数を提供します。

標準ダイアログ

ui.input_text_dialog(title: str, message: str, initial_text: str) -> InputTextDialogResponse

テキスト入力フィールドを持つダイアログを表示します。

  • 引数:
    • title (str): ダイアログのタイトル。
    • message (str): 表示するメッセージ。
    • initial_text (str): 入力フィールドの初期テキスト。
  • 戻り値:
    • InputTextDialogResponse: result (int) と text (str) 属性を持つオブジェクト。

ui.ok_cancel_dialog(title: str, message: str) -> int

「OK」と「キャンセル」ボタンを持つダイアログを表示します。

  • 戻り値:
    • int: DialogResult 定数 (OK または CANCEL)。

ui.ok_dialog(title: str, message: str) -> int

「OK」ボタンのみを持つダイアログを表示します。

  • 戻り値:
    • int: DialogResult.OK。

ui.skip_retry_cancel_dialog(title: str, message: str) -> int

「スキップ」、「リトライ」、「キャンセル」ボタンを持つダイアログを表示します。

  • 戻り値:
    • int: DialogResult 定数 (SKIP, RETRY, または CANCEL)。

ui.yes_no_dialog(title: str, message: str) -> int

「はい」と「いいえ」ボタンを持つダイアログを表示します。

  • 戻り値:
    • int: DialogResult 定数 (YES または NO)。

UI定数

ui.DialogResult

ダイアログのボタン結果の列挙型。

  • 定数:
    • CANCEL (0)
    • OK (1)
    • YES (2)
    • NO (3)
    • SKIP (4)
    • RETRY (5)

ui.ChoiceStyle

選択コントロールの表示スタイルの定数。

  • 定数:
    • DROPDOWN (0)
    • RADIO_BUTTON (1)

ui.LayoutDirection

グループ内のコントロールのレイアウト方向の定数。

  • 定数:
    • VERTICAL (0)
    • HORIZONTAL (1)

カスタムダイアログ (DialogBuilder)

コントロールを順次追加して、複雑なダイアログを作成します。

  • ビルド開始: host.ui.dialog(title: str, root_direction: int = LayoutDirection.VERTICAL) -> DialogBuilder
  • ダイアログ表示: dialog_builder.show_modal() -> int
  • ダイアログを閉じる: dialog_builder.close(result: int)

例:

dlg = host.ui.dialog("マイダイアログ")
name_input = dlg.text("名前:", "デフォルト")
dlg.button("OK").clicked += lambda s, e: dlg.close(host.ui.DialogResult.OK)
result = dlg.show_modal()
if result == host.ui.DialogResult.OK:
    host.log(f"入力された名前: {name_input.text}")

DialogBuilder メソッド

DialogBuilder とコンテナ要素 (GroupProxy, GroupBoxProxy, TabPageProxy) は、コントロールを追加するために以下のメソッドを共有します。

  • bool(label: str, initial_value: bool) -> CheckboxProxy
  • button(text: str) -> ButtonProxy
  • choice(label: str, items: Any, initial_index: int = 0, style: int = ChoiceStyle.DROPDOWN) -> ChoiceProxy
  • float(label: str, initial_value: float, min_value: float, max_value: float) -> FloatSliderProxy
  • group(direction: int) -> GroupProxy
  • group_box(title: str, direction: int) -> GroupBoxProxy
  • int(label: str, initial_value: int, min_value: int, max_value: int) -> IntSliderProxy
  • label(text: str) -> LabelProxy
  • separator() -> SeparatorProxy
  • tab() -> TabProxy
  • text(label: str, initial_text: str = '') -> TextBoxProxy

コンテナコントロール

  • group(direction: int) -> GroupProxy: コントロールをグループ化するためのコンテナを作成します。
  • group_box(title: str, direction: int) -> GroupBoxProxy: タイトル付きの枠線を持つコンテナを作成します。
  • tab() -> TabProxy: タブコントロールを作成します。
    • tab_proxy.page(title: str) -> TabPageProxy: タブコントロールに新しいページを追加します。

コントロールプロキシ

ダイアログにコントロールを追加すると、プロキシオブジェクトが返されます。このオブジェクトを使用して、コントロールのプロパティやイベントにアクセスできます。

  • 共通プロパティ:

    • enabled (bool): コントロールが有効かどうかを取得または設定します。

  • TextBoxProxy:

    • text (str): テキストコンテンツを取得または設定します。

  • CheckboxProxy:

    • value (bool): チェック状態を取得または設定します。

  • IntSliderProxy:

    • value (int): 現在の整数値を取得または設定します。

  • FloatSliderProxy:

    • value (float): 現在の浮動小数点数値を取得または設定します。

  • ChoiceProxy:

    • selected_index (int): 選択されているアイテムのインデックスを取得または設定します。
    • selected_item (str): 選択されているアイテムのテキストを取得します。

  • ButtonProxy:

    • clicked: 購読できるイベントです。ハンドラは (sender, event_args) を受け取ります。

  • その他のプロキシ: LabelProxy, SeparatorProxy, GroupProxy, GroupBoxProxy, TabProxy, TabPageProxy。これらは主にレイアウト用で、enabled プロパティを持ちます。