Layout rows and panels¶
Pop-up Dialogs (DIALOG) and Floating Panels (FPANEL) store rows, spacers
and Layout Panels as slots in the menu’s saved list. The functions on this page
read that list as rows and change rows, spacers, item alignment and Layout
Panels. Adding, removing, moving and editing single items is on
Slots; Mode, width and the other menu settings are on
Menu type settings.
Function |
Purpose |
|---|---|
Returns the rows under |
|
Adds a row with a default button. |
|
Adds a row with a Layout Panel. |
|
Removes a row and everything in it. |
|
Moves a row before or after another row. |
|
Splits a row before one of its slots. |
|
Joins two adjacent rows. |
|
Changes row settings. |
|
Changes one spacer setting, creating the spacer when needed. |
|
Places an item in the left, center or right section of its row. |
Saved layout¶
The saved list is read in order, left to right and top to bottom. Three kinds of slot carry the layout:
Slot |
Saved as |
Meaning |
|---|---|---|
Row marker |
|
Starts a row. The text holds the row settings. |
Spacer |
|
A gap, column boundary, alignment boundary or subrow boundary inside a row. The text holds the spacer settings. |
Layout Panel anchor |
|
Starts a Layout Panel. The slots after it in the same row are the Panel header. |
A row runs from its marker to the next marker. Slots before the first marker form a markerless first row, which has default settings. A new Pop-up Dialog or Floating Panel has one marker and one button.
Rows¶
read_pm(pm_uid)["rows"] lists the rows of a Pop-up Dialog or Floating Panel
in saved order. Other menu types have no rows key. An empty menu has
rows == []. The slot_uids argument of read_pm() filters only
slots; rows always describes the whole menu. Reading does not add
markers, repair UIDs, initialize the version or change the layout.
Each row is a dictionary:
Key |
Type |
Value |
|---|---|---|
|
dict |
Reference to the row. See Row references. |
|
list[str] |
UIDs of every slot in the row in saved order, the marker included. |
|
bool |
|
|
str or None |
The marker’s saved text. |
|
dict |
Row settings by name, see Row settings. A name missing from the saved text has its default. A row without a marker has all defaults; the text of its first item is not read as row settings. |
|
list[str] |
Setting names that are not in the saved text. All names for a row without a marker. |
|
list[dict] |
|
|
list[dict] |
One entry per spacer in the row, in saved order. See below. |
|
dict or None |
The row’s Layout Panel, or |
A spacer entry:
Key |
Type |
Value |
|---|---|---|
|
str |
UID of the spacer. |
|
str |
The spacer’s saved text. |
|
dict |
|
|
list[str] |
Setting names that are not in the saved text. |
|
list[dict] |
As for the row. |
A panel entry:
Key |
Type |
Value |
|---|---|---|
|
str |
UID of the anchor: the first Layout Panel anchor in the row. |
|
dict |
The anchor’s options read as |
|
any |
The saved |
|
bool |
Whether the anchor has a saved |
|
list[str] |
Every slot after the anchor in the row, in saved order. Disabled items and items hidden while Header Layout is off are included. |
>>> 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 references¶
A row_ref is {"kind": kind, "slot_uid": uid}: the slot that starts the
row. kind is "marker" when that slot is the row marker and
"first_item" for the first slot of a markerless first row. A row_ref is
not a permanent row ID.
A row_ref is accepted while a row still starts with the same slot and the
same kind. It stops matching when that slot moves or is removed, when another
slot is placed before it, or when a marker is added to a markerless first row
(the reference changes from "first_item" to "marker"). An old reference
is not redirected to another row: operations reject it with row_not_found.
Take current references from the after_rows of the last result, or read
again.
Row operations accept a row_ref with exactly the keys kind and
slot_uid. Other keys or a missing key raise TypeError; another kind
raises ValueError.
Row settings¶
Row settings are stored in the row marker’s text. update_row() accepts
these names and values.
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
str |
|
|
Alignment of the row and its subrows when the row has no |
|
str |
|
|
Button height: 1, 1.25 or 1.5 times normal. |
|
str |
|
|
Space above the row: 0, 1, 3 or 5 separators. No space is drawn above the first row. |
|
bool |
|
Give the row’s columns equal widths. |
|
|
bool |
|
Use equal button widths in the row or its subrows. |
Spacer settings¶
Spacer settings are stored in the spacer’s text. update_spacer()
changes one of them per call.
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
str |
|
|
|
|
str |
|
|
|
Common result keys¶
Every function on this page returns the dictionary described here. So do
add_slot(), remove_slot(), move_slot() and
swap_slots() on a Pop-up Dialog or Floating Panel, without the three
*_row_refs keys. transfer_slot() has its own result; its Popup side
carries before_rows, after_rows and insertion_position.
Key |
Type |
Value |
|---|---|---|
|
str |
See Status. |
|
bool |
|
|
str |
UID of the menu. |
|
int |
The menu’s session-local version after the call. Equal to
|
|
int |
The version read before the call. |
|
int |
The version read after the call. |
|
list[str] |
Slot UIDs in saved order before the call. |
|
list[str] or None |
Slot UIDs in saved order after the call. |
|
list[dict] |
Rows before the call, as in Rows. |
|
list[dict] or None |
Rows after the call. |
|
dict or None |
The gap an item addition or move resolved to. See
Read a resolved Popup insertion position. |
|
list[dict] |
The call’s target slots. Each entry has |
|
list[dict] |
Other slots whose saved values or index changed: |
|
list[str] |
Slots present after the call and not before, in saved order. |
|
list[str] |
Slots present before the call and not after. |
|
list[str] |
Slots whose index changed, including shifts caused by inserted or removed slots. |
|
list[dict] |
The actual row and spacer changes, including cleanup outside the target row. See below. |
|
dict |
The saved slot collection read before the call: |
|
str |
|
|
list |
Always |
|
list[dict] |
One entry per problem: |
|
list[dict] |
Functions on this page only. Row references present after the call and not before. |
|
list[dict] |
Functions on this page only. Row references present before the call and not after. |
|
list[dict] |
Functions on this page only. Row references whose start index changed, including shifts caused by another row’s change. |
structure_changes entries:
|
Other keys |
Meaning |
|---|---|---|
|
|
The complete |
|
|
A row marker or spacer was added, removed, changed or shifted.
|
|
|
The call added a marker to a markerless first row. |
Status¶
The values are those of Results and guards.
|
Meaning |
|---|---|
|
|
|
No saved change: the saved slots already satisfy the call, or the write
left them equal to |
|
The saved slots changed and were read back. The version increased by one. |
|
Nothing was written. |
|
A write raised and the saved slots were restored to the |
|
A write raised and the restore failed. |
Common diagnostics¶
|
Cause, and extra keys |
|---|---|
|
The menu is not a Pop-up Dialog or Floating Panel. Reported by every
function on this page: |
|
|
|
|
|
A |
|
A UID does not identify one slot of the menu. |
|
The Slot Editor has an open draft on a slot that the call would delete or rewrite. |
|
The call is not available for a Layout Panel row or anchor. Each function entry gives the case. |
|
The change would place the row’s first |
|
A write raised. |
|
Restoring the |
|
The editor refresh raised after the write. |
|
Reading the saved state after the call raised. |
Checks before writing¶
Every function on this page takes expected_version, expected and
dry_run.
Argument |
Rule |
|---|---|
|
|
|
|
|
A |
A dry run writes nothing: no UIDs, no markers, no version change and no refresh.
Its before_* and after_* values both describe the current saved state,
and its created, deleted and moved lists are empty. It does not predict cleanup,
new UIDs or drawing success. The later call resolves its arguments and checks
the current saved state again.
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"])
Notes¶
Only
committedincreases the version, once per call.committed=Falsewithstatus="unknown"does not mean that nothing changed.The editor refresh runs after every write, including one that ends
unchangedorrestored_failure. A call that stops before writing (a dry run, a rejection, or a no-op found before writing) does not refresh.When the final readback raises,
after_orderandafter_rowsareNone;after_orderis kept when only the row readback failed. The created, deleted and moved lists are then empty, which does not mean that nothing changed. Read again before retrying.Selection, unrelated Slot Editor drafts and the row clipboard stay in place.
The calls do not save Preferences to disk or add an Undo step.
Row operations¶
The editor’s Add Row, Remove Row, Move Row, Split and Join
Rows commands call the same operations. Pass current row references from
read_pm()["rows"] or from the last result’s 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 a row marker and a default button, as Add Row does.
Give at most one position. Without one, the row is appended after the last row, also in an empty menu.
- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
before_row_ref (dict or None) – Insert the new row before this row.
after_row_ref (dict or None) – Insert the new row after this row.
expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError – A
row_refis not a mapping with exactlykindand a non-emptyslot_uidstring, orexpected_version,expectedordry_runhas the wrong type.ValueError – Both positions are given, a
row_refkind is not"marker"or"first_item", or the menu UID is missing, invalid or ambiguous.
Result
slotsholds the new marker and the new button, in that order.created_uidslists the same two UIDs.created_row_refsholds the new row.Diagnostics
row_operation_unsupported,row_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
added = pme.editing.add_row(pm_uid) marker_uid, button_uid = added["created_uids"]
Notes
The new button is a Command slot named
Button <n>with no command. An empty menu receives a marker with the textrowand one button.The new row’s settings follow Add Row:
Appended, also after the last row:
sizefrom the last row, andvspacerfrom it unless that row has aCOLUMNspacer.Before a row:
sizefrom that row. The new row getsvspacer="NONE"if that row hadNONEand the row above it has noCOLUMNspacer, otherwise"NORMAL". That row’svspacerbecomes"NONE"unless it has aCOLUMNspacer.After a row that is not the last:
sizefrom that row, andvspacer="NONE"unless that row has aCOLUMNspacer, in which case"NORMAL".A row with a
COLUMNspacer, and the row directly below it, never receivevspacer="NONE"from this call; the editor’s row Spacer menu does not offerNONEthere either. ANONEalready saved on such a row is kept.
before_row_refnaming a markerless first row adds a marker to that row first, keeping its slots and their text.structure_changesthen has a"row_ref"entry.after_row_refadds no marker to it.
- pme.editing.remove_row(pm_uid, row_ref, *, expected_version=None, expected=None, dry_run=False)¶
Remove a row: its marker and every slot in it.
The next row keeps its marker and settings. Removing the last row leaves an empty menu.
- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
row_ref (dict) – The row to remove.
expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError –
row_refis not a mapping with exactlykindand a non-emptyslot_uidstring, orexpected_version,expectedordry_runhas the wrong type.ValueError – The
row_refkind is not"marker"or"first_item", or the menu UID is missing, invalid or ambiguous.
Result
slotsholds every slot of the removed row; theirafterisNone.deleted_row_refsholds the removed row.Diagnostics
codeCause, and extra keys
slot_edit_conflictThe Slot Editor has an open draft on a slot of the row.
Also
row_operation_unsupported,row_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
rows = pme.editing.read_pm(pm_uid)["rows"] result = pme.editing.remove_row(pm_uid, rows[-1]["row_ref"])
Notes
A Layout Panel row is removed with its anchor and every header item, including disabled items and items hidden while Header Layout is off.
No empty-row or spacer cleanup runs on the neighboring rows.
Unrelated drafts, the selection and the row clipboard stay in place.
- pme.editing.move_row(pm_uid, row_ref, *, before_row_ref=None, after_row_ref=None, expected_version=None, expected=None, dry_run=False)¶
Move a whole row before or after another row.
Give exactly one of
before_row_refandafter_row_ref.- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
row_ref (dict) – The row to move.
before_row_ref (dict or None) – Move the row before this row.
after_row_ref (dict or None) – Move the row after this row.
expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError – A
row_refis not a mapping with exactlykindand a non-emptyslot_uidstring, orexpected_version,expectedordry_runhas the wrong type.ValueError – Neither or both positions are given, a
row_refkind is not"marker"or"first_item", or the menu UID is missing, invalid or ambiguous.
Result
slotsholds the slots of the moved row.moved_row_refslists every row whose start index changed.Status
unchangedwhenrow_refnames the target row itself or the row is already at that position. This is also the dry-run status in that case. No marker is added, the version does not change and the editor is not refreshed.Diagnostics
row_operation_unsupported,row_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
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"], )
Notes
The row’s slots, settings and UIDs move together, including the header items of a Layout Panel row.
No item-move cleanup runs.
A markerless first row receives a marker when it is moved, or when it is the
before_row_reftarget.structure_changesthen has a"row_ref"entry.
- pme.editing.split_row(pm_uid, row_ref, *, before_uid, expected_version=None, expected=None, dry_run=False)¶
Split an ordinary row so that one of its slots starts a new row.
The slot named by
before_uidand the slots after it in the row move to a new row with default settings. No button is added.- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
row_ref (dict) – The row to split.
before_uid (str) – A slot of the row other than its marker: an item or a spacer.
expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError –
before_uidis not a non-empty string,row_refis not a mapping with exactlykindand a non-emptyslot_uidstring, orexpected_version,expectedordry_runhas the wrong type.ValueError – The
row_refkind is not"marker"or"first_item", or the menu UID is missing, invalid or ambiguous.
Result
slotsholds the row’s slots and the new marker.created_row_refsholds the new row.Diagnostics
codeCause, and extra keys
panel_rowThe row is a Layout Panel row.
split_position_not_foundbefore_uidis not in the row, or is its marker.aligner_without_rootThe new row would start its first
ALIGNERafter its firstCOLUMN.column_slot_uid,aligner_slot_uid,message.Also
row_operation_unsupported,row_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
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], )
Notes
The original row keeps its marker and settings. The new marker has default settings.
One spacer immediately before
before_uidis removed, as Split does. Other slots and all UIDs stay.before_uidnaming the first item leaves the original row empty. A markerless first row receives a marker first;structure_changesthen has a"row_ref"entry.A spacer named by
before_uidstays at the start of the new row. Naming theALIGNERspacer itself keeps the alignment root.Rows with
COLUMNorALIGNERspacers are accepted unlessaligner_without_rootapplies. A row already in that state is not repaired.The editor does not offer Split on the first item. The function accepts it.
- pme.editing.join_rows(pm_uid, first_row_ref, second_row_ref, *, expected_version=None, expected=None, dry_run=False)¶
Join two adjacent ordinary rows.
second_row_refmust start where the first row ends.- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
first_row_ref (dict) – The upper row. It keeps its marker and settings.
second_row_ref (dict) – The row directly below it.
expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError – A
row_refis not a mapping with exactlykindand a non-emptyslot_uidstring, orexpected_version,expectedordry_runhas the wrong type.ValueError – A
row_refkind is not"marker"or"first_item", or the menu UID is missing, invalid or ambiguous.
Result
slotsholds the slots of both rows.deleted_row_refsholds the second row.Diagnostics
codeCause, and extra keys
panel_rowEither row is a Layout Panel row.
rows_not_adjacentAnother row lies between them, they are in the reverse order, or both references name the same row.
Also
row_operation_unsupported,row_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
rows = pme.editing.read_pm(pm_uid)["rows"] result = pme.editing.join_rows(pm_uid, rows[0]["row_ref"], rows[1]["row_ref"])
Notes
The second row’s marker is removed, and so is every spacer in the second row whose
hsepisCOLUMNorALIGNER. Other spacers and items stay.
Row settings, spacers and alignment¶
The editor’s row settings, spacer and alignment commands call the same operations. The caller does not build row or spacer text.
- pme.editing.update_row(pm_uid, row_ref, changes, *, scope='row', expected_version=None, expected=None, dry_run=False)¶
Change the settings of one row or a group of rows.
Settings that already have the requested value are not written. When nothing differs, the result is
unchanged.- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
row_ref (dict or None) – The row.
Noneonly withscope="all_rows".changes (dict) – Row setting name mapped to its new value. Partial: settings that are not named keep their values. Names and values are under Row settings.
scope (str) –
"row","aligned_rows"or"all_rows". See Scope below.expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError –
changesis not a mapping; a value has the wrong Python type (boolforfixed_colandfixed_but,strfor the others);row_refisNonewith another scope or is not a mapping with exactlykindand a non-emptyslot_uidstring; orexpected_version,expectedordry_runhas the wrong type.ValueError – A name is not a row setting, a value is not one of its values,
scopeis not one of the three values, therow_refkind is not"marker"or"first_item", or the menu UID is missing, invalid or ambiguous.
Scope
scopeRows changed
rowThe row named by
row_ref.aligned_rowsThe row’s group of rows joined by
vspacer="NONE": upward while a row hasvspacer="NONE", so the group’s top row is included, and downward while the next row hasvspacer="NONE".all_rowsEvery row, a markerless first row included.
row_refmay beNone. An empty menu stays empty and returnsunchanged.Result
slotsholds the slots of every row in the scope.Diagnostics
codeCause, and extra keys
panel_rowscope="row"on a Layout Panel row with a setting other thanvspacer.fieldslists those names.row_fields_skippedNot a rejection. A wider scope left settings other than
vspacerunchanged on a Layout Panel row.row_ref,fields.slot_edit_conflictThe Slot Editor has an open draft on a marker that would be rewritten.
Also
row_operation_unsupported,row_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
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"])
Notes
A Layout Panel row accepts only
vspacer.With
scope="all_rows",vspacer="NONE"is written as"NORMAL"on a row when that row or the row above it has aCOLUMNspacer.Values are compared after that adjustment. A call with nothing to change leaves the saved text, UIDs and version as they are and does not refresh.
A markerless first row receives a marker only when one of its settings changes. Its first item keeps its command text.
structure_changesthen has a"row_ref"entry.A changed marker is written with the editor’s encoding, which can normalize or drop unknown query keys on that marker. Other saved values stay.
alignis the row setting, not the item placement done byalign_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)¶
Change one spacer setting, creating the spacer when needed.
Name exactly one target:
slot_uidfor an existing spacer, orbefore_uid/after_uidfor the spacer beside a content slot. One call changes one setting, because the cleanup depends on the order of changes.- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
slot_uid (str or None) – An existing spacer: leading, trailing or between items.
before_uid (str or None) – A content slot. The spacer immediately before it in the same row is changed; when there is none, a spacer is created there.
after_uid (str or None) – A content slot. The spacer immediately after it in the same row is changed or created.
prop (str) –
"hsep"or"subrow".value (str) – A value of
prop, see Spacer settings.expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError –
valueis not a string, the target UID is not a non-empty string, orexpected_version,expectedordry_runhas the wrong type.ValueError –
propis not a spacer setting,valueis not one of its values, not exactly one target is given, or the menu UID is missing, invalid or ambiguous.
Result
slotsholds the spacers whose settings change, the targeted spacer and a created spacer.Diagnostics
codeCause, and extra keys
spacer_requiredslot_uidnames a row marker or a content slot.content_slot_requiredbefore_uidorafter_uidnames a spacer or a row marker.panel_rowIn a Layout Panel row: the target is the anchor,
propissubrow, or the value ishsep="COLUMN".aligner_without_rootSee Common diagnostics.
slot_edit_conflictThe Slot Editor has an open draft on a spacer or marker that would be rewritten or removed.
Also
row_operation_unsupported,slot_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
result = pme.editing.update_spacer( pm_uid, after_uid=slot_uid, prop="hsep", value="SPACER", )
Notes
An adjacent spacer is updated in place.
add_slot()withuse_spacer=Trueinserts a spacer instead.The neighbor must be in the same row. Leading and trailing positions are accepted. Creating a spacer before the first item of a markerless first row adds no row marker.
A spacer whose settings all become
NONEis removed.NONEwith no adjacent spacer returnsunchanged.hsep="COLUMN"on a spacer withsubrow="END"clears theEND.hsep="COLUMN"also setsvspacer="NORMAL"on this row and the next row where they havevspacer="NONE". The first row is not changed.Changing the row’s only
COLUMNspacer to anotherhsepclearssubrowon every spacer in the row.Changing
subrowfromBEGINtoNONEalso clears the nextENDin the row, unless aBEGINorCOLUMNcomes first.A subrow does not require a
COLUMNspacer.Spacers in a Layout Panel header can be changed while Header Layout is off. The change does not turn Header Layout on.
- pme.editing.align_slot(pm_uid, slot_uid, alignment, *, expected_version=None, expected=None, dry_run=False)¶
Place an item in the left, center or right section of its row.
The call moves or creates
ALIGNERspacers as the editor’s alignment buttons do. It does not write the row’salignsetting.- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
slot_uid (str) – A content slot.
alignment (str or None) –
"LEFT","CENTER","RIGHT", orNoneto remove the row’s outer alignment boundaries.expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError –
slot_uidis not a non-empty string, orexpected_version,expectedordry_runhas the wrong type.ValueError –
alignmentis not one of the four values, or the menu UID is missing, invalid or ambiguous.
Result
slotsholds the item. Spacers that are created, moved, changed or removed appear increated_uids,deleted_uids,side_effectsandstructure_changes.Diagnostics
codeCause, and extra keys
content_slot_requiredslot_uidnames a row marker or a spacer.panel_rowslot_uidnames a Layout Panel anchor.item_in_column_regionThe row has a
COLUMNspacer and the item comes after the first one.column_slot_uid,message.aligners_after_columnThe row has an
ALIGNERafter its firstCOLUMN.message.popup_slot_alignment_failedThe changes could not be calculated from the saved data. Nothing was written and
recoveryis"not_needed". The traceback is printed to the console.exception_type,message.aligner_without_rootSee Common diagnostics.
slot_edit_conflictThe Slot Editor has an open draft on a slot that would be moved, rewritten or removed.
Also
row_operation_unsupported,slot_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
result = pme.editing.align_slot(pm_uid, slot_uid, "RIGHT")
Notes
In a row with
COLUMNspacers the item must come before the firstCOLUMN, and noALIGNERmay follow it. Elsewhere, edit the boundaries withupdate_spacer(). This limit belongs toalign_slot, not to the saved layout.Noneremoves the row’s first and lastALIGNER(up to two), also when the item is after aCOLUMN. FurtherALIGNERspacers in imported data stay.Adjacent spacers are merged afterwards by the editor’s rules.
Alignment in a Layout Panel header can be changed while Header Layout is off. The change does not turn Header Layout on.
Layout Panels¶
A Layout Panel is a collapsible section of a Pop-up Dialog or Floating Panel. It
occupies one row. Its anchor is a Menu slot whose target menu supplies the Panel
body; the slots after the anchor in the same row form the Panel header. A
Panel’s anchor and header move or are removed together with the row
(move_row(), remove_row()). The anchor cannot be removed,
moved or exchanged as a single item (panel_row). Layout Panel rows cannot be
split or joined.
- pme.editing.add_panel(pm_uid, *, before_row_ref=None, after_row_ref=None, expected_version=None, expected=None, dry_run=False)¶
Add a row with a default Layout Panel anchor, as Add Panel does.
Give at most one position. Without one, the row is appended after the last row, also in an empty menu.
- Parameters:
pm_uid (str) – UID of a Pop-up Dialog or Floating Panel.
before_row_ref (dict or None) – Insert the new row before this row.
after_row_ref (dict or None) – Insert the new row after this row.
expected_version (int or None) – See Checks before writing.
expected (dict or None) – See Checks before writing.
dry_run (bool) – Check and return without writing.
- Returns:
The result described in Common result keys.
- Return type:
- Raises:
TypeError – A
row_refis not a mapping with exactlykindand a non-emptyslot_uidstring, orexpected_version,expectedordry_runhas the wrong type.ValueError – Both positions are given, a
row_refkind is not"marker"or"first_item", or the menu UID is missing, invalid or ambiguous.
Result
slotsholds the anchor.created_uidslists the new marker and the anchor.created_row_refsholds the new row.Diagnostics
codeCause, and extra keys
layout_panel_unavailableBlender is older than 4.2 or has no
UILayout.panel. Checked before a dry run returns.Also
row_operation_unsupported,row_not_found,stale_version,stale_popupand the write failures under Common diagnostics.Example
added = pme.editing.add_panel(pm_uid) anchor_uid = added["slots"][0]["uid"]
Notes
The anchor is a Menu slot named
Panelwith no target, no icon and no button background color. Itslayout_panelis a freshidname(layout_panel_<id>) withdefault_closedanduse_header_layoutset toFalse. The header is empty.The new row’s
sizeandvspacerfollow Add Row, as inadd_row(). Then the new row and the row after it getvspacer="NORMAL"where they havevspacer="NONE".before_row_refnaming a markerless first row adds a marker to that row, keeping its slots and their text.Set the anchor’s name and
menu_target_uidwithupdate_slots(), using the anchor’s UID. Givemenu_target_uidin the same edit as the name or before it: an edit on an anchor without a body menu is rejected (see Panel settings below). Alayout_paneldictionary or row marker is not built by hand.
Panel settings¶
The Panel settings are the update_slots() fields
layout_panel_default_closed and layout_panel_use_header_layout on the
anchor. Both accept only bool.
update_slots()saves the anchor as the Slot Editor does, and the Slot Editor saves a Menu slot only with a body menu. On an anchor without one, such as a newadd_panel()anchor, every edit is rejected: the slot entry haseditor_validationwith the editor’s message"Select the item", whichever fields are given. Givemenu_target_uidin the same edit or an earlier one. The editor’s anchor menu changes Default Closed and Header Layout without a body menu; nopme.editingfunction does.Turning
layout_panel_use_header_layouton while the header is empty adds one button to the header.A header that becomes empty later stays empty: another save, a rename or an unchanged
Truedoes not add a button.Turning it off keeps every saved header item.
A changed save applies the editor’s anchor normalization, including
enabled=True.enabledis not anupdate_slots()field.update_slots()saves edits one after another; a failure does not undo earlier edits.
Header positions¶
add_slot(), move_slot() and transfer_slot() place an
item in a Panel header with header_anchor_uid, the panel["anchor_uid"]
of the row, combined with exactly one position:
Position |
Meaning |
|---|---|
|
Before or after a saved slot of that header. Spacers count as positions. |
|
Directly after the anchor. |
|
At the end of the header. Use an edge when the header is empty. |
Giving none or several positions with
header_anchor_uid, anedgeother than"START"or"END", orheader_anchor_uidtogether withrow_refornew_rowraisesValueError.A
row_refof a Layout Panel row does not mean its header; it is rejected withpanel_row.move_slot()into a header from an ordinary row or another header needsheader_anchor_uid; otherwise the result isheader_role_required. Moving withbefore_uid/after_uidinside the same header works without it.transfer_slot()into a header always needs it.add_slot()withbefore_uid/after_uidinside a header works withoutheader_anchor_uidwhile Header Layout is on, and needs it while Header Layout is off.swap_slots()takes only the two UIDs. It exchanges an ordinary item with a header item, or items in different headers, without cleanup.An anchor cannot be moved into another header. A second anchor already saved inside a header can be removed with
remove_slot(); nothing inserts one.Header items can be added, moved and removed while Header Layout is off; the call does not turn it on. The result then has
header_layout_disabledwith theanchor_uidindiagnostics. Preferences shows these items for editing; the menu at run time hides them.In the editor, the anchor’s menu has Add for an empty header, Move offers the header start and end, Ctrl+Alt+click removes one header item, and Delete Inactive Header removes all items of a header whose Header Layout is off.
|
Cause, and extra keys |
|---|---|
|
Not a rejection. The header’s Header Layout is off. |
|
|
|
|
|
A move or transfer into a header without |
|
The destination is in a Layout Panel row outside the header positions,
or |
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"])
Item positions in rows¶
In a Pop-up Dialog or Floating Panel, add_slot(), move_slot()
and transfer_slot() take one of these destination forms.
Arguments |
Functions |
Destination |
|---|---|---|
|
all three |
Directly before or after that saved slot. |
|
|
The left end (after the marker) or the right end of that row. The row
may be empty. A Layout Panel row is rejected with |
|
|
A new last row. |
|
all three |
A Panel header. See Header positions. |
Exactly one form is accepted. Mixing forms raises
ValueError.new_rowis the string"END", not a bool.use_spaceris abooland defaults toFalse. The Preferences setting does not apply.before_uid/after_uiduse the anchor’s saved index. Markers and spacers are not skipped:after_uid=Aandbefore_uid=Bare different positions when spacers lie between A and B.move_slot()runs the editor’s empty-row and spacer cleanup for all forms. The moved item keeps its UID and saved values; the selection and an open Slot Editor draft stay attached to their items.A move with
before_uid/after_uidthat is already satisfied, including a self anchor, returnsunchangedwithout spacers, cleanup, version change or refresh. A row-edge move that is already satisfied can still refresh the editor. Moving the only item of a row to a new row can endunchangedafter cleanup.swap_slots()exchanges two items with their UIDs and saved values, without cleanup of empty rows or spacers.The editor’s Move chooser offers the same before and after positions, the exchange, the row ends and 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"])
Read a resolved Popup insertion position¶
Popup results of add_slot() and move_slot() include
insertion_position. For transfer_slot() it is
result["to"]["insertion_position"]. The value is the position the call
resolved, recorded the same way for a dry run and for the write. It describes
a gap in the saved order before the call.
Key |
Type |
Value |
|---|---|---|
|
str |
Always |
|
int |
Gap index from 0 through the number of saved slots, markers and spacers included. |
|
str or None |
The slot directly before the gap. |
|
str or None |
The slot directly after the gap. |
|
dict or None |
The before-state row that contains |
|
str or None |
|
For the saved order [row, A, COLUMN, B], a position after A is index 2,
between A and the COLUMN spacer; a position before B is index 3, between
the COLUMN spacer and B. The UIDs of the neighboring markers and spacers
tell the two sides of a boundary apart.
A new-row destination reports the end index of the before state with
row_ref=None. No future row reference or UID is allocated.Removing the source, inserting a spacer and cleanup can change the final index. The value keeps its before basis after success or failure; the
after_*values and orders give the saved result.An
unchangedmove can report the requested gap with the source UID as a neighbor.A rejection before the position is resolved has
None. A rejection after it can carry a position;statusanddiagnosticsdecide whether the call is allowed. A new check never reuses the position of an earlier one.swap_slots(),remove_slot(), the functions on this page and transfers to other menu types reportNone.The value records saved insertion boundaries only. Column and subrow nesting is not reported as a tree. A dry run keeps the current saved rows in
before_rowsandafter_rowsand does not predict cleanup.
See also: Build a panel row by row.