Slots¶
A slot is one saved item of a menu: a command, a property, a link to another
menu, or a layout entry. This page covers the saved fields of a slot, the Slot
Editor inputs, and the operations that edit, clear, add, remove, move, exchange
and transfer slots. Rows, spacers and Layout Panels of Pop-up Dialogs and
Floating Panels are on Layout rows and panels. The menu-level result of
read_pm() is on Menus.
Function |
Purpose |
|---|---|
Returns the menu’s slots under |
|
Describes the inputs |
|
Returns slots under those input names. |
|
Reports whether Auto Icon finds an icon for each slot. |
|
Changes slot contents through the Slot Editor’s save. |
|
Clears slot contents and keeps the slots. |
|
Adds one default item. |
|
Removes one item. |
|
Moves one item within its menu. |
|
Exchanges two items. |
|
Moves one item’s contents to another menu. |
Slot snapshot¶
read_pm() returns the menu’s slots in saved order under slots.
Each slot is a dictionary of plain Python values. The same dictionary is the
before and after value of a slot in operation results. Writes select a
slot by uid; index only reports the current position.
Key |
Type |
Value |
|---|---|---|
|
str |
Slot UID. Unique within its menu. |
|
int |
Position in the menu’s saved slot list, from 0. Layout entries count. |
|
bool |
Whether the slot is enabled. Not an input of |
|
dict or None |
On a Layout Panel anchor: |
|
str |
Label. |
|
str |
Icon flags followed by the icon name. See Icon value. In a Modal Operator, the modal input of Command and Property slots. See Modal input. |
|
str |
|
|
bool |
Auto Icon. Saved as |
|
str |
Stored body. Its meaning depends on |
|
str |
Menu slot: UID of the linked menu. Empty for a link saved by name only and for other modes. |
|
str |
Menu slot: last known name of the linked menu. |
|
str |
Menu slot linking a Regular Menu: |
|
bool |
Menu slot: close the Vector Menu when the link starts a Sticky Key. |
|
float |
Menu slot: width of the expanded menu in pixels. |
|
float |
Menu slot: offset of the expanded menu in pixels. |
|
bool |
Command slot: add an Undo step after running a command that is not a Blender operator. |
|
str |
Tooltip text, or Python code when |
|
bool |
Run |
|
str |
Vector Menu enum presentation for this slot: |
|
str |
Property Split for this slot: |
|
bool |
Use |
|
list[float] |
Red, green and blue, each from 0.0 to 1.0, in scene linear color. See Button background color. |
>>> pme.editing.read_pm(pm_uid)["slots"][0]
{'uid': 'pmi_2j2ssemr', 'index': 0, 'enabled': True, 'layout_panel': None,
'name': 'Knife', 'icon': '', 'mode': 'COMMAND', 'auto_icon': True,
'text': "bpy.ops.wm.tool_set_by_id(name='builtin.knife')",
'target_pm_uid': '', 'target_pm_fallback_name': '', 'menu_presentation': '',
'menu_sticky_close': False, 'menu_expand_width': -1.0,
'menu_expand_offset_x': 0.0, 'menu_expand_offset_y': 0.0, 'exec_undo': False,
'description_is_expr': False, 'description': '',
'vector_menu_enum_strategy': 'global', 'use_property_split_override': 'inherit',
'button_background_color_enabled': False,
'button_background_color': [0.0, 0.0, 0.0]}
Text by mode¶
text is stored text. It is edited through the inputs in the last column,
not written directly.
|
|
Input |
|---|---|---|
|
Empty for an empty slot. In a Regular Menu, a layout entry:
|
|
|
Python code run when the slot is used. |
|
|
Data path of a Blender property, for example
|
|
|
Name of the linked menu, with an optional |
|
|
Hotkey string: modifiers |
|
|
Python code that draws a custom layout. |
|
|
Modal Operator: Python code run when the operator is invoked, confirmed, cancelled or updated. |
|
Icon value¶
icon is optional flags followed by an icon name, for example
#!^TOOL_SETTINGS. The flags are part of the string, not separate fields.
Flag |
Meaning |
|---|---|
|
Icon only: no label. |
|
Hidden. |
|
Checkbox style, where supported. |
Flags are read in the order #, !, ^. A flag out of that order is
part of the name. The name is a Blender icon identifier such as
TOOL_SETTINGS, "" or NONE for no icon, or @filename for a
custom PNG icon. An unknown name is saved as given; the
slot shows a fallback icon and update_slots() reports
icon_not_found.
In a Macro Operator, the editor sets the icon of every Command step when the
Macro is registered: BLENDER for a step that runs as an operator step of
Blender’s Macro, TEXT for a step that runs as code. An icon input on
such a step is replaced. The two kinds of step are described in
Operator steps and code steps.
Slot input fields¶
update_slots() accepts the Slot Editor’s inputs, not saved fields.
slot_fields() describes them and read_slot_inputs() returns
their current values. Inputs that are not named keep the values the Slot Editor
loads from the saved slot.
Input |
Type |
Saved field |
Meaning |
|---|---|---|---|
|
str |
|
Slot mode. |
|
str |
|
Label. |
|
str |
|
Flags and icon name. See Icon value. |
|
bool |
|
Auto Icon. Kept only on a Command slot. |
|
str |
|
Python code of a |
|
str |
|
Property data path of a |
|
str |
|
Layout code of a |
|
bool |
|
Undo step for a Command slot. |
|
str |
|
Linked menu, by name or UID. Resolved to |
|
str |
|
UID of the linked menu. When not empty it replaces |
|
str |
— |
Name used to resolve a link whose UID no longer exists. The saved
|
|
str |
|
|
|
bool |
|
Close the Vector Menu when the link starts a Sticky Key. |
|
bool |
|
Expand the linked menu. See Menu slot text. |
|
bool |
|
Draw a frame around the expanded menu. |
|
float |
|
Width of the expanded menu; |
|
float |
same name |
Offset of the expanded menu. |
|
str |
|
Hotkey slot: key, a Blender event type such as |
|
bool |
|
Hotkey slot: modifier keys. |
|
str |
|
Hotkey slot: a regular key held as a modifier, or |
|
bool |
— |
Read from a saved hotkey. No slot saves it, so only |
|
str |
|
Tooltip text or code. |
|
bool |
|
Run the description as Python. |
|
str |
same name |
|
|
str |
same name |
|
|
bool |
same name |
Use the button background color. |
|
list[float] |
same name |
Three numbers from 0.0 to 1.0, in scene linear color. See Button background color. |
|
bool |
|
Layout Panel anchor: show the panel closed the first time. |
|
bool |
|
Layout Panel anchor: allow slots in the panel header. Switching an empty
header from |
|
dict |
|
Modal Operator only. See Modal input. |
Values are checked by type before anything is saved. A string or Enum input
takes a str, and an Enum value must be in slot_fields()[name]["values"].
A bool input takes True or False only. A float input takes a finite
int or float; button_background_color takes a list or tuple of three.
Modal input¶
In a Modal Operator, Command and Property slots store their modal input in
icon: hotkey;expression for a Command slot, and
hotkey;minimum;maximum;step;expression for a Property slot with a key. The
modal_input input edits these values. On those slots the saved modal input
replaces any icon input.
Field |
Type |
Value |
|---|---|---|
|
str |
Hotkey string, as in a Hotkey slot. Default |
|
str |
Property slot input method: |
|
str |
Display Expression: Python expression whose result is shown in the modal overlay. |
|
float or None |
Property range and step. |
Fields that are not named keep their saved values.
Changing
property_modeon a Property slot sets the key ofMOVEorWHEELand keeps the hotkey’s modifiers and the range.Changing to
KEYneeds an explicithotkey. Without one the save is rejected witheditor_validation.
# invoke_uid and lens_uid are slot UIDs read from the Modal Operator.
pme.editing.update_slots(modal_uid, {
invoke_uid: {"mode": "INVOKE", "cmd": "view = C.space_data"},
lens_uid: {"mode": "PROP", "name": "Lens", "prop": "view.lens",
"modal_input": {"property_mode": "WHEEL", "step": 1.0}},
})
The code of an INVOKE, UPDATE, FINISH or CANCEL slot is the
cmd input. A Property slot’s path can start from a variable that an On
Invoke slot assigned, as view here; see Share the starting value across slots.
The saved icon of the Property slot holds its modal input as text;
read_slot_inputs() returns it as modal_input.
Slot save results¶
update_slots() and clear_slots() return the same result. The
status words are defined on Results and guards.
Key |
Type |
Value |
|---|---|---|
|
str |
See Status below. |
|
bool |
|
|
str |
The |
|
int |
Menu version after the call. |
|
list[dict] |
One entry per attempted slot, in request order. See Slot entry. |
|
list[str] |
UIDs whose save was not attempted. Earlier editor callbacks can still have changed them. |
|
list[dict] |
Request-level problems found before the first save. |
|
dict |
Present when the slot order changed: |
|
list[dict] |
Present when slots not in |
Slot entry
Key |
Type |
Value |
|---|---|---|
|
str |
Slot UID. |
|
str |
|
|
dict |
Slot snapshot at the start of the call. |
|
dict or None |
Slot snapshot after the call. |
|
list |
|
|
list[dict] |
Problems and warnings for this slot. Absent on |
Status
|
Meaning |
|---|---|
|
At least one slot is |
|
Every requested slot is |
|
At least one slot committed, then a slot was rejected. Later slots are
in |
|
No slot committed. |
Diagnostics
|
Cause, and extra keys |
|---|---|
|
|
|
A slot UID is not in the menu. |
|
A value in |
|
|
|
|
|
|
|
The Slot Editor’s check refused the input. |
|
The save was refused without another diagnostic. |
|
The clear was refused. |
|
Warning: an empty slot edited without |
|
Warning: the saved icon name is not a known icon. |
|
Warning: the slot was saved, but the slot read back under input names
(as |
stale_version is always request-level. slot_not_found,
stale_slot, clear_unsupported and structural_slot are request-level
when found before the first save; the same checks run again before each slot,
and a failure then appears in that slot’s entry.
Item operation results¶
add_slot(), remove_slot(), move_slot() and
swap_slots() return the keys below for every menu type.
Key |
Type |
Value |
|---|---|---|
|
str |
See Status below. |
|
bool |
|
|
str |
The |
|
int |
Menu version after the call. |
|
list[dict] |
The target items: |
|
list |
Always empty. |
|
list[dict] |
|
|
list[str] |
Slot UIDs in saved order before and after the call. |
|
list[dict] |
Other items whose snapshot changed, including a changed |
|
dict |
Snapshot to pass back as |
A Pop-up Dialog or Floating Panel result also has these keys. Rows and the insertion position are described on Layout rows and panels.
Key |
Type |
Value |
|---|---|---|
|
int |
Menu version before and after the call. |
|
list[dict] or None |
Rows before and after. |
|
dict or None |
The resolved gap in the saved order before the call. |
|
list[str] |
Items added, removed, or with a changed index. |
|
list[dict] |
Actual row and layout entry changes, cleanup included. |
|
str |
|
Status
|
Meaning |
|---|---|
|
The change is saved and the version increased once. |
|
|
|
|
|
Nothing was written. |
|
Pop-up Dialog and Floating Panel: a write failed and the saved items and order were restored. |
|
Pop-up Dialog and Floating Panel: a write failed and the restore could
not be confirmed. Call |
Diagnostics
|
Cause, and extra keys |
|---|---|
|
|
|
|
|
|
|
Pop-up Dialog or Floating Panel: |
|
The target or anchor UID is not in the menu. Lists add |
|
|
|
The menu type does not support this operation. See Slots by menu type. |
|
|
|
|
|
|
|
A layout entry cannot be moved or exchanged as an item. |
|
The item is a Layout Panel anchor, or the position is inside a Layout Panel row without a header position. |
|
The Layout Panel header position is invalid. See Layout rows and panels. |
|
|
|
Saved slot UIDs are missing, invalid or duplicated. |
|
|
|
Warning: the item is in, or goes to, a header whose Header Layout is off.
|
|
Lists and fixed slots: the normal operation refused the change. |
|
Lists and fixed slots: the change or its editor hook raised, and the order was restored. The traceback is printed to the console. |
|
The write raised. |
|
The restore after a failed write raised. |
|
The editor refresh raised after the write. The saved status stays. |
|
The final readback raised. |
Conflict checks¶
expected_version is the session-local menu version from read_pm()
or a previous result. It changes only through PME’s versioned editing
operations and does not detect every change. expected compares saved
values, including changes made outside those operations. After stale_*,
read again and reconcile the intended change before retrying.
Operation |
Conflict check |
|---|---|
|
|
|
|
|
|
|
|
|
|
The complete |
Pass a returned expected unchanged. Missing fields in a complete snapshot
are not filled in.
Functions¶
- pme.editing.slot_fields()¶
Describe the inputs that
update_slots()accepts.Each description has these keys:
Key
Present for
Value
typeall
"STRING","BOOLEAN","ENUM","FLOAT", or"mapping"formodal_inputdescriptionall except
modal_inputThe editor’s tooltip text. Empty for some inputs.
valuesENUMAccepted identifiers.
modedoes not listEMPTY.lengtharray inputs
Number of items: 3 for
button_background_colorfieldsmodal_inputField names of the mapping
>>> pme.editing.slot_fields()["menu_presentation"] {'type': 'ENUM', 'description': '', 'values': ['BUTTON', 'SUBMENU', 'INLINE']}
Notes
The result is the same for every menu type. Which inputs a slot uses depends on its mode and menu type.
- pme.editing.read_slot_inputs(pm_uid, *, slot_uids=None)¶
Return slots under the input names that
update_slots()accepts.Values are what the Slot Editor loads from the saved slot: the body under
cmd,proporcustom, a Menu slot’s prefix asexpand_menuanduse_frame, a hotkey split intokeyand modifiers.- Parameters:
- Returns:
pm_uidandslots.- Return type:
- Raises:
ValueError – The menu UID is missing, invalid or ambiguous, or a requested slot UID is not in the menu.
Result
Key
Type
Value
pm_uidstr
The
pm_uidargument.slotslist[dict]
In saved order:
uid,indexandeditper slot.editdict or None
Every name in Slot input fields except
modal_input; a Modal Operator slot addsmodal_input.Nonefor empty slots, layout entries (Regular Menu labels, spacers and column breaks; row markers, spacers and Layout Panel anchors) and menu types with their own editor.Example
Copy the content of one slot to another:
inputs = pme.editing.read_slot_inputs(pm_uid, slot_uids=[source_uid]) edit = inputs["slots"][0]["edit"] result = pme.editing.update_slots(pm_uid, {target_uid: edit}) assert result["status"] == "committed", result
Notes
editcan be passed toupdate_slots()unchanged, for the same slot or another one. Passed back to its own slot, it returnsunchangedwithout writing.A Hotkey slot whose saved text contains
anyreadsany=True. Set it toFalsebefore passingeditback: no slot savesany, andupdate_slots()raisesValueErrorforTrue.On a Menu slot that links a Regular Menu,
menu_presentationis the saved value, or the value read from the@prefix when none is saved. Other slots readBUTTON.Nothing is saved.
- pme.editing.resolve_auto_icons(pm_uid, *, slot_uids=None)¶
Report, per slot, whether Auto Icon finds an icon in this Blender session.
- Parameters:
- Returns:
pm_uidandslots.- Return type:
- Raises:
ValueError – The menu UID is missing, invalid or ambiguous, or a requested slot UID is not in the menu.
Result
slotslists the slots in saved order. Each entry has these keys:Key
Type
Value
uid,indexstr, int
Slot UID and position.
auto_iconbool
Truewhen the slot is a Command slot with Auto Icon on.sourcedict or None
What the command names for an icon.
Nonewhenauto_iconisFalseor the command is not a single tool or brush activation.resolvedbool
Truewhen the lookup finds an icon.manual_iconstr
The saved
icon. The slot shows it whenresolvedisFalse.sourcehas these keys:kindKey
Value
"tool"toolTool identifier, such as
builtin.knife."tool"space_typeSpace type named in the command, or
None."asset"assetBrush asset identifier, relative to its library.
"asset"library_type,library_identifierLibrary type and identifier. The identifier is the Custom asset library name; the lookup uses both.
>>> pme.editing.resolve_auto_icons(pm_uid, slot_uids=[slot_uid])["slots"][0] {'uid': 'pmi_2j2ssemr', 'index': 0, 'auto_icon': True, 'source': {'kind': 'tool', 'tool': 'builtin.knife', 'space_type': None}, 'resolved': True, 'manual_icon': ''}
Notes
The lookup is the one the Preferences icon selector uses. It can load icon previews, so it is not part of
read_pm().Nothing is saved.
- pme.editing.update_slots(pm_uid, edits, *, expected_version=None, expected=None)¶
Change slot contents through the Slot Editor’s save, one slot at a time.
Each slot commits on its own, in the order of
edits. The first rejected slot stops the call; earlier commits stay.- Parameters:
pm_uid (str) – UID of the menu.
edits (dict) – Slot UID mapped to a dictionary of input names and values. Partial: inputs that are not named keep their loaded values. An empty dictionary, or values that the save would store exactly as the slot already has them, leave the slot
unchanged.expected_version (int or None) – Menu version the call requires. Rejected with
stale_versionwhen it differs.expected (dict or None) – Slot UID mapped to saved field values the slot must have now, any subset of the slot snapshot. Every UID must also be in
edits. Checked before the first save and again before each slot. Rejected withstale_slotwhen a value differs.
- Returns:
The slot save result.
- Return type:
- Raises:
TypeError –
edits,expected, a slot’s changes or a slot’s expected values are not mappings;expected_versionis not a non-negative int;modal_inputis not a mapping or names an unknown field.ValueError – The menu UID is missing, invalid or ambiguous; the menu type has its own editor;
expectednames a slot not inedits; a slot UID is malformed; an input name is unknown,modeis"EMPTY",anyisTrue, or a value fails its type check;modal_inputhas a non-finite number or is given for a menu that is not a Modal Operator;use_frameisTruewhile the slot’s resultingexpand_menuisFalse. All of these are checked for every slot before the first save.
Example
pm_uid = pme.create_pm(pme.PmCreationSpec("PMENU", name="Tools Pie")).pm_uid before = pme.editing.read_pm(pm_uid) slot = before["slots"][0] result = pme.editing.update_slots( pm_uid, {slot["uid"]: { "mode": "COMMAND", "name": "Knife", "cmd": "bpy.ops.wm.tool_set_by_id(name='builtin.knife')", "auto_icon": True, }}, expected_version=before["version"], expected={slot["uid"]: slot}, ) assert result["status"] == "committed", result
Notes
Each committed slot increases the menu version once. An
unchangedslot writes nothing: no version change, editor hook or refresh. The comparison uses the values the save would store before the editor’s later normalization, so a value that normalization would change back (for example a background color on a menu type that does not use it) is saved and reportedcommitted; itsbeforeandafterare equal.A
committedslot can carryslot_value_not_retained: the save succeeded, and a requested field does not read back as requested. Check thediagnosticsof committed slots, not onlystatus.An empty slot edited without
modeis saved asCOMMANDand reportsslot_mode_normalized. A blanknamecan be filled from the editor’s suggested name. Read theaftervalue instead of assuming an input stayed empty.The editor normalizes the saved slot.
beforeandaftershow the result. Editor callbacks can change other slots, such as Macro icons, and switching an empty Layout Panel header on adds a slot. These changes appear inside_effectsandstructure_changes.A Command edit in a Pie Menu or Vector Menu keeps the other slots and their order.
An icon-only edit leaves
modeandmenu_target_uidout; the other settings keep their values.A Layout Panel anchor is a Menu slot. A save on an anchor without a body target is rejected with
editor_validation.An exception after a save started keeps its traceback, with a note naming the committed UIDs. A refresh can fail after a slot committed. Call
read_pm()before retrying.The call does not save Preferences to disk, add an Undo step, or run the slot. It is not a raw field write or a JSON import.
See also: Link a child menu and keep its icon flags.
- pme.editing.clear_slots(pm_uid, slot_uids, *, expected_version=None, expected=None)¶
Clear the contents of slots and keep the slots.
Each slot keeps its UID, position and
enabled. Its other saved fields return to the values of an empty slot, through the editor’s normal Clear.- Parameters:
pm_uid (str) – UID of the menu.
slot_uids (iterable of str) – UIDs of the slots to clear, in order. Each UID once.
expected_version (int or None) – Menu version the call requires.
expected (dict or None) – Slot UID mapped to saved field values, as in
update_slots().
- Returns:
The slot save result.
- Return type:
- Raises:
TypeError –
slot_uidsis a string, bytes or a mapping, or contains a value that is not a non-empty string. Other conditions as inupdate_slots().ValueError – A UID appears twice. Other conditions as in
update_slots().
Saved field
Value after Clear
mode"EMPTY"name,icon,text,target_pm_uid,target_pm_fallback_name,menu_presentation,description""auto_icon,menu_sticky_close,exec_undo,description_is_expr,button_background_color_enabledFalsemenu_expand_width-1.0menu_expand_offset_x,menu_expand_offset_y0.0vector_menu_enum_strategy"global"use_property_split_override"inherit"button_background_color[0.0, 0.0, 0.0]Example
before = pme.editing.read_pm(pm_uid, slot_uids=[slot_uid]) result = pme.editing.clear_slots( pm_uid, [slot_uid], expected_version=before["version"], expected={slot_uid: before["slots"][0]}, ) assert result["status"] == "committed", result
Notes
update_slots()does not acceptmode="EMPTY"; Clear is the only way to empty a slot.The editor’s remove hook runs after each clear.
In a Regular Menu, a cleared item becomes a separator; it is not removed.
Layout entries are rejected with
structural_slot; they are edited on Layout rows and panels. A menu type whose editor does not save empty slots returnsclear_unsupported.Each cleared slot increases the menu version once, also when it was already empty. An empty
slot_uidsreturnsunchanged. A refresh can fail after a clear committed; callread_pm()before retrying.The call does not save Preferences to disk or add an Undo step.
- pme.editing.add_slot(pm_uid, *, kind=None, before_uid=None, after_uid=None, expected_version=None, expected=None, use_spacer=False, dry_run=False, header_anchor_uid=None, edge=None)¶
Add one default item through the menu’s normal Add.
The new item’s contents are set with
update_slots(). Its UID isresult["slots"][0]["uid"].- Parameters:
pm_uid (str) – UID of the menu.
kind (str or None) – Kind of item. See Kinds below.
Noneuses the editor’s default.before_uid (str or None) – Insert before this item.
after_uid (str or None) – Insert after this item. At most one of
before_uidandafter_uid; neither appends to the end.expected_version (int or None) – Menu version the call requires.
expected (dict or None) – The complete
expectedreturned by a previous call. It covers every saved item, so it also detects changes made outside versioned operations.use_spacer (bool) – Pop-up Dialog and Floating Panel only.
Trueadds the automatic spacer: before an anchor the order is new item, spacer, anchor; after an anchor it is anchor, spacer, new item. DefaultFalse, regardless of the Preferences setting.dry_run (bool) – Check the addition and return without writing.
header_anchor_uid (str or None) – Pop-up Dialog and Floating Panel only: UID of a Layout Panel anchor, to add into its header. Combine it with exactly one of
before_uid,after_uid(an item of that header) oredge. See Layout rows and panels.edge (str or None) –
"START"or"END"of the header named byheader_anchor_uid.
- Returns:
- Return type:
- Raises:
TypeError –
kindis not a string orNone;expectedis not a mapping; an anchor UID is not a non-empty string;use_spacerordry_runis not a bool;expected_versionis not a non-negative int.ValueError – The menu UID is missing, invalid or ambiguous; both
before_uidandafter_uidare given;header_anchor_uidoredgeis given for a menu that is not a Pop-up Dialog or Floating Panel;edgeis given withoutheader_anchor_uid; a header position is not exactly one;edgeis notSTARTorEND; a list anchor UID is malformed.
Kinds
Menu type
kindNew item
Regular Menu
ITEM(default)COMMANDnamedSlotRegular Menu
LABELLabel:
EMPTY, nameLabel, textlabelRegular Menu
SPACEREMPTY, textspacerRegular Menu
SEPARATOREMPTY, empty textRegular Menu
COLUMNEMPTY, textcolumnPop-up Dialog, Floating Panel
NoneorBUTTONEmpty Command button
Macro Operator, Modal Operator, Stack Key
NoneThe editor’s normal Add item
Any other kind is rejected with
slot_kind_unsupported.Example
Insert an item after the second item of a Regular Menu, checking first:
before = pme.editing.read_pm(pm_uid) anchor_uid = before["slots"][1]["uid"] checked = pme.editing.add_slot( pm_uid, after_uid=anchor_uid, expected_version=before["version"], dry_run=True, ) assert checked["status"] == "validated", checked["diagnostics"] added = pme.editing.add_slot( pm_uid, after_uid=anchor_uid, expected_version=checked["version"], expected=checked["expected"], ) assert added["committed"], added["diagnostics"] new_uid = added["slots"][0]["uid"]
Notes
Existing items keep their UIDs and relative order. Add does not change layout markers.
In a Pop-up Dialog or Floating Panel,
before_uidandafter_uidare exact saved positions; markers between items are not skipped. The automatic spacer appears increated_uids,side_effectsandstructure_changes, not inslots.An empty menu takes an addition without an anchor. A Pop-up Dialog or Floating Panel then gets no row marker.
A fixed-slot menu is rejected with
fixed_slots; useclear_slots(). A list rejectsuse_spacer=Truewithunsupported_position. Regular Menukind="SPACER"is a separate item kind.A dry run returns
validatedorrejectedwithslots=[]. It allocates no UID, does not change saved values or the version, and runs no editor hook or refresh. It does not predict labels, cleanup or hook success. Itsexpectedcan be passed to the same call withoutdry_run.A refresh can fail after the addition committed; call
read_pm()before retrying. The call does not save Preferences to disk or add an Undo step.
- pme.editing.remove_slot(pm_uid, slot_uid, *, expected_version=None, expected=None, dry_run=False)¶
Remove one item through the menu’s normal Remove.
- Parameters:
pm_uid (str) – UID of the menu.
slot_uid (str) – UID of the item.
expected_version (int or None) – Menu version the call requires.
expected (dict or None) – On a list: saved field values the item must have, any subset of its slot snapshot;
{}adds no condition. On a Pop-up Dialog or Floating Panel: the completeexpectedreturned by a previous call.dry_run (bool) – Check the removal and return without writing.
- Returns:
The item operation result. The removed item’s
afterisNone.- Return type:
- Raises:
TypeError –
slot_uidis not a non-empty string;expectedis not a mapping;dry_runis not a bool;expected_versionis not a non-negative int.ValueError – The menu UID is missing, invalid or ambiguous; on a list,
slot_uidis malformed.
Example
checked = pme.editing.remove_slot(pm_uid, slot_uid, dry_run=True) if checked["status"] == "validated": removed = pme.editing.remove_slot( pm_uid, slot_uid, expected_version=checked["version"], expected=checked["expected"], ) print(removed["status"], removed["after_order"])
Notes
A dry run’s
expectedis the target’s full snapshot on a list and the complete collection on a Pop-up Dialog or Floating Panel. Both are validexpectedvalues for the same call withoutdry_run.The last item can be removed, which leaves an empty list. No row or item is added in its place.
Pop-up Dialog and Floating Panel: Remove merges adjacent markers and removes subrow boundaries when the affected row has fewer than two columns. A Layout Panel anchor is rejected with
panel_row; whole rows are removed on Layout rows and panels. The item open in the Slot Editor is rejected withslot_edit_conflict; other drafts, the selection and the clipboard stay.Lists: the editor’s remove hook runs. A rejected operation can still leave callback changes, reported in
side_effects; not every callback is rolled back.A fixed-slot menu is rejected with
fixed_slots; useclear_slots().A dry run returns
validatedorrejectedand shows the target with equalbeforeandafter. It runs no UID repair, editor hook or refresh, and does not change the version. It does not predict cleanup or hook success.A refresh can fail after the removal committed; call
read_pm()before retrying. The call does not save Preferences to disk or add an Undo step.
- pme.editing.move_slot(pm_uid, slot_uid, *, before_uid=None, after_uid=None, expected_version=None, row_ref=None, edge=None, new_row=None, expected=None, use_spacer=False, dry_run=False, header_anchor_uid=None)¶
Move one item to another position in the same menu.
Exactly one position form is given. The item keeps its UID and saved values.
- Parameters:
pm_uid (str) – UID of the menu.
slot_uid (str) – UID of the item.
before_uid (str or None) – Move before this item.
after_uid (str or None) – Move after this item.
expected_version (int or None) – Menu version the call requires.
row_ref (dict or None) – Pop-up Dialog and Floating Panel: a current row reference from
read_pm()["rows"],{"kind": "marker" or "first_item", "slot_uid": ...}. Requiresedge. See Layout rows and panels.edge (str or None) –
"START"or"END"of the row named byrow_ref, or of the header named byheader_anchor_uid.new_row (str or None) – Pop-up Dialog and Floating Panel:
"END"moves the item to a new last row.expected (dict or None) – Pop-up Dialog and Floating Panel only: the complete
expectedreturned by a previous call.use_spacer (bool) – Pop-up Dialog and Floating Panel only.
Trueapplies the normal Move spacer rules. DefaultFalse, regardless of the Preferences setting.dry_run (bool) – Check the move and return without writing.
header_anchor_uid (str or None) – Pop-up Dialog and Floating Panel: UID of a Layout Panel anchor, to move into its header. Combine it with exactly one of
before_uid,after_uidoredge.
- Returns:
- Return type:
- Raises:
TypeError –
slot_uidor an anchor UID is not a non-empty string;row_refdoes not have exactlykindandslot_uid;expectedis given for a menu that is not a Pop-up Dialog or Floating Panel;use_spacerordry_runis not a bool;expected_versionis not a non-negative int.ValueError – The menu UID is missing, invalid or ambiguous; the number of position forms is not one;
edgeis missing, notSTARTorEND, or given withoutrow_reforheader_anchor_uid;new_rowis not"END";row_refhas an invalidkind;header_anchor_uidis given for a list; on a list, a UID is malformed.
Example
Move the last item of a list before the first:
before = pme.editing.read_pm(pm_uid) result = pme.editing.move_slot( pm_uid, before["slots"][-1]["uid"], before_uid=before["slots"][0]["uid"], expected_version=before["version"], ) print(result["status"], result["before_order"], result["after_order"])
Notes
An item already at the requested position, including a self anchor, returns
unchanged. The version does not change and no refresh runs.Other items keep their relative order.
Lists: the editor’s move hook runs on a changed order, including Macro registration. A hook failure restores the order but does not revert every callback effect.
Pop-up Dialog and Floating Panel:
before_uidandafter_uidare exact saved positions, including spacer and column boundaries. Row-end, new-row and item-relative moves run the normal Move cleanup of empty rows and spacers. Layout entries and Layout Panel anchors cannot be moved as items. The selection and an open Slot Editor draft stay with their items.A fixed-slot menu is rejected with
fixed_slots; useswap_slots().row_ref,new_roworuse_spacer=Trueon a list is rejected withunsupported_position.A dry run runs the same checks without writing, hooks or refresh. It does not change saved values, UIDs, the order, the version, the selection or an open Slot Editor draft. It returns
validated,unchangedorrejected;before/afterand the orders stay the saved state and do not predict the move. It does not reserve the position; the call withoutdry_runchecks again.Unknown UIDs and stale versions are rejected before moving. A refresh can fail after the move committed; call
read_pm()before retrying. The call does not save Preferences to disk or add an Undo step.
- pme.editing.swap_slots(pm_uid, slot_uid, other_slot_uid, *, expected_version=None, expected=None, dry_run=False)¶
Exchange the positions of two items in the same menu.
Accepted for Pie Menus, Vector Menus, Pop-up Dialogs and Floating Panels. Each UID moves with its saved values; the items between them stay in place.
- Parameters:
pm_uid (str) – UID of the menu.
slot_uid (str) – UID of the first item.
other_slot_uid (str) – UID of the second item.
expected_version (int or None) – Menu version the call requires.
expected (dict or None) – Pop-up Dialog and Floating Panel only: the complete
expectedreturned by a previous call.dry_run (bool) – Check the exchange and return without writing.
- Returns:
The item operation result, with both items in
slots.- Return type:
- Raises:
TypeError – A UID is not a non-empty string;
dry_runis not a bool;expected_versionis not a non-negative int;expectedis given for a fixed-slot menu.ValueError – The menu UID is missing, invalid or ambiguous; on a fixed-slot menu, a UID is malformed.
Example
before = pme.editing.read_pm(pm_uid) first, third = before["slots"][0]["uid"], before["slots"][2]["uid"] checked = pme.editing.swap_slots( pm_uid, first, third, expected_version=before["version"], dry_run=True, ) if checked["status"] == "validated": result = pme.editing.swap_slots( pm_uid, first, third, expected_version=checked["version"], ) print(result["status"], result["after_order"])
Notes
Both UIDs and the final placement of Menu slots are checked before writing. A successful exchange increases the version once.
The same UID twice returns
unchangedwithout changing the version.A failure of the exchange or of an editor hook restores the order. Field changes made by a hook can remain in the readback.
Pop-up Dialog and Floating Panel: the exchange uses the normal Move owner without Add or Move cleanup. Ordinary and header items, and items of different headers, can be exchanged.
Lists and Sticky Keys are rejected with
slot_swap_unsupported; usemove_slot()for lists.A dry run returns
validated,unchangedorrejectedwithout writing, hooks or refresh. It does not reserve the result.A refresh can fail after the exchange committed; call
read_pm()before retrying. The call does not save Preferences to disk or add an Undo step.
- pme.editing.transfer_slot(source_pm_uid, source_slot_uid, destination_pm_uid, *, destination_slot_uid=None, before_uid=None, after_uid=None, row_ref=None, edge=None, new_row=None, use_spacer=False, header_anchor_uid=None, expected=None, dry_run=False)¶
Move one item’s contents to another menu and report both menus.
The contents,
enabledincluded, follow the normal Paste rules. Both menus are saved before the editor hooks run. The two menus must differ; usemove_slot()orswap_slots()within one menu.- Parameters:
source_pm_uid (str) – UID of the source menu.
source_slot_uid (str) – UID of the item to move.
destination_pm_uid (str) – UID of the destination menu.
destination_slot_uid (str or None) – Fixed-slot destination: an empty slot that receives the contents and keeps its UID.
before_uid (str or None) – List or layout destination: insert before this item.
after_uid (str or None) – List or layout destination: insert after this item.
row_ref (dict or None) – Pop-up Dialog or Floating Panel destination: a current row reference, with
edge. An ordinary row can be empty.edge (str or None) –
"START"or"END"ofrow_refor of the header named byheader_anchor_uid.new_row (str or None) –
"END": a new last row of a Pop-up Dialog or Floating Panel destination.use_spacer (bool) –
Trueapplies the normal Move spacer rules to item-relative and row-end positions. A new last row uses the existing row settings rules and gets no extra spacer. DefaultFalse, regardless of the Preferences setting.header_anchor_uid (str or None) – Layout Panel anchor of the destination header, with
before_uid,after_uidoredge.expected (dict or None) – The complete
expectedreturned by the same transfer’s dry run.Noneskips the comparison; the current state is still checked.dry_run (bool) – Check the transfer and return without writing.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError – A menu or slot UID is not a non-empty string; a destination UID is not a non-empty string or
None;use_spacerordry_runis not a bool;row_refdoes not have exactlykindandslot_uid;expectedhas values of the wrong type or non-JSON values.ValueError – More than one destination form is given;
expectedkeys do not match a transfer snapshot or a version is negative; a layout position is malformed.
Destination
Destination
Position
Fixed slots
destination_slot_uidof an empty slot. A Sticky Key slot is empty when it isCOMMANDwith empty text.List
Exactly one of
before_uid/after_uid. An empty list takes neither. The new item gets a new UID.Pop-up Dialog, Floating Panel
before_uid/after_uid,row_refwithedge, ornew_row="END". An empty menu takes no position. The new item gets a new UID.Layout Panel header
header_anchor_uidwithbefore_uid/after_uidoredge. Required even when Header Layout is on. A header that is off stays off and reportsheader_layout_disabled.Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".moveddict or None
After a commit:
fromandto, each withpm_uidandslot_uid.to.slot_uidis the receiving item.expecteddict or None
Opaque snapshot of both menus, the target arguments and the linked menu facts. It survives a JSON round trip.
Nonewhen the call was rejected before the source slot was found.effectslist[dict]
Predicted and observed effects. See Effects.
losslist[dict]
Values that are not transferred. See Notes.
diagnosticslist[dict]
codeand details. See Diagnostics.from,todict
One side each:
pm_uid;beforeandafter, the saved item collection;changed;version_beforeandversion_after.toaddsinsertion_position. A Pop-up Dialog or Floating Panel side addsbefore_rowsandafter_rows. Unreadableaftervalues areNone.Status
statusMeaning
validateddry_run=Trueand the transfer is acceptable. Nothing was written.committedBoth menus are saved. Each menu’s version increased once.
rejectedNothing was written.
diagnosticsnames the cause.restored_failureA write failed and both saved item collections match their prior snapshots. Macro registration is reported in
effects.unknownA write failed and the restore or readback could not confirm the prior state. Call
read_pm()before deciding; do not retry automatically.Effects
kindValue
predictiondestination_fields: the saved fields the destination will receive,enabledincluded.icon_predictionis"dynamic"when the destination computes the icon, otherwise"known".registrationMacro Operator registration,
phasebefore,afterorrecovery, withpm_uidand the observed state.hookAn editor hook that ran:
pm_uidandhook.recoverysaved_restored: whether both menus were restored after a failure.Diagnostics
codeCause, and extra keys
menu_identity_unconfirmedA menu UID does not resolve to one menu.
same_menuThe source and destination are the same menu.
slot_transfer_unsupportedA menu type has its own editor or no slot clipboard.
source_identity_unconfirmedsource_slot_uidis not in the source menu.stale_transferexpecteddiffers from the current snapshot.source_has_no_contentThe source slot is empty.
popup_position_requires_popup_menuA layout position is given for a destination that is not a Pop-up Dialog or Floating Panel.
sticky_slot_role_invalidA Sticky Key slot is not On Press or On Release.
paste_mode_unsupportedThe destination does not accept this slot mode from this menu type.
destination_identity_unconfirmed,destination_occupieddestination_slot_uidis not found, or is not empty.destination_slot_requires_fixed_menudestination_slot_uidis given for a list or layout destination.anchor_identity_unconfirmed,destination_anchor_requiredThe anchor is not found, or a non-empty destination got no position.
slot_not_found,structural_slot,panel_row,row_not_found,position_not_found,panel_anchor_not_found,header_target_mismatch,header_role_requiredThe layout source or position is invalid, as in Item operation results.
menu_reference_slot_incompatible,menu_reference_target_mode_not_allowed,menu_reference_self_reference,menu_reference_presentation_not_supportedA Menu slot’s resolved link is not valid at the destination.
menu_reference_unresolvedWarning: the link is missing or ambiguous and keeps its raw value.
kind.slot_edit_conflictThe Slot Editor has an affected item open: the source, a fixed destination, or a layout entry that cleanup would remove or rewrite.
header_layout_disabledWarning: a header involved has Header Layout off.
anchor_uid.slot_transfer_failedA write raised.
exception_typeandmessage.slot_transfer_restore_failed,slot_transfer_registration_restore_failedThe restore raised.
statusisunknown.transfer_snapshot_failed,transfer_cleanup_failedReading the menus or planning the cleanup raised.
transfer_readback_failed,transfer_rows_readback_failedReading a side after the call raised.
side. That side’safterorafter_rowsisNone; the status stays. Read the menu again instead of repeating a committed transfer.transfer_refresh_failedA refresh raised after the call.
operation. A committed status stays.macro_registration_read_failedReading Macro registration raised.
Example
Move an item to the end of a list or layout menu, checking first:
destination = pme.editing.read_pm(destination_pm_uid) position = ({"after_uid": destination["slots"][-1]["uid"]} if destination["slots"] else {}) checked = pme.editing.transfer_slot( source_pm_uid, source_slot_uid, destination_pm_uid, **position, dry_run=True, ) if checked["status"] == "validated": result = pme.editing.transfer_slot( source_pm_uid, source_slot_uid, destination_pm_uid, **position, expected=checked["expected"], ) print(result["status"], result["moved"], result["effects"], result["loss"])
For a fixed destination,
positionis{"destination_slot_uid": empty_slot_uid}. For a Panel header, it is{"header_anchor_uid": anchor_uid, "edge": "END"}. For an ordinary row, it is{"row_ref": row_ref, "edge": "END"}.Notes
A fixed source is cleared and keeps its UID and
enabled. A Sticky Key source also gets back its On Press or On Release name and an empty command. A list source is removed, even when it is the last item.layout_panelis not transferred. It stays on a fixed source and is lost with a removed list source.lossreports it:kind"layout_panel",value,transferred(False) andsource_removed.The destination editor’s icon rule applies: Pop-up Dialogs and Floating Panels keep icon flags, Macro Operators compute the icon, other types drop the flags. A button background color is cleared where the destination does not use it.
Regular Menu labels and layout markers can be anchors but not the item transferred. A Layout Panel anchor cannot be transferred; its header items can, also from a header that is off.
Layout cleanup covers the insertion and removal boundaries and an emptied source row; unrelated empty rows and distant spacers stay. When the markerless first row becomes empty, the next row marker is absorbed, as in Move. This differs from
remove_row(). Moving the last content out can leave an empty menu; moving the last header item out keeps the anchor and its empty header. Read row references again after a transfer.A missing or ambiguous menu link keeps its raw value with
menu_reference_unresolved. A uniquely resolved link that is not valid at the destination is rejected before writing.The Slot Editor draft of an affected item rejects the call. Other drafts, the clipboard and the selection stay.
A dry run allocates no UID, does not initialize a version, and runs no editor hook or refresh.
beforeandafterare the unchanged saved values, and the cleanup and new UIDs are not predicted. Macro icons and registration are observed only after the call.A refresh failure keeps a committed status. The call does not save Preferences to disk or add an Undo step.