レイアウトの行とパネル¶
Pop-up Dialog(DIALOG)とFloating Panel(FPANEL)は、行、spacer、Layout Panelをメニューの保存リストにスロットとして保存します。
このページの関数は、そのリストを行として読み取り、行、spacer、項目の揃え、Layout Panelを変更します。
単独の項目の追加・削除・移動・編集は スロット、Modeや幅などのメニュー設定は
メニューの種類ごとの設定 にあります。
関数 |
用途 |
|---|---|
行を |
|
既定のボタンを持つ行を追加します。 |
|
Layout Panelを持つ行を追加します。 |
|
行とその中身をすべて削除します。 |
|
行を別の行の前後へ移動します。 |
|
行を、その行のスロットの一つの直前で分割します。 |
|
隣接する2行を結合します。 |
|
行設定を変更します。 |
|
spacerの設定を一つ変更します。必要ならspacerを作成します。 |
|
項目を行の左・中央・右の区分に配置します。 |
保存されるレイアウト¶
保存リストは、左から右、上から下の順に読みます。レイアウトを担うスロットは3種類です。
スロット |
保存形式 |
意味 |
|---|---|---|
行マーカー |
|
行を開始します。この文字列に行設定が入ります。 |
spacer |
|
行内の間隔、列境界、揃え境界、subrow境界。 この文字列にspacerの設定が入ります。 |
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の修復、バージョンの初期化、レイアウトの変更を行いません。
各行は次の辞書です。
キー |
型 |
値 |
|---|---|---|
|
dict |
行への参照。行参照 を参照。 |
|
list[str] |
行内の全スロットのUID。保存順で、マーカーを含みます。 |
|
bool |
マーカーのない先頭行では |
|
str or None |
マーカーの保存文字列。マーカーがなければ |
|
dict |
名前ごとの行設定。行設定 を参照。 保存文字列にない名前は既定値です。マーカーのない行はすべて既定値で、 先頭項目の文字列を行設定として読みません。 |
|
list[str] |
保存文字列にない設定名。マーカーのない行ではすべての名前。 |
|
list[dict] |
保存文字列を解析できないときは、 |
|
list[dict] |
行内のspacerごとに1件、保存順。下記を参照。 |
|
dict or None |
行のLayout Panel、または |
spacerの要素は次のとおりです。
キー |
型 |
値 |
|---|---|---|
|
str |
spacerのUID。 |
|
str |
spacerの保存文字列。 |
|
dict |
|
|
list[str] |
保存文字列にない設定名。 |
|
list[dict] |
行と同じ。 |
panel の値は次のとおりです。
キー |
型 |
値 |
|---|---|---|
|
str |
アンカーのUID。行内で最初のLayout Panel アンカーです。 |
|
dict |
アンカーのオプションを |
|
any |
その読み取りを行う前の、保存済みの |
|
bool |
アンカーに保存済みの |
|
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() は次の名前と値を受け付けます。
名前 |
型 |
値の範囲 |
既定値 |
説明 |
|---|---|---|---|---|
|
str |
|
|
行に |
|
str |
|
|
ボタンの高さ。通常の1倍、1.25倍、1.5倍。 |
|
str |
|
|
行の上の間隔。separator 0、1、3、5個分。先頭行の上には間隔を描画しません。 |
|
bool |
|
行の列を等幅にします。 |
|
|
bool |
|
行またはそのsubrow内のボタンを等幅にします。 |
spacerの設定¶
spacerの設定はspacerの文字列に保存されます。update_spacer() は1回の呼び出しでそのうち一つを変更します。
名前 |
型 |
値の範囲 |
既定値 |
説明 |
|---|---|---|---|---|
|
str |
|
|
|
|
str |
|
|
|
共通の結果キー¶
このページのすべての関数は、ここで説明する辞書を返します。
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 を持ちます。
キー |
型 |
値 |
|---|---|---|
|
str |
ステータス を参照。 |
|
bool |
|
|
str |
メニューのUID。 |
|
int |
呼び出し後のメニューのセッション内バージョン。
|
|
int |
呼び出し前に読んだバージョン。 |
|
int |
呼び出し後に読んだバージョン。 |
|
list[str] |
呼び出し前の、保存順のスロットUID。 |
|
list[str] or None |
呼び出し後の、保存順のスロットUID。読み戻しに失敗したときは
|
|
list[dict] |
呼び出し前の行。形式は 行構造を読む と同じです。 |
|
list[dict] or None |
呼び出し後の行。読み戻しに失敗したときは |
|
dict or None |
項目の追加または移動が解決した隙間。
Popupの解決済み挿入位置を読む を参照。このページの関数では
|
|
list[dict] |
呼び出しの対象スロット。各要素は |
|
list[dict] |
保存値またはindexが変わった他のスロット。 |
|
list[str] |
呼び出し前になく、呼び出し後にあるスロット。保存順。 |
|
list[str] |
呼び出し前にあり、呼び出し後にないスロット。 |
|
list[str] |
indexが変わったスロット。スロットの挿入・削除によるずれも含みます。 |
|
list[dict] |
実際の行とspacerの変更。対象行の外の整理も含みます。 下記を参照。 |
|
dict |
呼び出し前に読んだ保存スロット一式。 |
|
str |
|
|
list |
常に |
|
list[dict] |
問題ごとに1件。 |
|
list[dict] |
このページの関数のみ。呼び出し前になく、呼び出し後にある行参照。 |
|
list[dict] |
このページの関数のみ。呼び出し前にあり、呼び出し後にない行参照。 |
|
list[dict] |
このページの関数のみ。開始indexが変わった行参照。 別の行の変更によるずれも含みます。 |
structure_changes の要素は次のとおりです。
|
その他のキー |
意味 |
|---|---|---|
|
|
完全な |
|
|
行マーカーまたはspacerの追加・削除・変更・位置のずれ。
|
|
|
呼び出しが、マーカーのない先頭行にマーカーを追加しました。 |
ステータス¶
値は 結果とガード と同じです。
|
意味 |
|---|---|
|
|
|
保存変更なし。保存済みのスロットがすでに呼び出しを満たしているか、
書き込み後も |
|
保存済みのスロットが変わり、読み戻されました。バージョンが1増えました。 |
|
何も書き込んでいません。 |
|
書き込みが例外を送出し、保存済みのスロットを |
|
書き込みが例外を送出し、復元にも失敗しました。 |
共通の診断¶
|
原因と追加のキー |
|---|---|
|
メニューがPop-up DialogでもFloating Panelでもありません。このページのすべての関数
( |
|
|
|
|
|
|
|
UIDがメニューのスロットを一つに特定しません。 |
|
呼び出しが削除または書き換えるスロットを、Slot Editorで編集中です。 |
|
この呼び出しはLayout Panelの行またはアンカーには使えません。 該当する場合は各関数の説明にあります。 |
|
変更によって行の最初の |
|
書き込みが例外を送出しました。 |
|
|
|
書き込み後のエディターの画面更新が例外を送出しました。 |
|
呼び出し後の保存状態の読み取りが例外を送出しました。 |
書き込み前の検査¶
このページのすべての関数は expected_version、expected、dry_run を受け取ります。
引数 |
規則 |
|---|---|
|
|
|
|
|
|
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 と同じく、行マーカーと既定のボタンを追加します。
位置は最大一つ指定します。指定しない場合は最後の行の後に追加します。 空のメニューでも同じです。
- パラメータ:
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
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も、その行にCOLUMNspacerがなければ最後の行から取ります。行の前:
sizeはその行から取ります。その行がNONEで、その上の行にCOLUMNspacerがなければ、新しい行はvspacer="NONE"、それ以外は"NORMAL"です。その行のvspacerは、その行にCOLUMNspacerがない限り"NONE"になります。最後でない行の後:
sizeはその行から取ります。新しい行はvspacer="NONE"です。ただし、その行にCOLUMNspacerがある場合は"NORMAL"です。COLUMNspacerを持つ行と、そのすぐ下の行は、この呼び出しで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)¶
行を、そのマーカーと行内の全スロットとともに削除します。
次の行はマーカーと設定を保ちます。最後の行を削除すると、空のメニューになります。
- パラメータ:
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
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のどちらか一方だけを指定します。- パラメータ:
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
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で指定したスロットと、行内でそれより後のスロットは、既定の設定を持つ新しい行へ移ります。ボタンは追加しません。- パラメータ:
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
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_foundbefore_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は、新しい行の先頭に残ります。ALIGNERspacer自体を指定すると、揃えの起点が保たれます。COLUMNまたはALIGNERspacerを持つ行も、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は、最初の行が終わる位置から始まっている必要があります。- パラメータ:
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
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です。- パラメータ:
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
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変更する行
rowrow_refで指定した行。aligned_rowsvspacer="NONE"でつながる、その行を含む行のグループ。上方向へは、 行がvspacer="NONE"を持つ間たどるため、グループの最上行を含みます。 下方向へは、次の行がvspacer="NONE"を持つ間たどります。all_rowsマーカーのない先頭行を含むすべての行。
row_refはNoneでもかまいません。空のメニューは空のままで、unchangedを返します。結果
slotsは対象範囲のすべての行のスロットを持ちます。診断
code原因と追加のキー
panel_rowLayout 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"では、行自身またはその上の行にCOLUMNspacerがある場合、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"。dry_run (bool) -- 書き込まずに検査して返します。
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
valueが文字列でない場合、対象のUIDが空でない文字列でない場合、 またはexpected_version、expected、dry_runの型が誤っている場合。ValueError --
propがspacerの設定でない場合、valueがその値の範囲にない場合、対象がちょうど一つでない場合、またはメニューUIDが存在しない・無効・曖昧な場合。
結果
slotsは、設定が変わるspacer、対象のspacer、作成したspacerを持ちます。診断
code原因と追加のキー
spacer_requiredslot_uidが行マーカーまたは内容スロットを指しています。content_slot_requiredbefore_uidまたはafter_uidがspacerまたは行マーカーを指しています。panel_rowLayout 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"も設定します。先頭行は変更しません。行で唯一の
COLUMNspacerを別のhsepに変えると、行内の全spacerのsubrowを解除します。subrowをBEGINからNONEに変えると、行内の次のENDも解除します。ただし、その前にBEGINまたはCOLUMNがある場合は解除しません。subrowに
COLUMNspacerは必須ではありません。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)¶
項目を行の左・中央・右の区分に配置します。
エディターの揃えボタンと同じく、
ALIGNERspacerを移動または作成します。 行のalign設定は書き込みません。- パラメータ:
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
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_requiredslot_uidが行マーカーまたはspacerを指しています。panel_rowslot_uidがLayout Panel アンカーを指しています。item_in_column_region行に
COLUMNspacerがあり、項目が最初の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")
補足
COLUMNspacerのある行では、項目は最初のCOLUMNより前にある必要があり、 その後にALIGNERがあってはなりません。それ以外の場合は、update_spacer()で境界を編集します。この制限はalign_slotのもので、保存レイアウトの制限ではありません。Noneは、項目がCOLUMNより後にある場合も、行の最初と最後のALIGNER(最大2つ) を削除します。インポートしたデータにある、それ以外のALIGNERspacerは残ります。隣接する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 アンカーを持つ行を追加します。
位置は最大一つ指定します。指定しない場合は最後の行の後に追加します。 空のメニューでも同じです。
- パラメータ:
- 戻り値:
共通の結果キー で説明する結果。
- 戻り値の型:
- 例外:
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_unavailableBlenderが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 ヘッダーに配置します。
位置 |
意味 |
|---|---|
|
そのヘッダーの保存済みスロットの前または後。spacerも位置として数えます。 |
|
アンカーの直後。 |
|
ヘッダーの末尾。ヘッダーが空のときは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のヘッダーの全項目を削除します。
|
原因と追加のキー |
|---|---|
|
拒否ではありません。そのヘッダーのHeader LayoutがOFFです。 |
|
|
|
|
|
|
|
挿入先がヘッダーの位置以外のLayout Panel行にある、
|
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() は次の挿入先の形式のいずれか一つを受け取ります。
引数 |
関数 |
挿入先 |
|---|---|---|
|
3つすべて |
その保存済みスロットの直前または直後。 |
|
|
その行の左端(マーカーの後)または右端。行は空でもかまいません。Layout Panel行は |
|
|
新しい最後の行。 |
|
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"])
Popupの解決済み挿入位置を読む¶
add_slot() と move_slot() のPopupの結果は insertion_position を含みます。
transfer_slot() では result["to"]["insertion_position"] です。
値は呼び出しが解決した位置で、dry runでも書き込みでも同じ方法で記録されます。
呼び出し 前 の保存順にある隙間を表します。
キー |
型 |
値 |
|---|---|---|
|
str |
常に |
|
int |
0から保存スロット数までの隙間のindex。マーカーとspacerを含みます。 |
|
str or None |
隙間の直前のスロット。先頭では |
|
str or None |
隙間の直後のスロット。末尾では |
|
dict or None |
|
|
str or None |
新しい最後の行では |
保存順が [row, A, COLUMN, B] の場合、Aの後の位置は、Aと COLUMN spacerの間の
index 2です。Bの前の位置は、COLUMN spacerとBの間のindex 3です。
隣接するマーカーとspacerのUIDが、境界の両側を区別します。
新しい行への挿入は、呼び出し前の状態の末尾indexを
row_ref=Noneとともに返します。将来の行参照やUIDは割り当てません。移動元の除去、spacerの挿入、整理によって、最終的なindexは変わる場合があります。 成功後も失敗後も、値は呼び出し前の基準のままです。保存結果は
after_*の値と順序が示します。unchangedの移動は、要求された隙間を、移動元のUIDを隣接スロットとして返す場合があります。位置の解決前の拒否では
Noneです。解決後の拒否は位置を持つ場合があります。呼び出しが許可されるかはstatusとdiagnosticsで判断します。 新しい検査が以前の検査の位置を再利用することはありません。swap_slots()、remove_slot()、このページの関数、 他の種類のメニューへの転送はNoneを返します。この値が記録するのは保存上の挿入境界だけです。列とsubrowの入れ子は木構造として報告しません。dry runは
before_rowsとafter_rowsに現在の保存行を入れ、整理の結果を予測しません。
関連項目: パネルを1行ずつ組み立てる。