メニュー¶
メニュー全体の操作です。メニューの作成・検索・一覧・呼び出し(pme)と、
メニューの保存定義の読み取り、名前・説明・Poll・有効状態・タグの変更、
メニューの複製と削除、メニューを参照している箇所の検索(pme.editing)を扱います。
スロット、レイアウトの行、種類ごとの設定、ホットキー、
Property・Property Stack・Context Router の定義は、それぞれ別のページで扱います。
メニューの書き出しは 書き出しと検証 の export_menus() です。
関数 |
用途 |
|---|---|
種類の既定の内容でメニューを作成します。 |
|
UID または名前で 1 つのメニューを探し、ハンドルを返します。 |
|
すべてのメニューのハンドルを返します(絞り込みは任意)。 |
|
メニューが使っているタグ名を返します。 |
|
メニューを開く要求を出します。 |
|
メニューの保存定義を返します。 |
|
名前・説明・説明の形式・Poll を変更します。 |
|
メニューを有効または無効にします。 |
|
メニューのタグ名を追加・解除します。 |
|
メニューを複製します。 |
|
メニューを削除します。 |
|
メニューを参照している保存箇所を一覧にします。 |
呼び出しの規則¶
メニューは UID で指定します。名前は変わることがあります。 名前で探すときは
find_pm()を使い、得た UID を以降の呼び出しに使います。このページの
pme.editingの関数はすべて、Blender のメインスレッド以外から呼ばれたとき、 PME の読み込みが完了する前、PME の Preferences を利用できないときにRuntimeErrorを送出します。このページの関数は、Preferences をディスクへ保存せず、Blender の Undo ステップも追加しません。 メニューを開くのは
invoke_pm()だけです。メニューのアクションを実行する関数はありません。
メニューの種類の識別子¶
識別子は、PmCreationSpec の mode_id、PMHandle の mode、
read_pm()["mode"] に使われる値です。
メニューの UID は、種類の接頭辞と _ で始まります(例: pm_a2b3c4d5)。
「ホットキー」列は、その種類がホットキーを持つかを示します。
editable_slots は read_pm() が返す値です。
False の種類は、スロットの操作ではなく、その種類専用の操作で編集します。
|
名前 |
UID 接頭辞 |
ホットキー |
|
|---|---|---|---|---|
|
Pie Menu |
|
あり |
|
|
Vector Menu |
|
あり |
|
|
Regular Menu |
|
あり |
|
|
Pop-up Dialog |
|
あり |
|
|
Floating Panel |
|
あり |
|
|
Stack Key |
|
あり |
|
|
Panel Group |
|
なし |
|
|
Hidden Panel Group |
|
なし |
|
|
Sticky Key |
|
あり |
|
|
Macro Operator |
|
あり |
|
|
Modal Operator |
|
あり |
|
|
Property |
|
なし |
|
|
Property Stack |
|
なし |
|
|
Context Router |
|
あり |
|
共通の結果構造¶
保存済みメニューのスナップショット¶
duplicate_pm() と delete_pms() は、
メニューの保存状態を切り離した辞書で報告します。
それぞれの expected の digest は、この値から計算します。
キー |
型 |
値 |
|---|---|---|
|
dict |
メニューの保存プロパティ。その |
|
list[dict] |
スロットごとに 1 要素: |
|
bool |
Property Stack HUD の設定がメニューに保存されているか。 |
|
dict |
Property Stack HUD の設定。 |
選択のスナップショット¶
duplicate_pm()、delete_pms()、
update_tags() は、呼び出し前後のエディターのメニュー選択を報告します。
読み取れなかったスナップショットは None です。
キー |
型 |
値 |
|---|---|---|
|
str or None |
アクティブなメニューの UID。メニューがないときは |
|
int |
アクティブなメニューのコレクション内のインデックス。 |
|
list[str] |
選択されているメニューの UID。 |
|
bool |
Select Mode がオンか。 |
|
dict or None |
選択されている Tree の行: |
|
bool or None |
一覧のリージョンが最後に描画されたとき、アクティブなメニューがその中にあったか。
不明なときは |
|
str |
|
メニューを探す・呼び出す¶
- pme.find_pm(name=None, *, uid=None)¶
UID または完全一致の名前で 1 つのメニューを探し、ハンドルを返します。
- パラメータ:
- 戻り値:
ハンドル。一致するメニューがないときは
None。- 戻り値の型:
PMHandleor None
例
handle = pme.find_pm("Mesh Tools") if handle: pm_uid = handle.uid
補足
見つからない UID では
Noneを返します。名前での検索は行いません。UID での検索は、その UID を持つ最初のメニューを返します。 複数のメニューが共有する UID は検出しません。
PME の Preferences を利用できないとき、 または保留中の Tag の変更を適用できないときは
Noneを返します。ハンドルは呼び出し時点のコピーです。その後の変更には追従しません。
- pme.list_pms(mode=None, *, enabled_only=False)¶
すべてのメニューのハンドルをコレクション順に返します。
- パラメータ:
mode (str or None) -- メニューの種類の識別子(メニューの種類の識別子)。 その種類のメニューだけを返します。
Noneではすべての種類を返します。 未知の識別子では[]を返します。enabled_only (bool) -- 有効なメニューだけを返します。
- 戻り値:
メニューごとに 1 つのハンドル。PME の Preferences を利用できないとき、 または保留中の Tag の変更を適用できないときは
[]。- 戻り値の型:
list[
PMHandle]
例
for handle in pme.list_pms(mode="PMENU", enabled_only=True): print(handle.uid, handle.name, handle.tag)
- pme.list_tags()¶
メニューが使っているタグ名を返します。
- 戻り値:
使われているタグ名を 1 回ずつ。Tag Registry が有効なときはその順、 それ以外は大文字と小文字を区別して並べ替えた順。
Untaggedは含みません。 PME の Preferences を利用できないとき、 または保留中の Tag の変更を適用できないときは[]。- 戻り値の型:
例
>>> pme.list_tags() ['Modeling', 'Sculpt', 'UV']
- pme.invoke_pm(pm_or_name=None, *, name=None, uid=None)¶
ホットキーと同じように、メニューを開く要求を出します。
Trueは、要求がエラーなく送られたことを表します。 メニューが表示されたことや、アクションが実行されたことは確認しません。- パラメータ:
- 戻り値:
要求を送ったか。
- 戻り値の型:
例
opened = pme.invoke_pm(uid=pm_uid)
補足
次の場合は、例外を送出せずに
Falseを返します。一致するメニューがない。
メニューが無効。
メニューの Poll または現在のコンテキストが許可しない。
Blender のオペレーターの呼び出しが例外を送出した。
PME が起動スクリプト(
scripts/autorun/、scripts/register/)を実行中。
- class pme.types.PMHandle(name, mode=None, enabled=True, uid='', tag='')¶
1 つのメニューの識別情報のコピーです。
find_pm()とlist_pms()が返します。項目を変更しても PME では何も変わりません。 クラスはpme.types.PMHandleです。pme.PMHandleとしては使えません。- mode: str or None¶
メニューの種類の識別子(メニューの種類の識別子)。
メニューを作成する¶
- pme.create_pm(spec, *, request_refresh=None)¶
種類の既定の内容でメニューを作成します。
メニューは、エディターの New と同じように作成されます。スロットと設定は作成後に編集します。 スロットは
update_slots()、種類ごとの設定はupdate_settings()、Property はupdate_property()で編集します。- パラメータ:
spec (PmCreationSpec) -- 作成するメニュー。
slotsは空、dataはNoneでなければなりません。request_refresh (callable or None) -- メニューの作成と Tree の更新の後、エディターを再描画するために、 引数
"global"で 1 回呼ばれます。Noneでは再描画を要求しません。
- 戻り値:
新しいメニューの UID、または拒否のコード。
- 戻り値の型:
診断
結果の
diagnosticsは、辞書ではなくコードを持ちます。検査は表の順に行います。 spec の検査は、失敗したコードをすべてまとめて報告します。 後の検査は、前の検査に通ったときだけ行います。refresh_failed以外のコードは、メニューが作成されなかったことを表します。コード
原因
spec_shape_invalidspecがPmCreationSpecでない、または項目の型が誤っている (mode_idかnameが str でない、dataが str でもNoneでもない、slotsが tuple でも list でもない、スロットの項目が str でない)。このコードだけが報告されます。unknown_modemode_idが メニューの種類の識別子 にない。logic_envelope_mode_unsupportedslotsまたはdataを指定したCONDITIONかROUTER。slot_count_exceeds_fixedスロットが種類の固定数を超えている(
PMENUとVMENUは 10、STICKYは 2、CONDITIONとROUTERは 0)。slot_count_below_fixedスロットが 1 つの
STICKY。PMENUとVMENUは固定数より少ないスロットを受け付けます。data_marker_mismatchdataの?より前の部分が、種類のデータマーカーでない。data_query_malformeddataの?より後の組がkey=valueでない。unknown_slot_modeスロットの
modeがEMPTY、COMMAND、PROP、MENU、HOTKEY、CUSTOM、INVOKE、FINISH、CANCEL、UPDATEのどれでもない。slots_unsupported_by_create_pmslotsが空でない。data_unsupported_by_create_pmdataがNoneでない。boot_worker_thread_unsupportedPME が起動スクリプトを実行している間に、Blender のメインスレッド以外から呼ばれた。
boot_refresh_callback_unsupportedPME が起動スクリプトを実行している間に
request_refreshが指定された。route_pm_identity_*保存されたメニューが UID の検査に通らない。例: 複数のメニューが UID を共有するときの
route_pm_identity_uid_duplicate。route_target_rejected作成先を準備できなかった。
route_dry_run_rejected準備から書き込みまでの間に、メニューのコレクションが変わったか、 新しい UID が衝突した。
route_apply_failedメニューの作成で例外が発生した。追加した要素は取り除かれています。 元の例外は Blender のコンソールに出力されます。
route_receipt_invalid作成処理が有効な結果を返さなかった。
refresh_failed拒否ではありません。
acceptedはTrueです。メニューは作成されましたが、 Tree の更新またはrequest_refreshが例外を送出しました。例外は Blender のコンソールに出力されます。例
created = pme.create_pm(pme.PmCreationSpec(mode_id="VMENU", name="Mesh Tools")) print(created.accepted, created.pm_uid, created.diagnostics) if created.accepted: menu = pme.editing.read_pm(created.pm_uid)
補足
accepted=Trueは、メニューが Preferences に存在することを表します。 Preferences のディスク保存、メニューの呼び出し、 実行時にすぐ使えることは意味しません。refresh_failedの後は、メニューを作り直さず、返された UID のメニューを読み取ります。配置、Auto Tag、キーマップの継承は、現在の一覧の状態でのエディターの New に従います。 新しいメニューがアクティブなメニューになります。
空の
nameでは種類の既定の名前を使います。使用中の名前には.001のような接尾辞が付きます。route_*の検査より前に拒否された要求は、Preferences を読み取りも変更もしません。メインスレッドの起動スクリプトからの呼び出しでは、保存されたメニューだけを作成します。 ホットキーやエディターの登録と画面更新は、この呼び出しの中では行いません。
- class pme.PmCreationSpec(mode_id, name='', slots=(), data=None)¶
create_pm()に渡すメニューを記述する、frozen な dataclass です。- mode_id: str¶
メニューの種類の識別子(メニューの種類の識別子)。
- slots: tuple[PmiSlotSpec, ...]¶
メニューのスロット。
create_pm()は空の tuple だけを受け付けます。
- data: str or None¶
read_pm()["data"]の形式の、保存された設定の生の文字列。create_pm()はNoneだけを受け付けます。
- class pme.PmiSlotSpec(mode='EMPTY', name='', text='', icon='')¶
PmCreationSpec.slotsの 1 要素を記述する、frozen な dataclass です。create_pm()はスロットを持つ spec を拒否します (slots_unsupported_by_create_pm)。スロットは作成後に追加・編集します。
- class pme.PmCreationResult(accepted, pm_uid, diagnostics)¶
create_pm()が返す、frozen な dataclass です。pme.types.PmCreationResultとしても使えます。- diagnostics: tuple[str, ...]¶
拒否のコード、画面更新に失敗した作成の後は
("refresh_failed",)、 それ以外は()。create_pm()を参照してください。
メニューを読み取る¶
- pme.editing.read_pm(pm_uid, *, slot_uids=None)¶
1 つのメニューの保存定義を、通常の Python の値で返します。
読み取りでは何も実行しません。Poll、説明の式、Getter、Setter は評価されず、 タグも同期されません。
- パラメータ:
- 戻り値:
下で説明する定義。
- 戻り値の型:
- 例外:
ValueError -- UID が存在しない、無効、または曖昧な場合。 または
slot_uidsの UID がそのメニューのスロットでない場合。
結果
キー
型
含まれる条件
値
uidstr
すべて
メニューの UID。
namestr
すべて
メニュー名。
modestr
すべて
メニューの種類の識別子(メニューの種類の識別子)。
enabledbool
すべて
メニューが有効か。
descriptionstr
すべて
メニューの説明、またはそれを返す式。
description_is_exprbool
すべて
descriptionが Python の式のときはTrue。poll_cmdstr
すべて
Poll のソース。
def poll(cls, context):の本体です。update_pm()を参照してください。tagslist[str]
すべて
保存されたタグのテキストにあるタグ名を、並べ替えて 1 回ずつ。 タグのないメニューでは
[]。hotkeydict
すべて
保存されたホットキーの割り当て。ホットキー を参照してください。
datastr
すべて
保存された設定の生の文字列。種類のマーカーに続けて
?と、&で連結したkey=valueの組が並びます。値はsettingsから読み取ります。settingsdict
すべて
設定名と現在の値の対応。設定のない種類では
{}。メニューの種類ごとの設定 を参照してください。settings_diagnosticslist[dict]
読み取れない
datadataを解析できないときだけ存在します。コードsettings_data_unreadableの要素が 1 つ入り、そのときsettingsは{}です。 メニューの種類ごとの設定 を参照してください。versionint
すべて
メニューの編集カウンター。スロットとレイアウトの操作に
expected_versionとして渡します。 セッション内だけの値で、まだバージョンがないメニューでは0です。 Python からの直接の書き込みをすべて検出するわけではありません。editable_slotsbool
すべて
その種類専用の操作で編集する種類では
False(メニューの種類の識別子)。slotslist[dict]
すべて
保存順に、スロットごとに 1 要素。または
slot_uidsで指定したスロットだけ。 各要素の説明は スロットのスナップショット にあります。rowslist[dict]
DIALOG、FPANELレイアウトの行。常に完全です。行構造を読む を参照してください。
routerdict
ROUTERContext Router の定義。Context Router を参照してください。
property_stackdict
CONDITIONProperty Stack の定義。Property Stack を参照してください。
propertydict
PROPERTYProperty の定義。Property を参照してください。
例
menu = pme.editing.read_pm(pm_uid) print(menu["mode"], menu["name"], [slot["uid"] for slot in menu["slots"]])
補足
返す値は切り離したコピーです。変更しても何も変わりません。
スロットの
textは保存されているテキストです。read_slot_inputs()は、 同じスロットをupdate_slots()が受け付ける入力名で返します。tagsは、保存されたタグのテキストを同期せずに読み取ります。 保存された空の名前の所属("")と、文字どおりの"Untagged"は区別されたままです。PMHandle.tag、list_tags()、PMItem.get_tags()は、それぞれの形式を保ちます。
メニューの名前・説明・Poll を変更する¶
- pme.editing.update_pm(pm_uid, changes, *, expected=None)¶
メニューの名前、説明、説明の形式、Poll のソースを変更します。
項目は 1 つずつ保存されます。呼び出しはアトミックではありません。 最初に拒否された項目で処理が止まり、それより前に保存された項目は保存されたまま残ります。
- パラメータ:
- 戻り値:
下で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
changesかexpectedがマッピングでない場合、description_is_exprが bool でない場合、またはほかの値が str でない場合。ValueError -- 項目名が 4 つのどれでもない場合、文字列が NUL 文字または UTF-8 にエンコードできないテキストを含む場合、または UID が存在しない、 無効、曖昧な場合。
結果
キー
型
値
statusstr
下の「ステータス」を参照してください。
committedbool
statusが"committed"のときだけTrue。pm_uidstr
引数
pm_uid。beforedict
呼び出し前に読み取った 4 つの項目。
afterdict
呼び出し後に読み取った 4 つの項目。
changed_fieldslist[str]
beforeとafterで値が異なる項目。 エディターのコールバックによる変更も含みます。fieldslist[dict]
試みた項目ごとに 1 要素(保存順):
field、status(committed、unchanged、rejectedのいずれか)、before、after、diagnostics。pendinglist[str]
試みなかった項目。
side_effectslist[dict]
changesにnameがあり、いずれかのメニューのスロットが変わったときだけ存在します。 スロットごとに 1 要素:pm_uid、pmi_uid、before、after。diagnosticslist[dict]
すべての項目の診断、または
stale_metadataの要素。ステータス
status意味
committed1 つ以上の項目を保存し、拒否された項目はありません。 ほかの項目が
unchangedのこともあります。unchangedすべての項目がすでに要求した値だった、または
changesが空です。 何も書き込んでいません。partial先の項目またはコールバックが保存値を変えた後に、項目が拒否されました。 再試行の前に
fields、pending、before/after、side_effectsを確認してください。rejected何も変わっていません。
expectedが一致しなかったか、 値が変わる前に項目が拒否されました。診断
code原因と追加のキー
stale_metadataexpectedの値が保存値と異なる。fieldsに項目名が入ります。rename_rejected異なる空でない名前を指定したのに、エディターが古い名前を保った。
name_adjusted保存された名前が要求した名前と異なる。
@が取り除かれたか、 名前が使用中のため.001のような接尾辞が付いた。requestedとactualに両方の名前が入ります。metadata_value_not_retainedsetter が、要求した
description、description_is_expr、poll_cmdを保たなかった。poll_compile_errorpoll_cmdは保存されたが、コンパイルできない。messageにエラーが入ります。 この診断は項目の状態を変えません。例
読み取った後に 4 つの項目が変わっていないことを確認しながら、 プレーンテキストのメニュー説明を追加します。
before = pme.editing.read_pm(pm_uid) fields = ("name", "description", "description_is_expr", "poll_cmd") result = pme.editing.update_pm(pm_uid, { "description_is_expr": False, "description": "Mesh tools. Unmatched contexts keep Blender's shortcut.", }, expected={key: before[key] for key in fields}) print(result["status"], result["after"], result["diagnostics"])
補足
descriptionとdescription_is_exprの両方を指定すると、description_is_exprが先に保存されます。そのため、形式の変換が指定した説明を書き換えることはありません。 ほかのエディターのコールバックも保存値を変えることがあり、その変更はchanged_fieldsに現れます。改名にはエディターの改名処理を使います。そのメニューにリンクする Menu スロット、 改名した Pop-up Dialog の名前を持つ Panel Group の項目、Tree、ホットキー登録が更新されます。 Command・Custom・Poll のソーステキストと Router のターゲットの
fallback_nameは書き換えられず、side_effectsにも含まれません。その中の名前による呼び出しは古い名前のままです。要求した名前から
@は取り除かれます。空の名前または現在の名前では、名前は変わりません。Property ID をロックしていない Property Stack を改名すると、新しい ID が生成されることがあります。 改名後に
property_stack["registered_property_id"]を読み直してください。 古い ID を埋め込んだウィジェットは書き換えられません。poll_cmdはdef poll(cls, context):の後に付け加えられます。"return context.mode == 'EDIT_MESH'"のような 1 行の本体は、そのままで有効です。 複数行の本体は改行で始め、各行を字下げします。コンパイルできない Poll のソースは、エディターと同じように保存され、
poll_compile_errorが付きます。一方、スロットのcmd、prop、customの構文エラーは、スロットの保存前に拒否されます。 どちらの検査も実行時の動作を証明しません。有効状態、ホットキー、種類ごとの設定は、この関数の項目ではありません。 Poll と説明のソースは評価されません。
予期しない例外は traceback を保ち、確定した項目を示す注記が加わります。 再試行の前に、そのメニューと、それを参照するメニューを読み取ってください。
メニューを有効・無効にする¶
- pme.editing.set_enabled(pm_uids, enabled, *, expected=None, dry_run=False)¶
エディターの一括の Enable と Disable と同じように、メニューを有効または無効にします。
最初の書き込みの前に、すべての対象を検査します。 書き込みが失敗すると、すでに書き込んだ有効状態の値を元に戻します。
- パラメータ:
pm_uids (non-string iterable of str) -- 重複しないメニューの UID。対象はコレクション順に処理します。 空の iterable では
unchangedを返します。enabled (bool) -- すべての対象に設定する値。
expected (dict[str, bool] or None) -- 要求した各 UID と、その UID が現在持っているべき保存値の対応。 要求した UID と過不足なく一致させます。一致しないときは、書き込みの前に拒否されます。
Noneでは呼び出し開始時に読み取った値を使います。dry_run (bool) -- 書き込まずに検査して返します。
- 戻り値:
下で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
enabledかdry_runが bool でない場合(int は受け付けません)、pm_uidsが文字列の場合、またはexpectedが bool のマッピングでない場合。ValueError --
pm_uidsに無効または重複した UID がある場合、 またはexpectedが要求した UID を過不足なく指定していない場合。
結果
キー
型
値
statusstr
下の「ステータス」を参照してください。
committedbool
statusが"committed"のときだけTrue。dry_runbool
引数
dry_run。target_uidslist[str]
コレクション順の対象。 解決できなかったときは指定された順。
beforedict[str, bool]
呼び出し開始時の保存値。対象を解決できなかったときは
{}。afterdict[str, bool]
呼び出し後に読み取った値。読み取れなかった対象は省かれ、
diagnosticsに示されます。 dry run の後は現在の値。expecteddict[str, bool]
expectedに渡すためのbeforeのコピー。確定の後でも、 新しい状態ではありません。planned_uidslist[str]
保存値が
enabledと異なる対象。attempted_uidslist[str]
setter を呼んだ対象。dry run の後は
[]。changed_uidslist[str]
呼び出しで変わった対象。dry run の後と、 復元を確認した後は
[]。registrationdict[str, dict]
対象ごとに、呼び出し後に観測したホットキー登録:
scope("hotkey")、status(not_required、registered、partial、unknownのいずれか)、required、lanes、diagnostics。ホットキー を参照してください。selectiondict
beforeとafter:active_pm_uid、active_index、selected_pm_uids、select_mode_active、tree_cursor、mode。読み取れないときはNone。visibilitydict
beforeとafter:scope("last_rendered_region")、status(observedまたはunknown)、visible_uids、targets(UID と、bool またはNoneの対応)。owner_statusstr
共有の一括操作のステータス:
APPLIED、VALIDATED、NO_CHANGE、REJECTED、RESTORED_FAILURE、ROLLBACK_FAILEDのいずれか。reasonstr
拒否または失敗のコード。ないときは
""。rollback_reasonstr
復元を確認できなかった理由。ないときは
""。diagnosticslist[dict]
下の「診断」を参照してください。
ステータス
status意味
validateddry_run=Trueで、1 つ以上の値が変わる見込みです。 何も書き込んでいません。unchangedすべての対象がすでにその値を持っている、または
pm_uidsが空です。 setter は実行されず、ホットキー登録も修復されていません。committedすべての値を書き込み、読み戻しました。
rejected何も書き込んでいません。
diagnosticsに原因が示されます。restored_failure書き込みが失敗し、元に戻した有効状態の値を確認しました。
unknown書き込みが失敗し、復元を確認できませんでした。 再試行の前にメニューを読み取ってください。
診断
拒否または失敗の要素は
code(reasonの値)とrollback_reasonを持ちます。code原因と追加のキー
pm_availability_target_missingUID がメニューのコレクションにない。
pm_availability_live_identity_invalid保存されたメニューが UID の検査に通らない(例: 複数のメニューが UID を共有している)。検査の範囲は対象だけでなく、 コレクション全体です。
pm_availability_expected_mismatchexpectedの値が保存値と異なる。beforeに保存値が入ります。pm_availability_target_state_unavailable対象の有効状態の値を読み取れなかった。
pm_availability_collection_stale呼び出し中にメニューのコレクションが変わった。
rollback_reasonの値にもなります。pm_availability_target_stale書き込みの前に対象の値が変わった。
pm_availability_apply_failedsetter が例外を送出した。
pm_availability_apply_readback_mismatchsetter が値を保たなかった。
pm_availability_post_apply_mismatch最後の読み取りが要求した値と異なる。
pm_availability_rollback_incompleterollback_reasonの値としてだけ使われます。 元に戻した値をすべては確認できなかった。pm_availability_target_unavailable呼び出し後に対象を解決できなかった。
pm_uid、phase、reason(解決処理のステータス)。pm_availability_readback_unavailable呼び出し後の対象の読み取りで例外が発生した。
pm_uid、phase、exception_type。pm_availability_registration_unavailable対象のホットキー登録の読み取りで例外が発生した。
pm_uid、phase、exception_type。pm_availability_context_unavailable選択と可視性を読み取れなかった。
phase(beforeまたはafter)、exception_type。例
preview = pme.editing.set_enabled([pm_uid], False, dry_run=True) print(preview["status"], preview["before"], preview["planned_uids"]) if preview["status"] == "validated": result = pme.editing.set_enabled( [pm_uid], False, expected=preview["expected"], ) print(result["status"], result["after"], result["registration"]) print(result["diagnostics"])
補足
committedが確認するのは、保存された有効状態の値だけです。registrationは現在のホットキーの状態を報告します。Macro、Property、Property Stack、Panel の資源、 Poll、Getter、Setter、アクションが実行されるかは確認しません。 登録の警告やunknownの観測は、確定したstatusを変えません。無効なメニュー、キーのないメニュー、ホットキーのない種類、Open Mode が
CLICKの Vector Menu は、ホットキー登録を必要としません(not_required)。dry run の後の
registrationは現在の登録で、予測ではありません。dry run は対象を予約せず、コールバックが成功することも証明しません。 後の呼び出しで、解決と検査をやり直します。
復元の範囲は有効状態の値だけで、ほかの保存項目やエディターの資源は含みません。 失敗の後は
before、after、attempted_uids、changed_uids、reason、rollback_reason、diagnosticsを合わせて読んでください。選択、Slot Editor で編集中の内容(対象が持つものも含む)、一覧のフィルターは、 対象が非表示になってもそのまま残ります。
visibilityは最後に描画されたリージョンでの観測で、unknownの場合もあり、新しいフレームが描画されたことは証明しません。
タグを追加・解除する¶
- pme.editing.update_tags(pm_uids, *, add=(), remove=(), expected=None, dry_run=False)¶
複数のメニューのタグ名を、1 回の一括操作で追加・解除します。
呼び出しは 2 つの段階からなります。通常の Tag 同期と、 その後の、エディターのタグ操作が使う一括書き込みです。 2 つは 1 つのアトミックなトランザクションではありません。
- パラメータ:
pm_uids (non-string iterable of str) -- 重複しないメニューの UID。
add (non-string iterable of str) -- 追加する名前。それぞれ前後の空白を除きます。カンマで複数の名前を区切ります。 空の名前と
Untaggedは無視され、ignored_namesに記録されます。remove (non-string iterable of str) -- 解除する名前(完全一致)。空白を除かず、カンマでも分割しません。
expected (dict or None) -- この関数の以前の結果の
expected全体を、変更せずに渡します:activated、targets_digest、definitions_digest。同期の前に比較します。dry_run (bool) -- 同期も書き込みもせずに検査して返します。
- 戻り値:
下で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
dry_runが bool でない場合、pm_uids、add、removeが文字列であるか文字列以外を含む場合、またはexpected["activated"]が bool でない場合。ValueError --
pm_uidsに無効または重複した UID がある場合、 UID が存在しないか曖昧な場合、removeに同じ名前が 2 回ある場合、 同じ名前がadd全体で 2 回出るかaddとremoveの両方に出る場合、 またはexpectedが 3 つのキーをちょうど持つマッピングでないか、 小文字の SHA-256 16 進文字列でない digest を持つ場合。
結果
キー
型
値
statusstr
下の「ステータス」を参照してください。
committedbool
statusが"committed"のときだけTrue。dry_runbool
引数
dry_run。target_uidslist[str]
引数
pm_uids。expecteddict or None
開始時に読み取った状態の
activated、targets_digest、definitions_digest。その読み取りに失敗したときはNone。beforedict or None
対象ごとに、同期の前に読み取った
raw(保存されたタグのテキスト)、tags、ref_uids、projection_stamp。afterdict or None
呼び出し後に読み取った同じキー。読み取れないときは
None。changed_uidslist[str] or None
同期の後と最後の読み取りとで値が異なる対象。 段階が失敗した後は
None。synchronizeddict or None
通常の同期が、任意のメニューやタグ定義に加えた変更:
pms、definitions、version、activated(あるものだけ)。statusがunchangedでも値が入ることがあります。ignored_nameslist[dict]
無視された
addの要素ごとにnameとreason("legacy_add_noop")。selectiondict
beforeとafter:active_hidden_by_list_filterとlist_filter_scope("mode_tag_new_health")を加えた 選択のスナップショット。recoverydict or None
段階が失敗した後に入ります:
phase、baseline、carrier_matches、attempted(None)、scope("tag_carrier")。diagnosticslist[dict]
下の「診断」を参照してください。
ステータス
status意味
validateddry_run=Trueで、対象と変更があり、expectedが一致しています。 何も書き込んでいません。unchanged対象がない、
addとremoveのどちらにも要素がない、 または一括書き込みがどのメニューも変えませんでした。synchronizedは別に確認してください。committed一括書き込みが 1 つ以上のメニューを変えました。
rejected保存されたタグのデータは変わっていません。
expectedが古い、 開始時の状態を読み取れなかった、または同期が失敗し、 保存されたタグのデータがbeforeと同じままです。unknown一括書き込みが失敗したか、同期が失敗し、 保存されたタグのデータが
beforeと異なるか読み取れませんでした。 再試行の前に値を読み取ってください。診断
各要素は
phaseとcodeを持ちます。例外による要素はexception_typeとmessageも持ちます。code原因
tag_expected_staleexpectedが現在の状態と異なる。段階はpreflight。tag_snapshot_failed開始時にタグのデータを読み取れなかった。
tag_update_failed同期または一括書き込みが例外を送出した。段階は
synchronizeまたはbatch。独自のコードを持つ例外では、 代わりにそのコードを報告します。tag_carrier_readback_failed、tag_targets_readback_failed呼び出し後の値を読み取れなかった。
tag_synchronization_readback_failed失敗の後に、同期による変更を読み取れなかった。
tag_selection_readback_failed、tag_filter_readback_failed選択または一覧のフィルターの状態を読み取れなかった。
refresh_pending画面更新が延期された。段階は
refresh。tag_refresh_failed画面更新が例外を送出した。段階は
refresh。例
targets = [first_pm_uid, second_pm_uid] preview = pme.editing.update_tags( targets, add=["Review"], remove=["Draft"], dry_run=True, ) if preview["status"] == "validated": result = pme.editing.update_tags( targets, add=["Review"], remove=["Draft"], expected=preview["expected"], ) print(result["status"], result["after"], result["synchronized"]) print(pme.editing.read_pm(first_pm_uid)["tags"])
補足
一括処理は、Tag Registry が有効でも無効でも、エディターのタグの書き込み処理を使います。 タグ定義は削除しません。
名前は大文字小文字と Unicode をそのまま保ちます。
add=["A,B"], remove=["B"]は競合です(ValueError)。 無視される追加も重複の検査には含まれます。名前の長さに追加の制限はありません。名前の集合が変わらない場合でも、 書き込みが保存されたタグのテキストの順序と重複を正規化することがあります (例: すでに所属している名前の追加、存在しない名前の解除)。 名前の集合ではなく保存値を比べてください。
expectedは JSON の往復でも保たれます。対象の保存されたタグのテキスト、 参照、projection stamp と、レジストリの定義を範囲とします。 古いexpectedは書き込みなしで拒否されます。dry run は入力、対象、名前の変換を検査します。 同期、UID の割り当て、新しい定義の予測は行わず、 後の書き込みが成功することも証明しません。
空の変更または空の対象集合では、
expectedの検査の後に、 同期も画面更新もせずにunchangedを返します。recovery.carrier_matchesは保存されたタグのデータをbaselineと比べます。baselineは、同期が失敗したときは"before"、 一括書き込みが失敗したときは"after_synchronize"です。Trueが証明するのは保存データの一致だけです。 ロールバックが実行されたかは分からないため、attemptedはNoneです。 一致してもrestored_failureとしては報告されません。一括書き込みの成功後の読み戻しや画面更新の失敗は、確定した結果を変えません。
アクティブなメニュー、選択されているメニュー、Slot Editor で編集中の内容 はそのまま残ります。 同じ Tree の行がまだあり、画面更新が成功したときは、その行が選択されたままです。
active_hidden_by_list_filterは、現在の mode・tag・new・health のフィルターの結果で、 名前の検索と折りたたまれた行は含みません。不明なときはNoneです。
メニューを複製する¶
- pme.editing.duplicate_pm(source_pm_uid, *, name=None, expected=None, dry_run=False)¶
1 つのメニューを複製し、コピーを複製元の直後に挿入します。
コピーはエディターの Duplicate で作られます。アクティブなメニュー、選択、 Slot Editor で編集中の内容 はそのまま残ります。エディターの Duplicate はコピーを選択しますが、 この関数は選択しません。
- パラメータ:
- 戻り値:
下で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
source_pm_uidが空でない str でない場合、nameが str でもNoneでもない場合、dry_runが bool でない場合、expectedがマッピングでない場合、またはその値の型が誤っている場合。ValueError --
expectedが 3 つのキーをちょうど持たない場合、 またはそのcollection_versionが負の場合。
結果
キー
型
値
statusstr
下の「ステータス」を参照してください。
committedbool
statusが"committed"のときだけTrue。dry_runbool
引数
dry_run。source_pm_uidstr
引数
source_pm_uid。createddict or None
コピーの
pm_uid、name、コレクション内のindex。dry run の後、 またはコピーが存在しないときはNone。beforedict
pm_uids(コレクション順)、source(保存済みメニューのスナップショット)、created(常にNone)。afterdict
呼び出し後に読み取った同じキー。
createdはコピーの保存スナップショットです。expecteddict or None
collection_version、source_pm_uid、source_digest。 複製元を読み取れなかったときはNone。collection_version_before、collection_version_afterint or None
呼び出し前後のメニューのコレクションのバージョン。
selection_before、selection_afterdict or None
not_inheritedlist[str]
key、any、ctrl、shift、alt、oskey、key_mod、enabled。recoverydict
attempted(False、True、不明なときはNone)と、uid_order、active_uid、source_digest(それぞれ呼び出し前の値と等しいか。bool またはNone)。data_scopeは"collection_order_active_uid_source_saved_values"です。diagnosticslist[dict]
下の「診断」を参照してください。
ステータス
status意味
validateddry_run=Trueで、検査に通りました。何も書き込んでいません。rejected何も書き込んでいません。
diagnosticsに原因が示されます。committedDuplicate が確定しました。
restored_failureDuplicate が失敗しました。元の UID の順序、アクティブな UID、 複製元の保存値が変わっていないことを読み戻しで確認しました。
unknown結果または復旧を確認できませんでした。 再試行の前にコレクションを読み取ってください。
診断
code原因と追加のキー
pm_identity_*保存されたメニューが UID の検査に通らない。例: 複数のメニューが UID を共有するときの
pm_identity_uid_duplicate。pm_duplicate_source_unavailablesource_pm_uidを持つメニューがない。pm_duplicate_unsupported_mode複製元の種類が既知のメニューの種類でない。
pm_duplicate_stale_expectedexpectedが現在のコレクションのバージョンまたは複製元と異なる。pm_duplicate_snapshot_failed開始時の状態の読み取りで例外が発生した。
exception_type、message。target_rejected、dry_run_rejectedDuplicate が書き込みの前に拒否した(例: コレクションまたは複製元が変わった)。
statusはrejectedです。apply_failedDuplicate が書き込み中に例外を送出し、自身のロールバックを実行した。
statusはrestored_failureまたはunknownです。pm_duplicate_failedDuplicate が自身の処理の外で例外を送出した。
statusはunknownです。exception_type、message。pm_duplicate_refresh_failed確定の後、画面更新または Tree の選択の復元が失敗した。 確定はそのまま有効です。
pm_duplicate_readback_failed呼び出し後の値を読み取れなかった。その値は
Noneです。field、exception_type、message。pm_duplicate_readback_unavailable呼び出し後に複製元またはコピーを解決できなかった。
field。例
preview = pme.editing.duplicate_pm(pm_uid, name="Working copy", dry_run=True) print(preview["status"], preview["not_inherited"]) if preview["status"] == "validated": result = pme.editing.duplicate_pm( pm_uid, name="Working copy", expected=preview["expected"], ) print(result["status"], result["created"], result["diagnostics"])
補足
コピーは、アクティブなメニューや表示の並び順にかかわらず、 コレクション順で複製元の後に置かれます。
コピーとそのスロットには新しい UID が割り当てられます。スロットの内容、スロットの
enabled、 タグ、エディターの種類ごとの複製動作は引き継がれます。 コピー内の参照は参照先を保ちます。not_inheritedの項目は複製されません。コピーは有効で、 ホットキーのキーがない状態で始まります。Property Stack のコピーは HUD の外観を保ち、監視はオフになります。 複製元の Property ID は再利用しません。
dry run は UID を作らず、バージョンを初期化せず、選択を変えず、何も登録せず、 HUD の設定も書き込みません。名前を予約したり、 コレクションの順序を固定したりもしません。
expectedは JSON の往復でも保たれます。 範囲は、複製元の保存値(バージョンを更新しない編集も含む)と、コレクションのバージョンです。同じ Tree の行がまだあるときは、その行が選択されたままです。 コピーがフィルターで非表示になっても、別のメニューが選択されることはありません。
画面更新や読み戻しの失敗は、確認済みの確定を取り消しません。
recoveryの範囲は Duplicate 自身のロールバックとその保存データの検査だけで、 エディターの登録や host の資源は含みません。
メニューを1件または複数削除する¶
- pme.editing.delete_pms(pm_uids, *, expected=None, dry_run=False)¶
エディターの Selected Remove と同じように、メニューを削除します。
削除するメニューへの参照は報告されますが、削除も書き換えもされません。 残ったメニューが、削除されたメニューへのリンクを持ち続けることがあります。
- パラメータ:
pm_uids (non-string iterable of str) -- 1 つ以上の重複しないメニューの UID。 1 つのメニューでも 1 要素のリストで渡します。対象はコレクション順に処理します。
expected (dict or None) -- dry run が返した
expected全体を、変更せずに渡します:collection_version、collection_digest、target_digests、references_digest。Noneでは呼び出し開始時に読み取った状態を使います。dry_run (bool) -- 削除せずに検査して返します。
- 戻り値:
下で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
pm_uidsが文字列の場合、またはdry_runが bool でない場合。ValueError --
pm_uidsが空であるか、無効または重複した UID を含む場合。 またはexpectedの形が不正な場合 (キーの不足、負のcollection_version、要求した UID 以外のtarget_digestsのキー、 小文字の SHA-256 16 進文字列でない digest)。
結果
キー
型
値
statusstr
下の「ステータス」を参照してください。
committedbool
statusが"committed"のときだけTrue。dry_runbool
引数
dry_run。target_uidslist[str]
コレクション順の対象。 解決できなかったときは指定された順。
beforedict
対象ごとに、開始時に読み取った 保存済みメニューのスナップショット。 対象を解決できなかったときは
{}。afterdict
対象ごとの呼び出し後のスナップショット。削除された対象では
None、 読み取れないときは{"readback_unavailable": True}。referenceslist[dict]
対象を指す、または読み取れなかった 参照の行。
source_survivesとtarget_missing_afterが加わります。expecteddict or None
開始時に読み取った状態の 4 つの前提条件。その読み取りに失敗したときは
None。removed_uidslist[str]
コレクションにもうない対象。拒否されたときは
[]。remaining_target_uidslist[str]
まだコレクションにある対象。
remaining_uidslist[str] or None
最終的なコレクションの順序。
collection_version_before、collection_version_afterint
呼び出し前後のメニューのコレクションのバージョン。
selection_before、selection_afterdict or None
planned_active_uidstr or None
削除後にアクティブにする予定のメニュー。削除の計画が立たなかったときは
None。recoverydict
status(APPLIED、REJECTED、RESTORED_FAILURE、BLOCKED_RECOVERYのいずれか)、rollback_attempted、rollback_confirmed、rollback_reason、rollback_exception_type、data_scope("owned_menu_saved_values")、host_scope("existing_batch_recovery_postconditions")、hotkey_observation。diagnosticslist[dict]
下の「診断」を参照してください。
ステータス
status意味
readydry_run=Trueで、検査に通りました。何も削除していません。rejected何も削除していません。
diagnosticsに原因が示されます。committed要求したメニューをコレクションから削除しました。
restored_failure削除が失敗し、削除処理自身の復旧を確認しました。
unknown復旧を確認できなかったか、削除の後に対象が残っているか、 最後の読み取りが失敗しました。 再試行の前にコレクションを読み取ってください。
診断
すべての結果に
static_reference_coverage(severityは"warning")が含まれます。warningを持つ参照の行ごとに、code(その warning)、severity、source_pm_uid、pathを持つ要素が加わります。拒否や失敗では、code、phase、exception_typeを持つ要素が加わります。code原因
static_reference_coverage常に含まれます。 実行時に参照を組み立てる Python は見つけられません。
pm_remove_target_missingUID がメニューのコレクションにない。
pm_remove_live_identity_invalid保存されたメニューが UID の検査に通らない(例: 複数のメニューが UID を共有している)。
pm_remove_host_name_ambiguous別のメニューが対象と同じ名前を持つ。
pm_remove_active_invalidアクティブなメニューのインデックスが有効でない。
pm_remove_plan_invalid選択の状態またはコレクションのバージョンを、 削除の計画に使えない。
pm_remove_draft_conflictSlot Editor で編集中の内容 が対象のものである。
pm_remove_saved_state_staleexpectedが異なる、 または呼び出し中に対象の保存値かその対象への参照が変わった。pm_remove_collection_stale呼び出し中に、コレクション、そのバージョン、または選択が変わった。
pm_remove_target_changed削除の前に、対象の名前、種類、または位置が変わった。
pm_remove_snapshot_failed開始時の状態の読み取りで例外が発生した。
pm_remove_apply_failedメニューの削除で例外が発生した。
pm_remove_apply_readback_mismatchコレクションを読み取っても、削除を確認できなかった。
pm_remove_terminal_failed最終的なアクティブなメニューと選択の設定が失敗した。
pm_remove_version_commit_failed削除の後にコレクションのバージョンを更新できなかった。
pm_remove_readback_failed最後の読み取りで例外が発生した。
pm_remove_hotkey_readback_failedrecovery.hotkey_observationを読み取れなかった。pm_remove_refresh_failed削除の後、画面更新の処理が例外を送出した。
phaseにその処理が入ります。確定はそのまま有効です。pm_remove_recovery_publish_failed失敗した復旧の後の画面更新の処理が例外を送出した。
recovery.rollback_reasonは、pm_remove_rollback_failed(復元したコレクションまたは選択が異なる)、pm_remove_host_recovery_unproven(ホットキーまたは Floating Panel の解除処理が始まっていた)、pm_remove_version_commit_failedのいずれかです。例
preview = pme.editing.delete_pms([pm_uid], dry_run=True) print(preview["status"], preview["references"], preview["diagnostics"]) if preview["status"] == "ready": result = pme.editing.delete_pms([pm_uid], expected=preview["expected"]) print(result["status"], result["removed_uids"], result["recovery"])
補足
dry run は保存値、バージョン、選択、編集中の内容、host の登録を変更しません。
beforeとafterは同じ値を持ちます。planned_active_uidを返します。対象を予約せず、 解除処理が成功することも証明しません。expectedは、コレクションの識別情報と順序、対象の保存内容、 対象への保存された参照を比べます。コレクションのバージョンを増やさない変更も検出します。 古いと判定された後は、読み直して改めて判断します。expectedがなくても、各対象を削除する前に、開始時の状態を再び検査します。referencesには、無効または未完成の Router と Property Stack の参照も含まれます。 実行時に参照を組み立てる Python は見つかりません。 走査範囲の警告は削除を妨げません。ほかのメニューのSlot Editor で編集中の内容 はそのまま残ります。 対象外のアクティブなメニューは UID を保ちます。 アクティブなメニューが削除されたときは、その後ろで次に残っているメニューがアクティブになり、 後ろにないときは、前にある最も近いメニューがアクティブになります。 残ったメニューを表示するためにフィルターを解除することはありません。
保存データの復旧と host の登録の復旧は別です。定義が復元されても、 すべてのエディターの資源が復元されたことは証明されません。 削除の後に画面更新が失敗しても、確定した結果は保たれます。
recovery.hotkey_observationの範囲は、削除の checkpoint と PME 自身のホットキーの記録だけです。 記録がないことは、Blender のすべてのキーマップ項目や、 ほかのエディターの資源が取り除かれたことを証明しません。
参照元を照会する¶
- pme.editing.find_references(pm_uids)¶
指定したメニューを参照している保存箇所を一覧にします。
何も書き込みません。読み取るのは保存データ中の静的な参照だけです。 空の結果は、対応している参照が見つからなかったことを表し、 メニューが使われていないことは表しません。
- パラメータ:
pm_uids (non-string iterable of str) -- 重複しないメニューの UID。
- 戻り値:
下で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
pm_uidsが文字列の場合。ValueError -- UID が無効または 2 回指定されている場合、または UID が存在しないか、 保存済みの複数のメニューで共有されている場合。
結果
キー
型
値
target_uidslist[str]
引数
pm_uids。referenceslist[dict]
target_uidが対象のいずれかである 参照の行。unscannablelist[dict]
対象に限らずすべてのメニューから集めた、内容を静的に読み取れなかった行。
target_uidはNoneです。例
found = pme.editing.find_references([pm_uid]) for row in found["references"]: print(row["kind"], row["source_pm_name"], row["path"]) if found["unscannable"]: print("Possibly referenced:", len(found["unscannable"]), "unreadable places")
補足
行は
delete_pms()の事前確認と同じもので、source_survivesとtarget_missing_afterを除いたものです。unscannableが空でない間は、メニューが参照されている可能性があるものとして扱ってください。
参照の行¶
すべての行が次のキーを持ちます。
キー |
型 |
値 |
|---|---|---|
|
str |
|
|
str |
参照を持つメニュー。 |
|
bool |
そのメニューが有効か。 |
|
str or None |
参照されている対象。読み取れなかった行では |
|
list |
参照元のメニュー内の場所。スロットでは |
|
any |
|
|
str |
スロットの行と |
|
bool |
|
|
bool |
|
スロットからの行は source_pmi_uid も持ちます。
menu_reference、text_call、text_property_ref の行は、さらに
raw_target (見つかった名前または UID)、item_name、item_mode、item_enabled、
target_pm_uid (スロットに保存された参照先の UID)、
flags (Menu スロットの表示フラグ、または None)を持ちます。
Router と Property Stack のロジックからの行は、その場所を特定する項目を写して持ちます。
target と source の行は source_segment_index も持ちます
(Router のターゲットでは -1)。
場所 |
追加のキー |
|---|---|
Router の分岐のターゲット |
|
Router の Otherwise のターゲット |
|
Router の条件のソース |
|
Property Stack の行のソース |
|
Property Stack の書き込み項目のソース |
|
検出される参照:
保存箇所 |
見つかる参照 |
|
|---|---|---|
Menu スロット(有効・無効を問わない) |
リンク先のメニュー。 |
|
Command または Custom スロットのテキスト(Property のコールバックを含む) |
名前を第 1 引数または |
|
Command または Custom スロットのテキスト(Property のコールバックを含む) |
|
|
Router の分岐または Otherwise |
メニューを開くターゲット。 |
|
Router の条件、Property Stack の行または書き込み項目 |
Property または Property Stack を読むソース。 |
|
unscannable に含まれるもの(warning 別):
|
保存箇所 |
|---|---|
|
有効な Python でない Command または Custom スロットのテキスト。 |
|
対象が実行時に計算されるメニューの呼び出しまたは |
|
解析できない、またはコンテナの形が不正な、 Router や Property Stack のロジック。 |
|
想定した形を持たない、 Router の条件または Property Stack のソース。 |
|
マッピングでない、保存されたターゲットまたはソース。 |
|
デコードできない Router のターゲット。 |
読み取らず、unscannable にも含まれないもの:
Property スロット。Property スロットに書いた
props().idは見つかりません。コマンドまたはカスタムスクリプトを実行する Router のターゲット。
Property Stack のカスタム Set のテキスト。
メニューの Poll と説明のスクリプト。
スクリプトファイル、ホットキー、PME の外の Python。