オーサリング API

オーサリング API は、pme パッケージとその pme.editing モジュールを通じて、 Python から PME のメニューを作成・読み取り・編集・書き出しします。 Python Console、Text Editor、ほかのアドオン、Blender を操作する AI エージェントから呼び出します。 スロットの中(Command、Custom、Poll)に書くコードは別の話題で、スクリプティング で説明します。

ページ一覧

各ページは単独で読めます。基本事項 と 結果とガード は、 すべての編集関数が従う規則を定めます。API 全体が Experimental です。

ページ

扱う内容

基本事項

編集関数を実行できる場所、対象、行わないこと、安定している範囲。

結果とガード

操作ごとの status の値、dry_run、expected / expected_version / expected_digest のガード、診断、例外。

メニュー

メニューの作成・検索・一覧・呼び出し・読み取り・改名・有効化・タグ付け・複製・削除と、 メニューを参照している箇所の検索。

スロット

スロット入力の読み取りと、 スロットの編集・消去・追加・削除・移動・入れ替え・移送。

レイアウトの行とパネル

Pop-up Dialog と Floating Panel の行、spacer、揃え、Layout Panel。

メニューの種類ごとの設定

Pop-up Dialog の Mode や幅など、メニューの種類が持つ設定。

ホットキー

メニューのホットキー割り当ての読み取りと変更。

Property

Property の作成(型、引数、Enum 項目、コールバック、保存先、Property ID)。

Property Stack

Property Stack の作成と、条件行の編集。

Context Router

Context Router の分岐の追加・更新・削除・並べ替え。

書き出しと検証

メニューを PME の JSON 文書として書き出す処理と、文書の検証。

リソース

登録済みのスクリプトとアイコンの場所、スクリプト参照の確認。

コード実行・ユーザープロパティ・identity

コードの実行、ユーザープロパティの読み書き、実行中のアドオンパッケージの特定、 UID の形式の確認。

実行中の API を読み込む

例では import pme を使います。これは 起動オプション で設定する任意の短縮エイリアスです。 エイリアスが無効な場合は、有効化済みアドオンのパッケージを名前で読み込みます。 起動設定の変更も Blender の再読み込みも不要です。

import bpy
import importlib

packages = [
    addon.module for addon in bpy.context.preferences.addons
    if addon.module.rsplit(".", 1)[-1].replace("-", "_") == "pie_menu_editor"
]
if len(packages) != 1:
    raise RuntimeError(f"Select the enabled PME package: {packages}")
pme = importlib.import_module(packages[0] + ".api")
print(pme.ADDON_ID)
  • このコードは、bl_ext.<repository>.pie_menu_editor としてインストールした Blender Extension と、 Extension ID にハイフンを使うもの(bl_ext.<repository>.pie-menu-editor)も見つけます。 モジュール名はリポジトリの ID に従うため、比較ではハイフンとアンダースコアの違いを無視します。

  • 複数のパッケージが該当する場合は、編集の前に目的のインストール先を特定します。 このコードは、その一覧を付けて RuntimeError を送出します。

  • 明示的な読み込みで得た pme 変数は、エイリアスと同じ API です。 この変数を使うコードでは import pme を省きます。

クイックスタート

import pme

# Runtime package identity (Legacy add-on or Blender Extension)
addon_id = pme.ADDON_ID

# Find a menu
pm = pme.find_pm("My Pie Menu")
pm = pme.find_pm(uid="pm_7f3c2k3h")

# Invoke a menu
pme.invoke_pm("My Pie Menu")
pme.invoke_pm(uid="pm_7f3c2k3h")

# List menus
all_menus = pme.list_pms()
pie_menus = pme.list_pms(mode="PMENU", enabled_only=True)
tags = pme.list_tags()

# Execute code
result = pme.execute("bpy.ops.mesh.primitive_cube_add()")
print(result.success, result.error_message)

# Evaluate an expression
value = pme.evaluate("len(C.selected_objects)")

# Validate JSON
result = pme.validate_json(json_string)
for err in result.errors:
    print(err.code, err.message)

関数一覧

pme

関数

用途

ページ

create_pm()

PmCreationSpec から、エディターの既定の内容を持つメニューを作成します。 PmCreationResult を返します。

メニュー

find_pm()

名前または UID で見つけたメニューの PMHandle、または None を返します。

メニュー

list_pms()

PMHandle オブジェクトを返します。 メニューの種類と有効状態による絞り込みは任意です。

メニュー

list_tags()

使用中のタグ名を Tag Registry の順で返します。

メニュー

invoke_pm()

ホットキーと同じように、メニューの呼び出しを要求します。

メニュー

export_menus()

メニューを PME の JSON 文書として書き出します。ファイルへの書き込みは任意です。

書き出しと検証

validate_json()

PME の JSON 文字列を静的に検証します。ValidationResult を返します。

書き出しと検証

validate_uid()

文字列がメニュー UID の形式かどうかを返します。

コード実行・ユーザープロパティ・identity

execute()

PME の標準名前空間でコードを実行します。ExecuteResult を返します。

コード実行・ユーザープロパティ・identity

evaluate()

PME の標準名前空間で式を評価します。失敗時は例外を送出します。

コード実行・ユーザープロパティ・identity

check_syntax()

コードを実行せずに Python の構文を確認します。 SyntaxResult を返します。

コード実行・ユーザープロパティ・identity

props()

PME が登録したユーザープロパティを読み書きします。

コード実行・ユーザープロパティ・identity

pme が公開するその他の名前:

名前

用途

ページ

PmCreationSpec

create_pm() に渡す作成要求(mode_id、name、 slots、data)。

メニュー

PmCreationResult

create_pm() の結果(accepted、pm_uid、 diagnostics)。

メニュー

PmiSlotSpec

PmCreationSpec.slots のスロット項目(mode、name、text、 icon)。create_pm() は、明示したスロットを slots_unsupported_by_create_pm で拒否します。

メニュー

ADDON_ID

実行中のアドオンパッケージのモジュール ID。pie_menu_editor や bl_ext.<repository>.<package> など。

コード実行・ユーザープロパティ・identity

preferences

PME のアドオン Preferences オブジェクト。 アドオンのエントリーがあり、PME の Preferences クラスがない間は None です。 PME が有効でない場合、読み取ると KeyError を送出します。

コード実行・ユーザープロパティ・identity

context

PME1 の実行コンテキスト。後方互換のために残されています (後方互換)。

コード実行・ユーザープロパティ・identity

サブモジュール:

モジュール

用途

ページ

pme.editing

保存済みのメニュー定義を UID で読み取り・編集します。 関数の一覧は下にあります。

このページ

pme.validation

PME JSON の静的検証(validate、validate_json、 validate_file、ERROR_CODES)。

書き出しと検証

pme.resources

登録済みのスクリプトとアイコンのフォルダー・ファイルの読み取り専用の探索と、 スクリプト参照の確認。

リソース

pme.types

結果とハンドルの型。ExecuteResult と SyntaxResult (コード実行・ユーザープロパティ・identity)、PMHandle と PmCreationResult (メニュー)、ValidationIssue と ValidationResult (書き出しと検証)。

型ごと

pme.constants

メニューの種類とスロットのモードの識別子(MENU_MODES、ITEM_MODES、 UNTAGGED)と、get_mode_label()、get_mode_icon()、 is_valid_mode()。MENU_MODES は FPANEL を含みません。

(なし)

pme.dev

ツール作成者向けの名前空間のイントロスペクション(is_public()、 get_stability()、validate_namespace()、namespace_report()、 get_logger())。

(なし)

pme.editing

関数

用途

ページ

update_pm()

メニューの名前、説明、説明の形式、Poll 本文を変更します。

メニュー

set_enabled()

一括操作の処理を通じて、メニューを有効または無効にします。

メニュー

update_tags()

複数のメニューにまたがるタグ名の追加と解除を、1 回の一括処理で行います。

メニュー

duplicate_pm()

メニューを 1 つ、複製元の直後へ複製します。

メニュー

delete_pms()

メニューを削除します。または、削除とその参照を事前確認します。

メニュー

find_references()

メニューを参照している保存済みの箇所を列挙します。読み取り専用です。

メニュー

read_pm()

1 つのメニューの保存定義を返します。スロット UID による絞り込みは任意です。

メニュー

read_slot_inputs()

update_slots() が受け付ける入力名で、スロットを返します。 読み取り専用です。

スロット

slot_fields()

Slot Editor の入力フィールドの説明(名前、型、Enum の値)を返します。

スロット

resolve_auto_icons()

各 Auto Icon スロットが、この Blender セッションでアイコンを見つけられるかを報告します。 読み取り専用です。

スロット

update_slots()

Slot Editor の通常の保存を通じて、スロット UID で指定したスロットの内容を変更します。

スロット

clear_slots()

スロットの UID と位置を保ったまま、内容を消去します。

スロット

add_slot()

既定の項目を 1 件、スロットの隣、末尾、 または Panel ヘッダーに追加します。

スロット

remove_slot()

項目を 1 件削除します。

スロット

move_slot()

項目を 1 件、別の項目の前後、行端、新しい行、 または Panel ヘッダーへ移動します。

スロット

swap_slots()

固定枠の項目 2 件、または Pop-up の項目 2 件を入れ替えます。

スロット

transfer_slot()

項目 1 件の内容を別のメニューへ移します。

スロット

add_row()

既定のボタンを持つレイアウト行を追加します。

レイアウトの行とパネル

add_panel()

既定のアンカーを持つ Layout Panel 行を追加します。

レイアウトの行とパネル

remove_row()

レイアウト行全体を、その内容とともに削除します。

レイアウトの行とパネル

move_row()

レイアウト行全体を別の行の前後へ移動します。

レイアウトの行とパネル

split_row()

レイアウト行を、その中の項目の直前で分割します。

レイアウトの行とパネル

join_rows()

隣接する 2 つのレイアウト行を結合します。

レイアウトの行とパネル

update_row()

1 行、揃えでつながった行群、またはすべての行について、 保存された行設定を変更します。

レイアウトの行とパネル

update_spacer()

spacer の設定を 1 つ変更します。必要なときは隣接する spacer を作成します。

レイアウトの行とパネル

align_slot()

項目を行の LEFT、CENTER、RIGHT の区分に配置します。または配置を解除します。

レイアウトの行とパネル

setting_fields()

メニューの種類が受け付ける設定の説明を返します。

メニューの種類ごとの設定

update_settings()

メニューの種類の設定を変更します。

メニューの種類ごとの設定

update_hotkey()

メニューのホットキー割り当てを変更します。または変更を事前確認します。

ホットキー

update_property()

Property の型、引数、Enum 項目、コールバック、保存先、 Property ID を変更します。

Property

update_property_stack()

Property Stack のロジック全体を置き換えます。

Property Stack

add_property_stack_row()

空の条件行を末尾に追加します。

Property Stack

update_property_stack_row()

条件行 1 件と、対応する SET 項目を変更します。

Property Stack

remove_property_stack_row()

条件行 1 件と、対応する SET 項目を削除します。

Property Stack

update_property_stack_hud()

Property Stack の While True HUD を変更します。

Property Stack

update_router()

Context Router の分岐と Otherwise を変更・追加・維持します。

Context Router

remove_router_branch()

Otherwise を保ったまま、分岐を 1 件削除します。

Context Router

move_router_branch()

分岐を 1 件、別の分岐の前後へ移動します。

Context Router

reorder_router_branches()

1 回の保存で、すべての分岐を指定した順序に並べます。

Context Router

PME1 からの変更点

観点

PME1

PME2

インポート

from pie_menu_editor import pme

import pme

実行中のアドオン ID

"pie_menu_editor" の固定値

pme.ADDON_ID

設計

内部モジュールの露出

公開 API ファサード

メニュー呼び出し

pme.context.open_menu(name)

pme.invoke_pm(name) / pme.invoke_pm(uid=...)

コード実行

pme.context.exe(code)

ExecuteResult を返す pme.execute(code)

メニュー検索

なし

pme.find_pm(), pme.list_pms()

JSON 検証

なし

pme.validate_json()

型・定数

なし

pme.types, pme.constants

後方互換

PME1 の pme.context と、Command のグローバル props() は引き続き利用できます。 PME の Command スロット内にある既存の props() スクリプトは、そのまま動作します。

# These still work in PME2
pme.context.open_menu("My Menu")
pme.context.event.mouse_x
pme.context.add_global("my_var", value)
props("MyCounter", 10)

新しいコードでは pme.execute() と pme.invoke_pm() を使います。