レイアウトの行とパネル

Pop-up Dialog(DIALOG)とFloating Panel(FPANEL)は、行、spacer、Layout Panelをメニューの保存リストにスロットとして保存します。 このページの関数は、そのリストを行として読み取り、行、spacer、項目の揃え、Layout Panelを変更します。 単独の項目の追加・削除・移動・編集は スロット、Modeや幅などのメニュー設定は メニューの種類ごとの設定 にあります。

関数

用途

read_pm()

行を rows で返します。

add_row()

既定のボタンを持つ行を追加します。

add_panel()

Layout Panelを持つ行を追加します。

remove_row()

行とその中身をすべて削除します。

move_row()

行を別の行の前後へ移動します。

split_row()

行を、その行のスロットの一つの直前で分割します。

join_rows()

隣接する2行を結合します。

update_row()

行設定を変更します。

update_spacer()

spacerの設定を一つ変更します。必要ならspacerを作成します。

align_slot()

項目を行の左・中央・右の区分に配置します。

保存されるレイアウト

保存リストは、左から右、上から下の順に読みます。レイアウトを担うスロットは3種類です。

スロット

保存形式

意味

行マーカー

mode は "EMPTY"、text は row で始まる。例: "row?size=LARGE"

行を開始します。この文字列に行設定が入ります。

spacer

mode は "EMPTY"、text は spacer で始まる。例: "spacer?hsep=COLUMN"

行内の間隔、列境界、揃え境界、subrow境界。 この文字列にspacerの設定が入ります。

Layout Panel アンカー

mode は "MENU" で、layout_panel オプションを持つ

Layout Panelを開始します。同じ行でアンカーより後のスロットがPanel ヘッダーです。

行はマーカーから次のマーカーまでです。最初のマーカーより前のスロットは、マーカーのない先頭行になり、 既定の設定を持ちます。新しいPop-up DialogまたはFloating Panelは、マーカーとボタンを一つずつ持ちます。

行構造を読む

read_pm(pm_uid)["rows"] は、Pop-up DialogまたはFloating Panelの行を保存順に並べます。 他の種類のメニューには rows キーがありません。空のメニューは rows == [] です。 read_pm() の slot_uids 引数が絞り込むのは slots だけで、rows は常にメニュー全体を表します。 読み取りでは、マーカーの追加、UIDの修復、バージョンの初期化、レイアウトの変更を行いません。

各行は次の辞書です。

キー

型

値

row_ref

dict

行への参照。行参照 を参照。

slot_uids

list[str]

行内の全スロットのUID。保存順で、マーカーを含みます。

has_marker

bool

マーカーのない先頭行では False。

raw_text

str or None

マーカーの保存文字列。マーカーがなければ None。 保存文字列内の未知のキーはここにだけ現れます。

settings

dict

名前ごとの行設定。行設定 を参照。 保存文字列にない名前は既定値です。マーカーのない行はすべて既定値で、 先頭項目の文字列を行設定として読みません。

defaulted_fields

list[str]

保存文字列にない設定名。マーカーのない行ではすべての名前。

diagnostics

list[dict]

保存文字列を解析できないときは、exception_type と message を持つ layout_parse_failed。 このとき settings は既定値を持ち、raw_text は保存文字列を保持します。

spacers

list[dict]

行内のspacerごとに1件、保存順。下記を参照。

panel

dict or None

行のLayout Panel、または None。下記を参照。

spacerの要素は次のとおりです。

キー

型

値

slot_uid

str

spacerのUID。

raw_text

str

spacerの保存文字列。

settings

dict

hsep と subrow。spacerの設定 を参照。

defaulted_fields

list[str]

保存文字列にない設定名。

diagnostics

list[dict]

行と同じ。

panel の値は次のとおりです。

キー

型

値

anchor_uid

str

アンカーのUID。行内で最初のLayout Panel アンカーです。

options

dict

アンカーのオプションを idname (str)、default_closed (bool)、 use_header_layout (bool) として読んだ値。

layout_panel

any

その読み取りを行う前の、保存済みの layout_panel の値。JSONの値として返します。

layout_panel_present

bool

アンカーに保存済みの layout_panel の値があるかどうか。

header_uids

list[str]

行内でアンカーより後の全スロット。保存順です。 無効な項目と、Header LayoutがOFFの間は非表示の項目も含みます。

>>> pme.editing.read_pm(pm_uid)["rows"][0]
{'row_ref': {'kind': 'marker', 'slot_uid': 'pmi_gxyya7hr'},
 'slot_uids': ['pmi_gxyya7hr', 'pmi_glcfd66v'], 'has_marker': True,
 'raw_text': 'row',
 'settings': {'align': 'CENTER', 'size': 'NORMAL', 'vspacer': 'NORMAL',
              'fixed_col': False, 'fixed_but': False},
 'defaulted_fields': ['align', 'size', 'vspacer', 'fixed_col', 'fixed_but'],
 'diagnostics': [], 'spacers': [], 'panel': None}
>>> panel_row["panel"]
{'anchor_uid': 'pmi_nptwzacb',
 'options': {'idname': 'layout_panel_tbcduupz', 'default_closed': False,
             'use_header_layout': False},
 'layout_panel_present': True,
 'layout_panel': {'idname': 'layout_panel_tbcduupz', 'default_closed': False,
                  'use_header_layout': False},
 'header_uids': []}

行参照

row_ref は {"kind": kind, "slot_uid": uid} で、行を開始するスロットを指します。 kind は、そのスロットが行マーカーなら "marker"、マーカーのない先頭行の先頭スロットなら "first_item" です。row_ref は永続的な行IDではありません。

row_ref は、行が同じスロット・同じkindで始まっている間だけ受け付けられます。 そのスロットが移動・削除されたとき、別のスロットがその前に置かれたとき、マーカーのない先頭行にマーカーが追加されたとき(参照が "first_item" から "marker" に変わる)には一致しなくなります。 古い参照は別の行へ付け替えられず、操作は row_not_found で拒否します。 現在の参照は、直前の結果の after_rows から取るか、読み直して取得してください。

行の操作は、キーがちょうど kind と slot_uid の row_ref を受け付けます。 他のキーがある、またはキーが欠けている場合は TypeError、それ以外の kind は ValueError を送出します。

行設定

行設定は行マーカーの文字列に保存されます。update_row() は次の名前と値を受け付けます。

名前

型

値の範囲

既定値

説明

align

str

CENTER, LEFT, RIGHT

CENTER

行に ALIGNER spacerがないときの、行とそのsubrowの寄せ。 align_slot() とは別の設定です。エディターのRow Alignmentメニューは、 この設定を非推奨と表示し、ボタンの揃えを案内します。

size

str

NORMAL, LARGE, LARGER

NORMAL

ボタンの高さ。通常の1倍、1.25倍、1.5倍。

vspacer

str

NONE, NORMAL, LARGE, LARGER

NORMAL

行の上の間隔。separator 0、1、3、5個分。先頭行の上には間隔を描画しません。

fixed_col

bool

False

行の列を等幅にします。

fixed_but

bool

False

行またはそのsubrow内のボタンを等幅にします。

spacerの設定

spacerの設定はspacerの文字列に保存されます。update_spacer() は1回の呼び出しでそのうち一つを変更します。

名前

型

値の範囲

既定値

説明

hsep

str

NONE, SPACER, COLUMN, ALIGNER

NONE

SPACER は間隔を描画します。COLUMN は新しい列を開始します。 ALIGNER は、align_slot() が使う左・中央・右の区分の境界です。

subrow

str

NONE, BEGIN, END

NONE

BEGIN は現在の列の中でsubrowを開始し、END はそれを終了します。

共通の結果キー

このページのすべての関数は、ここで説明する辞書を返します。 Pop-up DialogまたはFloating Panelに対する add_slot()、remove_slot()、move_slot()、 swap_slots() も同じ辞書を返しますが、3つの *_row_refs キーはありません。 transfer_slot() は独自の結果を返し、そのPopup側が before_rows、after_rows、 insertion_position を持ちます。

キー

型

値

status

str

ステータス を参照。

committed

bool

status が "committed" のときだけ True。

pm_uid

str

メニューのUID。

version

int

呼び出し後のメニューのセッション内バージョン。 version_after と同じです。

version_before

int

呼び出し前に読んだバージョン。

version_after

int

呼び出し後に読んだバージョン。

before_order

list[str]

呼び出し前の、保存順のスロットUID。

after_order

list[str] or None

呼び出し後の、保存順のスロットUID。読み戻しに失敗したときは None。

before_rows

list[dict]

呼び出し前の行。形式は 行構造を読む と同じです。

after_rows

list[dict] or None

呼び出し後の行。読み戻しに失敗したときは None。

insertion_position

dict or None

項目の追加または移動が解決した隙間。 Popupの解決済み挿入位置を読む を参照。このページの関数では None。

slots

list[dict]

呼び出しの対象スロット。各要素は uid、status (呼び出しのstatus)、 before、after、reports (常に []) を持ちます。 before と after はスロットの保存値に index と layout_panel を加えたもので、スロットが存在しない側は None です。 どのスロットが対象かは各関数の説明にあります。

side_effects

list[dict]

保存値またはindexが変わった他のスロット。uid、before、 after。

created_uids

list[str]

呼び出し前になく、呼び出し後にあるスロット。保存順。

deleted_uids

list[str]

呼び出し前にあり、呼び出し後にないスロット。

moved_uids

list[str]

indexが変わったスロット。スロットの挿入・削除によるずれも含みます。

structure_changes

list[dict]

実際の行とspacerの変更。対象行の外の整理も含みます。 下記を参照。

expected

dict

呼び出し前に読んだ保存スロット一式。pm_uid と items。書き込み前の検査 を参照。

recovery

str

"not_needed"、"restored"、"unknown" のいずれか。

pending

list

常に []。

diagnostics

list[dict]

問題ごとに1件。code と、共通の診断 および各関数の説明に挙げる詳細を持ちます。

created_row_refs

list[dict]

このページの関数のみ。呼び出し前になく、呼び出し後にある行参照。

deleted_row_refs

list[dict]

このページの関数のみ。呼び出し前にあり、呼び出し後にない行参照。

moved_row_refs

list[dict]

このページの関数のみ。開始indexが変わった行参照。 別の行の変更によるずれも含みます。

structure_changes の要素は次のとおりです。

kind

その他のキー

意味

"rows"

before, after

完全な before_rows と after_rows。両者が異なるときに入ります。

"layout_slot"

uid, before, after

行マーカーまたはspacerの追加・削除・変更・位置のずれ。 before と after は slots と同じ形式です。

"row_ref"

before, after

呼び出しが、マーカーのない先頭行にマーカーを追加しました。before は古い "first_item" 参照、after は新しい "marker" 参照です。行の操作のみ。

ステータス

値は 結果とガード と同じです。

status

意味

validated

dry_run=True で、呼び出しは受理可能です。何も書き込んでいません。

unchanged

保存変更なし。保存済みのスロットがすでに呼び出しを満たしているか、 書き込み後も expected と同じでした。バージョンは変わりません。

committed

保存済みのスロットが変わり、読み戻されました。バージョンが1増えました。

rejected

何も書き込んでいません。diagnostics が原因を示します。

restored_failure

書き込みが例外を送出し、保存済みのスロットを expected のスナップショットへ復元しました。recovery は "restored" です。

unknown

書き込みが例外を送出し、復元にも失敗しました。recovery は "unknown" です。 再試行の前に read_pm() を呼び出してください。

共通の診断

code

原因と追加のキー

row_operation_unsupported

メニューがPop-up DialogでもFloating Panelでもありません。このページのすべての関数 (add_row()、add_panel()、remove_row()、move_row()、 split_row()、join_rows()、update_row()、update_spacer()、 align_slot())が報告します。

stale_version

expected_version が現在のバージョンと異なります。スロットの操作と同じく、 expected (指定したバージョン) と actual (現在のバージョン)。

stale_popup

expected が現在の保存スロット一式と異なります。

row_not_found

row_ref が現在の行のちょうど一つに一致しません。

slot_not_found

UIDがメニューのスロットを一つに特定しません。

slot_edit_conflict

呼び出しが削除または書き換えるスロットを、Slot Editorで編集中です。

panel_row

この呼び出しはLayout Panelの行またはアンカーには使えません。 該当する場合は各関数の説明にあります。

aligner_without_root

変更によって行の最初の ALIGNER が最初の COLUMN より後になり、 揃えの起点が失われます。行が元からその状態でなかった場合だけ報告します。 column_slot_uid、aligner_slot_uid、message。

popup_<operation>_failed

書き込みが例外を送出しました。<operation> は row_add、panel_add、 row_remove、row_move、row_split、row_join、 row_update、spacer_update、slot_alignment のいずれか、 項目の操作では add、remove、move のいずれかです。 exception_type、message。

popup_restore_failed

expected のスナップショットの復元が例外を送出しました。status は "unknown"。exception_type、message。

refresh_failed

書き込み後のエディターの画面更新が例外を送出しました。status は維持されます。 exception_type、message。

popup_readback_failed

呼び出し後の保存状態の読み取りが例外を送出しました。status と recovery は維持されます。exception_type、message。

書き込み前の検査

このページのすべての関数は expected_version、expected、dry_run を受け取ります。

引数

規則

expected_version

None または負でない int。メニューのセッション内バージョン (read_pm()["version"] または結果の version)と異なると、 stale_version で拒否します。bool を含むそれ以外の値は TypeError を送出します。

expected

None、または以前のPopupの結果の expected。通常は同じ呼び出しのdry runが返したものです。 変更せずに渡してください。保存スロット一式を保持するため、バージョンが増えない保存変更も検出します。 異なると stale_popup で拒否します。 絞り込んだ read_pm() の結果、slots の要素、編集したコピーでは代用できません。 JSONの往復後も使えます。マッピングでない値は TypeError を送出します。

dry_run

bool。それ以外の値は TypeError を送出します。True は同じ検査を実行し、validated、unchanged、rejected のいずれかを返します。

dry runは何も書き込みません。UIDもマーカーも作成せず、バージョンも変えず、画面更新もしません。 before_* と after_* の値はどちらも現在の保存状態を表し、作成・削除・移動の一覧は空です。 整理の結果、新しいUID、描画の成功は予測しません。 後の呼び出しは引数を改めて解決し、現在の保存状態を再度検査します。

before = pme.editing.read_pm(pm_uid)
checked = pme.editing.add_row(
    pm_uid, expected_version=before["version"], dry_run=True,
)
if checked["status"] == "validated":
    added = pme.editing.add_row(
        pm_uid, expected_version=checked["version"], expected=checked["expected"],
    )
    print(added["status"], added["after_rows"], added["created_row_refs"])

補足

  • バージョンを増やすのは committed だけで、1回の呼び出しにつき1回です。

  • status="unknown" で committed=False でも、何も変わっていないとは限りません。

  • エディターの画面更新は、unchanged または restored_failure で終わるものを含め、 すべての書き込みの後に実行されます。書き込み前に止まる呼び出し(dry run、拒否、 書き込み前に変更なしと判明した呼び出し)は画面更新しません。

  • 最終の読み戻しが例外を送出すると、after_order と after_rows は None になります。行の読み戻しだけが失敗した場合は after_order が残ります。 このとき作成・削除・移動の一覧は空ですが、何も変わっていないことを意味しません。 再試行の前に読み直してください。

  • 選択、無関係なSlot Editorの編集中の内容、行のクリップボードはそのまま残ります。

  • この呼び出しはPreferencesをディスクへ保存せず、Undoステップも追加しません。

レイアウト行の追加・削除・移動・分割・結合

エディターの Add Row、Remove Row、Move Row、Split、Join Rows コマンドは、 同じ操作を呼び出します。read_pm()["rows"] または直前の結果の after_rows から、 現在の行参照を渡してください。

pme.editing.add_row(pm_uid, *, before_row_ref=None, after_row_ref=None, expected_version=None, expected=None, dry_run=False)

Add Row と同じく、行マーカーと既定のボタンを追加します。

位置は最大一つ指定します。指定しない場合は最後の行の後に追加します。 空のメニューでも同じです。

パラメータ:
  • pm_uid (str) -- Pop-up DialogまたはFloating PanelのUID。

  • before_row_ref (dict or None) -- この行の前に新しい行を挿入します。

  • after_row_ref (dict or None) -- この行の後に新しい行を挿入します。

  • expected_version (int or None) -- 書き込み前の検査 を参照。

  • expected (dict or None) -- 書き込み前の検査 を参照。

  • dry_run (bool) -- 書き込まずに検査して返します。

戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- row_ref が、キーをちょうど kind と空でない文字列の slot_uid だけ持つマッピングでない場合、または expected_version、expected、 dry_run の型が誤っている場合。

  • ValueError -- 両方の位置を指定した場合、row_ref のkindが "marker" でも "first_item" でもない場合、またはメニューUIDが存在しない・無効・ 曖昧な場合。

結果

slots は新しいマーカーと新しいボタンを、この順で持ちます。 created_uids は同じ2つのUIDを並べます。created_row_refs は新しい行を持ちます。

診断

row_operation_unsupported、row_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

added = pme.editing.add_row(pm_uid)
marker_uid, button_uid = added["created_uids"]

補足

  • 新しいボタンは、名前が Button <n> でコマンドのないCommandスロットです。 空のメニューには、文字列が row のマーカーとボタン一つが入ります。

  • 新しい行の設定は Add Row に従います。

    • 末尾への追加(最後の行の後への追加を含む): size は最後の行から取ります。 vspacer も、その行に COLUMN spacerがなければ最後の行から取ります。

    • 行の前: size はその行から取ります。その行が NONE で、その上の行に COLUMN spacerがなければ、新しい行は vspacer="NONE"、それ以外は "NORMAL" です。その行の vspacer は、その行に COLUMN spacerがない限り "NONE" になります。

    • 最後でない行の後: size はその行から取ります。新しい行は vspacer="NONE" です。ただし、その行に COLUMN spacerがある場合は "NORMAL" です。

    • COLUMN spacerを持つ行と、そのすぐ下の行は、この呼び出しで vspacer="NONE" を受け取りません。エディターの行の Spacer メニューも、そこでは NONE を提示しません。そのような行にすでに保存されている NONE は維持されます。

  • before_row_ref がマーカーのない先頭行を指す場合は、まずその行にマーカーを追加し、スロットとその文字列を保ちます。このとき structure_changes に "row_ref" 要素が入ります。after_row_ref ではマーカーを追加しません。

pme.editing.remove_row(pm_uid, row_ref, *, expected_version=None, expected=None, dry_run=False)

行を、そのマーカーと行内の全スロットとともに削除します。

次の行はマーカーと設定を保ちます。最後の行を削除すると、空のメニューになります。

パラメータ:
戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- row_ref が、キーをちょうど kind と空でない文字列の slot_uid だけ持つマッピングでない場合、または expected_version、expected、 dry_run の型が誤っている場合。

  • ValueError -- row_ref のkindが "marker" でも "first_item" でもない場合、またはメニューUIDが存在しない・無効・曖昧な場合。

結果

slots は削除した行の全スロットを持ち、その after は None です。 deleted_row_refs は削除した行を持ちます。

診断

code

原因と追加のキー

slot_edit_conflict

行のスロットをSlot Editorで編集中です。

ほかに row_operation_unsupported、row_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

rows = pme.editing.read_pm(pm_uid)["rows"]
result = pme.editing.remove_row(pm_uid, rows[-1]["row_ref"])

補足

  • Layout Panel行は、アンカーとすべてのヘッダー項目とともに削除されます。 無効な項目と、Header LayoutがOFFの間は非表示の項目も含みます。

  • 隣の行に対する空行やspacerの整理は実行しません。

  • 無関係な編集中の内容、選択、行のクリップボードはそのまま残ります。

pme.editing.move_row(pm_uid, row_ref, *, before_row_ref=None, after_row_ref=None, expected_version=None, expected=None, dry_run=False)

行全体を別の行の前後へ移動します。

before_row_ref と after_row_ref のどちらか一方だけを指定します。

パラメータ:
  • pm_uid (str) -- Pop-up DialogまたはFloating PanelのUID。

  • row_ref (dict) -- 移動する行。

  • before_row_ref (dict or None) -- この行の前へ移動します。

  • after_row_ref (dict or None) -- この行の後へ移動します。

  • expected_version (int or None) -- 書き込み前の検査 を参照。

  • expected (dict or None) -- 書き込み前の検査 を参照。

  • dry_run (bool) -- 書き込まずに検査して返します。

戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- row_ref が、キーをちょうど kind と空でない文字列の slot_uid だけ持つマッピングでない場合、または expected_version、expected、 dry_run の型が誤っている場合。

  • ValueError -- 位置を指定しないか両方を指定した場合、row_ref のkindが "marker" でも "first_item" でもない場合、またはメニューUIDが存在しない・ 無効・曖昧な場合。

結果

slots は移動した行のスロットを持ちます。moved_row_refs は開始indexが変わったすべての行を並べます。

ステータス

row_ref が移動先の行自身を指す場合、または行がすでにその位置にある場合は unchanged です。この場合はdry runのステータスも同じです。マーカーを追加せず、 バージョンも変わらず、エディターの画面更新もしません。

診断

row_operation_unsupported、row_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

rows = pme.editing.read_pm(pm_uid)["rows"]
result = pme.editing.move_row(
    pm_uid, rows[-1]["row_ref"], before_row_ref=rows[0]["row_ref"],
)

補足

  • 行のスロット、設定、UIDは、Layout Panel行のヘッダー項目を含めて一緒に移動します。

  • 項目の移動で行う整理は実行しません。

  • マーカーのない先頭行は、移動するとき、または before_row_ref の対象になったときにマーカーを受け取ります。このとき structure_changes に "row_ref" 要素が入ります。

pme.editing.split_row(pm_uid, row_ref, *, before_uid, expected_version=None, expected=None, dry_run=False)

通常の行を分割し、その行のスロットの一つから新しい行を始めます。

before_uid で指定したスロットと、行内でそれより後のスロットは、既定の設定を持つ新しい行へ移ります。ボタンは追加しません。

パラメータ:
  • pm_uid (str) -- Pop-up DialogまたはFloating PanelのUID。

  • row_ref (dict) -- 分割する行。

  • before_uid (str) -- 行のマーカー以外のスロット。項目または spacer。

  • expected_version (int or None) -- 書き込み前の検査 を参照。

  • expected (dict or None) -- 書き込み前の検査 を参照。

  • dry_run (bool) -- 書き込まずに検査して返します。

戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- before_uid が空でない文字列でない場合、row_ref がキーをちょうど kind と空でない文字列の slot_uid だけ持つマッピングでない場合、 または expected_version、expected、dry_run の型が誤っている場合。

  • ValueError -- row_ref のkindが "marker" でも "first_item" でもない場合、またはメニューUIDが存在しない・無効・曖昧な場合。

結果

slots は行のスロットと新しいマーカーを持ちます。created_row_refs は新しい行を持ちます。

診断

code

原因と追加のキー

panel_row

行がLayout Panel行です。

split_position_not_found

before_uid が行内にないか、行のマーカーです。

aligner_without_root

新しい行で、最初の ALIGNER が最初の COLUMN より後になります。column_slot_uid、aligner_slot_uid、message。

ほかに row_operation_unsupported、row_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

row = pme.editing.read_pm(pm_uid)["rows"][0]
result = pme.editing.split_row(
    pm_uid, row["row_ref"], before_uid=row["slot_uids"][-1],
)

補足

  • 元の行はマーカーと設定を保ちます。新しいマーカーは既定の設定です。

  • Split と同じく、before_uid の直前のspacerを一つ削除します。 それ以外のスロットとすべてのUIDは残ります。

  • before_uid に先頭項目を指定すると、元の行は空になります。 マーカーのない先頭行は先にマーカーを受け取り、このとき structure_changes に "row_ref" 要素が入ります。

  • before_uid で指定したspacerは、新しい行の先頭に残ります。 ALIGNER spacer自体を指定すると、揃えの起点が保たれます。

  • COLUMN または ALIGNER spacerを持つ行も、 aligner_without_root に該当しない限り受け付けます。すでにその状態の行は修復しません。

  • エディターは先頭項目に Split を表示しません。この関数は受け付けます。

pme.editing.join_rows(pm_uid, first_row_ref, second_row_ref, *, expected_version=None, expected=None, dry_run=False)

隣接する2つの通常の行を結合します。

second_row_ref は、最初の行が終わる位置から始まっている必要があります。

パラメータ:
  • pm_uid (str) -- Pop-up DialogまたはFloating PanelのUID。

  • first_row_ref (dict) -- 上の行。マーカーと設定を保ちます。

  • second_row_ref (dict) -- そのすぐ下の行。

  • expected_version (int or None) -- 書き込み前の検査 を参照。

  • expected (dict or None) -- 書き込み前の検査 を参照。

  • dry_run (bool) -- 書き込まずに検査して返します。

戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- row_ref が、キーをちょうど kind と空でない文字列の slot_uid だけ持つマッピングでない場合、または expected_version、expected、 dry_run の型が誤っている場合。

  • ValueError -- row_ref のkindが "marker" でも "first_item" でもない場合、またはメニューUIDが存在しない・無効・曖昧な場合。

結果

slots は両方の行のスロットを持ちます。deleted_row_refs は 2番目の行を持ちます。

診断

code

原因と追加のキー

panel_row

どちらかの行がLayout Panel行です。

rows_not_adjacent

間に別の行がある、順序が逆である、または両方の参照が同じ行を指しています。

ほかに row_operation_unsupported、row_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

rows = pme.editing.read_pm(pm_uid)["rows"]
result = pme.editing.join_rows(pm_uid, rows[0]["row_ref"], rows[1]["row_ref"])

補足

  • 2番目の行のマーカーと、2番目の行で hsep が COLUMN または ALIGNER のspacerをすべて削除します。それ以外のspacerと項目は残ります。

行設定・間隔・揃えを変更する

エディターの行設定、spacer、揃えのコマンドは、同じ操作を呼び出します。 呼び出し側は行やspacerの文字列を組み立てません。

pme.editing.update_row(pm_uid, row_ref, changes, *, scope='row', expected_version=None, expected=None, dry_run=False)

1つの行、または行のグループの設定を変更します。

すでに要求した値になっている設定は書き込みません。何も異ならない場合、 結果は unchanged です。

パラメータ:
  • pm_uid (str) -- Pop-up DialogまたはFloating PanelのUID。

  • row_ref (dict or None) -- 行。None は scope="all_rows" のときだけ。

  • changes (dict) -- 行設定の名前と新しい値のマッピング。部分指定で、 指定しない設定は値を保ちます。名前と値は 行設定 にあります。

  • scope (str) -- "row"、"aligned_rows"、"all_rows" のいずれか。 下の「対象範囲」を参照。

  • expected_version (int or None) -- 書き込み前の検査 を参照。

  • expected (dict or None) -- 書き込み前の検査 を参照。

  • dry_run (bool) -- 書き込まずに検査して返します。

戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- changes がマッピングでない場合、値のPythonの型が誤っている場合 (fixed_col と fixed_but は bool、それ以外は str)、row_ref が他のscopeで None であるか、キーをちょうど kind と空でない文字列の slot_uid だけ持つマッピングでない場合、または expected_version、expected、dry_run の型が誤っている場合。

  • ValueError -- 名前が行設定でない場合、値がその設定の値の範囲にない場合、 scope が3つの値のいずれでもない場合、row_ref のkindが "marker" でも "first_item" でもない場合、またはメニューUIDが存在しない・無効・ 曖昧な場合。

対象範囲

scope

変更する行

row

row_ref で指定した行。

aligned_rows

vspacer="NONE" でつながる、その行を含む行のグループ。上方向へは、 行が vspacer="NONE" を持つ間たどるため、グループの最上行を含みます。 下方向へは、次の行が vspacer="NONE" を持つ間たどります。

all_rows

マーカーのない先頭行を含むすべての行。row_ref は None でもかまいません。空のメニューは空のままで、unchanged を返します。

結果

slots は対象範囲のすべての行のスロットを持ちます。

診断

code

原因と追加のキー

panel_row

Layout Panel行に対する scope="row" で、vspacer 以外の設定を指定しました。fields にその名前が入ります。

row_fields_skipped

拒否ではありません。広い対象範囲で、Layout Panel行の vspacer 以外の設定を変更しませんでした。row_ref、fields。

slot_edit_conflict

書き換えるマーカーをSlot Editorで編集中です。

ほかに row_operation_unsupported、row_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

before = pme.editing.read_pm(pm_uid)
row_ref = before["rows"][0]["row_ref"]
checked = pme.editing.update_row(
    pm_uid, row_ref, {"size": "LARGE", "fixed_but": True},
    expected_version=before["version"], dry_run=True,
)
if checked["status"] == "validated":
    changed = pme.editing.update_row(
        pm_uid, row_ref, {"size": "LARGE", "fixed_but": True},
        expected_version=checked["version"], expected=checked["expected"],
    )
    print(changed["status"], changed["after_rows"], changed["structure_changes"])

補足

  • Layout Panel行は vspacer だけを受け付けます。

  • scope="all_rows" では、行自身またはその上の行に COLUMN spacerがある場合、 vspacer="NONE" をその行に "NORMAL" として書き込みます。

  • 値はこの補正の後で比較します。変更のない呼び出しは保存文字列、UID、 バージョンをそのまま保ち、画面更新もしません。

  • マーカーのない先頭行は、その設定のいずれかが変わるときだけマーカーを受け取ります。 先頭項目はコマンドの文字列を保ちます。このとき structure_changes に "row_ref" 要素が入ります。

  • 変更したマーカーはエディターのencodeで書き込まれるため、そのマーカーの未知の queryキーが正規化または削除される場合があります。他の保存値は変わりません。

  • align は行設定です。align_slot() による項目の配置ではありません。

pme.editing.update_spacer(pm_uid, *, slot_uid=None, before_uid=None, after_uid=None, prop, value, expected_version=None, expected=None, dry_run=False)

spacerの設定を一つ変更します。必要ならspacerを作成します。

対象をちょうど一つ指定します。既存のspacerなら slot_uid、内容スロットの隣のspacerなら before_uid / after_uid です。整理の結果が変更の順序に依存するため、 1回の呼び出しで変更する設定は一つです。

パラメータ:
  • pm_uid (str) -- Pop-up DialogまたはFloating PanelのUID。

  • slot_uid (str or None) -- 既存のspacer。先頭、末尾、項目の間のいずれでもかまいません。

  • before_uid (str or None) -- 内容スロット。同じ行でその直前にあるspacerを変更します。 ない場合は、そこにspacerを作成します。

  • after_uid (str or None) -- 内容スロット。同じ行でその直後にあるspacerを変更または作成します。

  • prop (str) -- "hsep" または "subrow"。

  • value (str) -- prop の値。 spacerの設定 を参照。

  • expected_version (int or None) -- 書き込み前の検査 を参照。

  • expected (dict or None) -- 書き込み前の検査 を参照。

  • dry_run (bool) -- 書き込まずに検査して返します。

戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- value が文字列でない場合、対象のUIDが空でない文字列でない場合、 または expected_version、expected、dry_run の型が誤っている場合。

  • ValueError -- prop がspacerの設定でない場合、value がその値の範囲にない場合、対象がちょうど一つでない場合、またはメニューUIDが存在しない・無効・曖昧な場合。

結果

slots は、設定が変わるspacer、対象のspacer、作成したspacerを持ちます。

診断

code

原因と追加のキー

spacer_required

slot_uid が行マーカーまたは内容スロットを指しています。

content_slot_required

before_uid または after_uid がspacerまたは行マーカーを指しています。

panel_row

Layout Panel行で、対象がアンカーである、prop が subrow である、または値が hsep="COLUMN" です。

aligner_without_root

共通の診断 を参照。

slot_edit_conflict

書き換えまたは削除するspacerかマーカーをSlot Editorで編集中です。

ほかに row_operation_unsupported、slot_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

result = pme.editing.update_spacer(
    pm_uid, after_uid=slot_uid, prop="hsep", value="SPACER",
)

補足

  • 隣接するspacerはその場で更新します。use_spacer=True の add_slot() は、 代わりにspacerを挿入します。

  • 隣のスロットは同じ行にある必要があります。先頭と末尾の位置も受け付けます。 マーカーのない先頭行の先頭項目の前にspacerを作成しても、行マーカーは追加しません。

  • すべての設定が NONE になったspacerは削除します。隣接するspacerがないときの NONE は unchanged を返します。

  • subrow="END" を持つspacerに hsep="COLUMN" を設定すると、その END を解除します。

  • hsep="COLUMN" は、この行と次の行が vspacer="NONE" を持つ場合、それぞれに vspacer="NORMAL" も設定します。先頭行は変更しません。

  • 行で唯一の COLUMN spacerを別の hsep に変えると、行内の全spacerの subrow を解除します。

  • subrow を BEGIN から NONE に変えると、行内の次の END も解除します。ただし、その前に BEGIN または COLUMN がある場合は解除しません。

  • subrowに COLUMN spacerは必須ではありません。

  • Layout Panelのヘッダーにあるspacerは、Header LayoutがOFFでも変更できます。 この変更でHeader LayoutはONになりません。

pme.editing.align_slot(pm_uid, slot_uid, alignment, *, expected_version=None, expected=None, dry_run=False)

項目を行の左・中央・右の区分に配置します。

エディターの揃えボタンと同じく、ALIGNER spacerを移動または作成します。 行の align 設定は書き込みません。

パラメータ:
  • pm_uid (str) -- Pop-up DialogまたはFloating PanelのUID。

  • slot_uid (str) -- 内容スロット。

  • alignment (str or None) -- "LEFT"、"CENTER"、"RIGHT"、または行の外側の揃え境界を解除する None。

  • expected_version (int or None) -- 書き込み前の検査 を参照。

  • expected (dict or None) -- 書き込み前の検査 を参照。

  • dry_run (bool) -- 書き込まずに検査して返します。

戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- slot_uid が空でない文字列でない場合、または expected_version、expected、dry_run の型が誤っている場合。

  • ValueError -- alignment が4つの値のいずれでもない場合、またはメニュー UIDが存在しない・無効・曖昧な場合。

結果

slots は項目を持ちます。作成・移動・変更・削除したspacerは created_uids、deleted_uids、side_effects、 structure_changes に現れます。

診断

code

原因と追加のキー

content_slot_required

slot_uid が行マーカーまたはspacerを指しています。

panel_row

slot_uid がLayout Panel アンカーを指しています。

item_in_column_region

行に COLUMN spacerがあり、項目が最初の COLUMN より後にあります。column_slot_uid、message。

aligners_after_column

行の最初の COLUMN より後に ALIGNER があります。message。

popup_slot_alignment_failed

保存データから変更を計算できませんでした。何も書き込まず、recovery は "not_needed" です。tracebackはコンソールに出力されます。exception_type、message。

aligner_without_root

共通の診断 を参照。

slot_edit_conflict

移動・書き換え・削除するスロットをSlot Editorで編集中です。

ほかに row_operation_unsupported、slot_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

result = pme.editing.align_slot(pm_uid, slot_uid, "RIGHT")

補足

  • COLUMN spacerのある行では、項目は最初の COLUMN より前にある必要があり、 その後に ALIGNER があってはなりません。それ以外の場合は、 update_spacer() で境界を編集します。この制限は align_slot のもので、保存レイアウトの制限ではありません。

  • None は、項目が COLUMN より後にある場合も、行の最初と最後の ALIGNER (最大2つ) を削除します。インポートしたデータにある、それ以外の ALIGNER spacerは残ります。

  • 隣接するspacerは、その後エディターの規則で統合されます。

  • Layout Panelのヘッダーの揃えは、Header LayoutがOFFでも変更できます。 この変更でHeader LayoutはONになりません。

Layout Panelを作成し、ヘッダーを編集する

Layout Panelは、Pop-up DialogまたはFloating Panelの折りたたみ可能な区画です。1行を占めます。 アンカーはMenuスロットで、その参照先メニューがPanelの本文を提供します。同じ行でアンカーより後のスロットがPanel ヘッダーになります。Panelのアンカーとヘッダーは、行とともに移動・削除されます (move_row()、remove_row())。アンカーを単独の項目として削除・移動・ 交換することはできません(panel_row)。Layout Panel行は分割も結合もできません。

pme.editing.add_panel(pm_uid, *, before_row_ref=None, after_row_ref=None, expected_version=None, expected=None, dry_run=False)

Add Panel と同じく、既定のLayout Panel アンカーを持つ行を追加します。

位置は最大一つ指定します。指定しない場合は最後の行の後に追加します。 空のメニューでも同じです。

パラメータ:
  • pm_uid (str) -- Pop-up DialogまたはFloating PanelのUID。

  • before_row_ref (dict or None) -- この行の前に新しい行を挿入します。

  • after_row_ref (dict or None) -- この行の後に新しい行を挿入します。

  • expected_version (int or None) -- 書き込み前の検査 を参照。

  • expected (dict or None) -- 書き込み前の検査 を参照。

  • dry_run (bool) -- 書き込まずに検査して返します。

戻り値:

共通の結果キー で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- row_ref が、キーをちょうど kind と空でない文字列の slot_uid だけ持つマッピングでない場合、または expected_version、expected、 dry_run の型が誤っている場合。

  • ValueError -- 両方の位置を指定した場合、row_ref のkindが "marker" でも "first_item" でもない場合、またはメニューUIDが存在しない・無効・ 曖昧な場合。

結果

slots はアンカーを持ちます。created_uids は新しいマーカーとアンカーを並べます。created_row_refs は新しい行を持ちます。

診断

code

原因と追加のキー

layout_panel_unavailable

Blenderが4.2より古いか、UILayout.panel がありません。 dry runが結果を返す前に検査します。

ほかに row_operation_unsupported、row_not_found、stale_version、 stale_popup と、共通の診断 の書き込み失敗。

例

added = pme.editing.add_panel(pm_uid)
anchor_uid = added["slots"][0]["uid"]

補足

  • アンカーは、名前が Panel で、参照先・アイコン・ボタンの背景色を持たない Menuスロットです。layout_panel は新しい idname (layout_panel_<id>) を持ち、default_closed と use_header_layout は False です。ヘッダーは空です。

  • 新しい行の size と vspacer は、add_row() と同じく Add Row に従います。そのうえで、新しい行とその次の行が vspacer="NONE" を持つ場合は vspacer="NORMAL" にします。

  • before_row_ref がマーカーのない先頭行を指す場合は、その行にマーカーを追加し、スロットとその文字列を保ちます。

  • アンカーの名前と menu_target_uid は、アンカーのUIDを使って update_slots() で設定します。menu_target_uid は、名前と同じ編集か、 それより前に指定してください。本文のメニューがないアンカーへの編集は拒否されます(後述の「Panel設定」を参照)。layout_panel 辞書や行マーカーは手で組み立てません。

Panel設定

Panel設定は、アンカーに対する update_slots() の項目 layout_panel_default_closed と layout_panel_use_header_layout です。 どちらも bool だけを受け付けます。

  • update_slots() はSlot Editorと同じ方法でアンカーを保存し、Slot Editorは Menuスロットを本文のメニューがある場合だけ保存します。新しい add_panel() のアンカーのように本文のメニューがないアンカーでは、どの項目を指定しても、すべての編集が拒否されます。 スロットの要素は、エディターのメッセージ "Select the item" を伴う editor_validation を持ちます。menu_target_uid を同じ編集か、それより前の編集で指定してください。 エディターのアンカーメニューは、本文のメニューがなくても Default Closed と Header Layout を変更します。pme.editing の関数はどれも変更しません。

  • ヘッダーが空の状態で layout_panel_use_header_layout をONにすると、ヘッダーにボタンを一つ追加します。

  • 後で空になったヘッダーは空のままです。再度の保存、名前の変更、変わらない True では、ボタンを追加しません。

  • OFFにしても、保存済みのヘッダー項目はすべて残ります。

  • 変更のある保存では、enabled=True を含むエディターのアンカー正規化を適用します。 enabled は update_slots() の項目ではありません。

  • update_slots() は編集を1件ずつ順に保存します。失敗しても、先に保存した編集は元に戻りません。

ヘッダーの位置

add_slot()、move_slot()、transfer_slot() は、行の panel["anchor_uid"] である header_anchor_uid と、次の位置のちょうど一つを組み合わせて、 項目をPanel ヘッダーに配置します。

位置

意味

before_uid / after_uid

そのヘッダーの保存済みスロットの前または後。spacerも位置として数えます。

edge="START"

アンカーの直後。

edge="END"

ヘッダーの末尾。ヘッダーが空のときはedgeを使います。

  • header_anchor_uid に対して位置を指定しない、または複数指定した場合、edge が "START" でも "END" でもない場合、header_anchor_uid を row_ref または new_row と併用した場合は ValueError を送出します。

  • Layout Panel行の row_ref は、そのヘッダーを意味しません。panel_row で拒否されます。

  • 通常の行または別のヘッダーからヘッダーへの move_slot() には header_anchor_uid が必要です。ない場合、結果は header_role_required です。同じヘッダー内での before_uid / after_uid による移動には不要です。ヘッダーへの transfer_slot() には常に必要です。

  • ヘッダー内での before_uid / after_uid による add_slot() は、 Header LayoutがONの間は header_anchor_uid なしで動作し、 OFFの間は header_anchor_uid が必要です。

  • swap_slots() は2つのUIDだけを受け取ります。通常の項目とヘッダー項目、 または別々のヘッダーの項目を、整理なしで交換します。

  • アンカーを別のヘッダーへ移動することはできません。ヘッダー内にすでに保存されている 2つ目のアンカーは remove_slot() で削除できます。それを挿入する手段はありません。

  • ヘッダー項目は、Header LayoutがOFFの間も追加・移動・削除できます。呼び出しは Header LayoutをONにしません。このとき結果の diagnostics に、anchor_uid を伴う header_layout_disabled が入ります。Preferencesはこれらの項目を編集用に表示し、実行時のメニューは非表示にします。

  • エディターでは、アンカーのメニューに空のヘッダー用の Add があり、Move はヘッダーの先頭と末尾を提示し、Ctrl+Alt+クリックでヘッダー項目を一つ削除し、 Delete Inactive Header はHeader LayoutがOFFのヘッダーの全項目を削除します。

code

原因と追加のキー

header_layout_disabled

拒否ではありません。そのヘッダーのHeader LayoutがOFFです。anchor_uid。

panel_anchor_not_found

header_anchor_uid がLayout Panel アンカーを指していません。

header_target_mismatch

before_uid / after_uid がそのヘッダーのスロットではありません。

header_role_required

header_anchor_uid なしでヘッダーへ移動または転送しました。

panel_row

挿入先がヘッダーの位置以外のLayout Panel行にある、 header_anchor_uid なしの add_slot() がHeader LayoutがOFFのヘッダーを対象にした、または移動する項目がアンカーです。

before = pme.editing.read_pm(pm_uid)
panel = next(row["panel"] for row in before["rows"] if row["panel"])
anchor_uid = panel["anchor_uid"]
checked = pme.editing.move_slot(
    pm_uid, slot_uid, header_anchor_uid=anchor_uid, edge="END",
    expected_version=before["version"], dry_run=True,
)
if checked["status"] == "validated":
    moved = pme.editing.move_slot(
        pm_uid, slot_uid, header_anchor_uid=anchor_uid, edge="END",
        expected_version=checked["version"], expected=checked["expected"],
    )
    print(moved["status"], moved["diagnostics"], moved["after_rows"])

行内の項目の位置

Pop-up DialogまたはFloating Panelでは、add_slot()、move_slot()、 transfer_slot() は次の挿入先の形式のいずれか一つを受け取ります。

引数

関数

挿入先

before_uid / after_uid

3つすべて

その保存済みスロットの直前または直後。

row_ref と edge="START" / "END"

move_slot、transfer_slot

その行の左端(マーカーの後)または右端。行は空でもかまいません。Layout Panel行は panel_row で拒否されます。

new_row="END"

move_slot、transfer_slot

新しい最後の行。

header_anchor_uid と位置

3つすべて

Panel ヘッダー。ヘッダーの位置 を参照。

  • 受け付ける形式はちょうど一つです。形式を混在させると ValueError を送出します。 new_row はboolではなく、文字列 "END" です。

  • use_spacer は bool で、既定値は False です。Preferencesの設定は適用されません。

  • before_uid / after_uid は、基準スロットの保存indexを使います。マーカーと spacerは飛ばしません。AとBの間にspacerがあると、after_uid=A と before_uid=B は別の位置です。

  • move_slot() は、すべての形式でエディターの空行とspacerの整理を実行します。 移動した項目はUIDと保存値を保ち、選択と開いているSlot Editorの編集中の内容は、 それぞれの項目に結び付いたままです。

  • すでに満たされている before_uid / after_uid の移動は、自分自身を基準にした場合を含め、 spacer、整理、バージョンの変更、画面更新なしで unchanged を返します。 すでに満たされている行端への移動でも、エディターの画面更新は実行される場合があります。 行の唯一の項目を新しい行へ移動すると、整理の後で unchanged になる場合があります。

  • swap_slots() は2つの項目をUIDと保存値ごと交換し、 空行やspacerの整理はしません。

  • エディターの Move の選択画面は、同じ前後の位置、交換、行端、Add Row を提示します。

before = pme.editing.read_pm(pm_uid)
row_ref = before["rows"][-1]["row_ref"]
checked = pme.editing.move_slot(
    pm_uid, slot_uid, row_ref=row_ref, edge="END",
    expected_version=before["version"], dry_run=True,
)
if checked["status"] == "validated":
    result = pme.editing.move_slot(
        pm_uid, slot_uid, row_ref=row_ref, edge="END",
        expected_version=checked["version"], expected=checked["expected"],
    )
    print(result["status"], result["after_rows"], result["structure_changes"])