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

read_pm()

Returns the menu’s slots under slots, as described in Slot snapshot.

slot_fields()

Describes the inputs update_slots() accepts.

read_slot_inputs()

Returns slots under those input names.

resolve_auto_icons()

Reports whether Auto Icon finds an icon for each slot.

update_slots()

Changes slot contents through the Slot Editor’s save.

clear_slots()

Clears slot contents and keeps the slots.

add_slot()

Adds one default item.

remove_slot()

Removes one item.

move_slot()

Moves one item within its menu.

swap_slots()

Exchanges two items.

transfer_slot()

Moves one item’s contents to another menu.

Slots by menu type¶

The menu type decides which operations apply. read_pm()["editable_slots"] is False for the types in the last row; their slots are edited by their own operations.

Menu type

Slots

Slot modes offered

Operations

Pie Menu (PMENU), Vector Menu (VMENU)

Fixed

COMMAND, PROP, MENU, HOTKEY, CUSTOM

update_slots(), clear_slots(), swap_slots(), transfer_slot()

Sticky Key (STICKY)

Fixed: On Press, On Release

COMMAND, HOTKEY

update_slots(), transfer_slot()

Regular Menu (RMENU)

List

COMMAND, PROP, MENU, HOTKEY, CUSTOM

update_slots(), clear_slots(), add_slot(), remove_slot(), move_slot(), transfer_slot()

Stack Key (SCRIPT)

List

COMMAND, HOTKEY

update_slots(), add_slot(), remove_slot(), move_slot(), transfer_slot()

Macro Operator (MACRO)

List

COMMAND, MENU

update_slots(), add_slot(), remove_slot(), move_slot(), transfer_slot()

Modal Operator (MODAL)

List

COMMAND, PROP, INVOKE, FINISH, CANCEL, UPDATE

update_slots(), add_slot(), remove_slot(), move_slot(), transfer_slot() between Modal Operators

Pop-up Dialog (DIALOG), Floating Panel (FPANEL)

Rows (Layout rows and panels)

COMMAND, PROP, MENU, HOTKEY, CUSTOM

All slot operations on this page

Panel Group (PANEL), Hidden Panel Group (HPANEL), Property (PROPERTY), Property Stack (CONDITION), Context Router (ROUTER)

Own editor

—

None. Context Routers use update_router(); Property callbacks are not slots.

Slot modes offered are the modes of the Slot Editor’s mode selector. The Sticky Key, Stack Key, Macro Operator and Modal Operator editors do not save empty slots; clear_slots() returns clear_unsupported there. For the types with their own editor, update_slots() and clear_slots() raise ValueError and the other operations are rejected.

A menu created by pme.create_pm() starts with its editor’s default slots: a Macro Operator has one empty Command step, and a Modal Operator has one On Invoke slot. Further slots are added with add_slot().

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

uid

str

Slot UID. Unique within its menu.

index

int

Position in the menu’s saved slot list, from 0. Layout entries count.

enabled

bool

Whether the slot is enabled. Not an input of update_slots().

layout_panel

dict or None

On a Layout Panel anchor: idname (str), default_closed (bool) and use_header_layout (bool). None on other slots.

name

str

Label.

icon

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.

mode

str

EMPTY, COMMAND, PROP, MENU, HOTKEY, CUSTOM, or for a Modal Operator INVOKE, FINISH, CANCEL, UPDATE.

auto_icon

bool

Auto Icon. Saved as True only on a Command slot.

text

str

Stored body. Its meaning depends on mode. See Text by mode.

target_pm_uid

str

Menu slot: UID of the linked menu. Empty for a link saved by name only and for other modes.

target_pm_fallback_name

str

Menu slot: last known name of the linked menu.

menu_presentation

str

Menu slot linking a Regular Menu: BUTTON (Open on Selection), SUBMENU or INLINE (Expand Contents). Empty for other targets and for data saved before this field existed.

menu_sticky_close

bool

Menu slot: close the Vector Menu when the link starts a Sticky Key.

menu_expand_width

float

Menu slot: width of the expanded menu in pixels. -1 uses the natural width.

menu_expand_offset_x, menu_expand_offset_y

float

Menu slot: offset of the expanded menu in pixels.

exec_undo

bool

Command slot: add an Undo step after running a command that is not a Blender operator.

description

str

Tooltip text, or Python code when description_is_expr is True.

description_is_expr

bool

Run description as Python and show the returned text.

vector_menu_enum_strategy

str

Vector Menu enum presentation for this slot: global, hover or virtual_nest.

use_property_split_override

str

Property Split for this slot: inherit, on or off. Used by Property slots in Pop-up Dialogs and Floating Panels.

button_background_color_enabled

bool

Use button_background_color. Used by Command slots in Floating Panels and Vector Menus.

button_background_color

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.

mode

text

Input

EMPTY

Empty for an empty slot. In a Regular Menu, a layout entry: "" separator, "label" label (name holds its text), "spacer" spacer, "column" column break. In a Pop-up Dialog or Floating Panel, a row marker (row with settings after ?) or a spacer (spacer?...), described on Layout rows and panels.

clear_slots(), add_slot()

COMMAND

Python code run when the slot is used.

cmd

PROP

Data path of a Blender property, for example C.scene.tool_settings.use_snap.

prop

MENU

Name of the linked menu, with an optional @ or @@ prefix. See Menu slot text.

menu_target_uid, expand_menu, use_frame

HOTKEY

Hotkey string: modifiers ctrl, shift, alt, oskey, then a key modifier, then the key, joined by +. Example: ctrl+A.

key, ctrl, shift, alt, oskey, key_mod

CUSTOM

Python code that draws a custom layout.

custom

INVOKE, FINISH, CANCEL, UPDATE

Modal Operator: Python code run when the operator is invoked, confirmed, cancelled or updated.

cmd

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.

Button background color¶

button_background_color is saved in scene linear color, as Blender’s own color properties are, and converted to sRGB when the button is drawn. A value taken from a hex code or an sRGB color is converted before it is written. Written unchanged, it is drawn lighter than the source color.

def srgb_to_linear(channel):
    if channel <= 0.04045:
        return channel / 12.92
    return ((channel + 0.055) / 1.055) ** 2.4

# sRGB #A83636
color = [srgb_to_linear(value / 255) for value in (0xA8, 0x36, 0x36)]
pme.editing.update_slots(pm_uid, {slot_uid: {
    "button_background_color_enabled": True,
    "button_background_color": color,
}})
  • The color is drawn only while button_background_color_enabled is True.

  • The button’s text color does not change. Whether the text stays readable on the chosen color is checked by the author, against the theme’s button text color (bpy.context.preferences.themes[0].user_interface.wcol_tool.text) and in the drawn menu.

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

mode

str

mode

Slot mode. EMPTY is not accepted. The modes each menu type offers are listed in Slots by menu type.

name

str

name

Label.

icon

str

icon

Flags and icon name. See Icon value.

auto_icon

bool

auto_icon

Auto Icon. Kept only on a Command slot.

cmd

str

text

Python code of a COMMAND, INVOKE, FINISH, CANCEL or UPDATE slot.

prop

str

text

Property data path of a PROP slot.

custom

str

text

Layout code of a CUSTOM slot.

exec_undo

bool

exec_undo

Undo step for a Command slot.

menu

str

text, target_pm_uid

Linked menu, by name or UID. Resolved to target_pm_uid when found.

menu_target_uid

str

target_pm_uid

UID of the linked menu. When not empty it replaces menu.

menu_target_fallback_name

str

—

Name used to resolve a link whose UID no longer exists. The saved target_pm_fallback_name is the resolved menu’s name.

menu_presentation

str

menu_presentation

BUTTON, SUBMENU or INLINE. Saved only for a Regular Menu target.

menu_sticky_close

bool

menu_sticky_close

Close the Vector Menu when the link starts a Sticky Key.

expand_menu

bool

@ prefix of text

Expand the linked menu. See Menu slot text.

use_frame

bool

@@ prefix of text

Draw a frame around the expanded menu.

menu_expand_width

float

menu_expand_width

Width of the expanded menu; -1 uses the natural width.

menu_expand_offset_x, menu_expand_offset_y

float

same name

Offset of the expanded menu.

key

str

text

Hotkey slot: key, a Blender event type such as A.

ctrl, shift, alt, oskey

bool

text

Hotkey slot: modifier keys.

key_mod

str

text

Hotkey slot: a regular key held as a modifier, or NONE.

any

bool

—

Read from a saved hotkey. No slot saves it, so only False is accepted; True raises ValueError.

description

str

description

Tooltip text or code.

description_is_expr

bool

description_is_expr

Run the description as Python.

vector_menu_enum_strategy

str

same name

global, hover or virtual_nest.

use_property_split_override

str

same name

inherit, on or off.

button_background_color_enabled

bool

same name

Use the button background color.

button_background_color

list[float]

same name

Three numbers from 0.0 to 1.0, in scene linear color. See Button background color.

layout_panel_default_closed

bool

layout_panel["default_closed"]

Layout Panel anchor: show the panel closed the first time.

layout_panel_use_header_layout

bool

layout_panel["use_header_layout"]

Layout Panel anchor: allow slots in the panel header. Switching an empty header from False to True adds one button to it. Saving True on a header that is already on does not add one.

modal_input

dict

icon

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.

Slot save results¶

update_slots() and clear_slots() return the same result. The status words are defined on Results and guards.

Key

Type

Value

status

str

See Status below.

committed

bool

True only when status is "committed".

pm_uid

str

The pm_uid argument.

version

int

Menu version after the call.

slots

list[dict]

One entry per attempted slot, in request order. See Slot entry.

pending

list[str]

UIDs whose save was not attempted. Earlier editor callbacks can still have changed them.

diagnostics

list[dict]

Request-level problems found before the first save.

structure_changes

dict

Present when the slot order changed: before_order and after_order, lists of slot UIDs.

side_effects

list[dict]

Present when slots not in slots changed, pending slots included: uid, before and after per slot.

Slot entry

Key

Type

Value

uid

str

Slot UID.

status

str

committed, unchanged or rejected. unchanged: the changes are empty, or saving them would leave the slot’s saved values as they are; nothing was written for the slot.

before

dict

Slot snapshot at the start of the call.

after

dict or None

Slot snapshot after the call. None when the slot no longer exists.

reports

list

(level, message) pairs from the save, such as a refresh warning.

diagnostics

list[dict]

Problems and warnings for this slot. Absent on unchanged.

Status

status

Meaning

committed

At least one slot is committed and none was rejected. The others are unchanged.

unchanged

Every requested slot is unchanged, or the request is empty. Nothing was written; the version does not change and no refresh runs.

partial

At least one slot committed, then a slot was rejected. Later slots are in pending.

rejected

No slot committed. diagnostics or the slot entry names the cause.

Diagnostics

code

Cause, and extra keys

stale_version

expected_version differs from the menu version. expected and actual.

slot_not_found

A slot UID is not in the menu. pmi_uid.

stale_slot

A value in expected differs from the saved value. pmi_uid and fields.

clear_unsupported

clear_slots(): the editor does not save empty slots. pmi_uid.

structural_slot

clear_slots(): the slot is a layout entry. pmi_uid.

invalid_syntax

cmd, custom or prop does not compile. field, message, line and column. Nothing is saved for the slot.

editor_validation

The Slot Editor’s check refused the input. message is the editor’s text.

save_rejected

The save was refused without another diagnostic. route.

clear_rejected

The clear was refused. route.

slot_mode_normalized

Warning: an empty slot edited without mode was saved with a mode. field, before and after.

icon_not_found

Warning: the saved icon name is not a known icon. field and value.

slot_value_not_retained

Warning: the slot was saved, but the slot read back under input names (as read_slot_inputs() returns it) does not have the requested value. field, requested and actual. One entry per field. modal_input is not compared.

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

status

str

See Status below.

committed

bool

True only when status is "committed".

pm_uid

str

The pm_uid argument.

version

int

Menu version after the call.

slots

list[dict]

The target items: uid, status, before, after and reports. An added item’s before and a removed item’s after are None.

pending

list

Always empty.

diagnostics

list[dict]

code and details. See Diagnostics below.

before_order, after_order

list[str]

Slot UIDs in saved order before and after the call.

side_effects

list[dict]

Other items whose snapshot changed, including a changed index: uid, before, after. Lists and fixed slots include the key only when not empty.

expected

dict

Snapshot to pass back as expected. Returned by every add_slot() call, by a remove_slot() dry run, and by every Pop-up Dialog or Floating Panel call.

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

version_before, version_after

int

Menu version before and after the call.

before_rows, after_rows

list[dict] or None

Rows before and after. after_rows is None when it could not be read.

insertion_position

dict or None

The resolved gap in the saved order before the call. None for exchanges, removals and early rejections.

created_uids, deleted_uids, moved_uids

list[str]

Items added, removed, or with a changed index.

structure_changes

list[dict]

Actual row and layout entry changes, cleanup included.

recovery

str

not_needed, restored or unknown.

Status

status

Meaning

committed

The change is saved and the version increased once.

validated

dry_run=True and the operation is acceptable. Nothing was written.

unchanged

move_slot() and swap_slots(): the item is already at that position. The version does not change.

rejected

Nothing was written. diagnostics names the cause.

restored_failure

Pop-up Dialog and Floating Panel: a write failed and the saved items and order were restored.

unknown

Pop-up Dialog and Floating Panel: a write failed and the restore could not be confirmed. Call read_pm() before retrying.

Diagnostics

code

Cause, and extra keys

stale_version

expected_version differs from the menu version. Lists and fixed slots add expected and actual.

stale_snapshot

add_slot() on a list: expected differs from the saved collection.

stale_slot

remove_slot() on a list: a value in expected differs. pmi_uid and fields.

stale_popup

Pop-up Dialog or Floating Panel: expected differs from the saved collection.

slot_not_found

The target or anchor UID is not in the menu. Lists add pmi_uid.

fixed_slots

add_slot(), remove_slot() or move_slot() on a fixed-slot menu.

slot_membership_unsupported, slot_move_unsupported, slot_swap_unsupported

The menu type does not support this operation. See Slots by menu type.

slot_kind_unsupported

add_slot(): kind is not accepted. available lists the kinds; lists also add kind.

unsupported_position

use_spacer=True, row_ref or new_row on a menu that is not a Pop-up Dialog or Floating Panel.

menu_reference_slot_incompatible

swap_slots(): a Menu slot would land on a slot that does not accept its target.

structural_slot

A layout entry cannot be moved or exchanged as an item.

panel_row

The item is a Layout Panel anchor, or the position is inside a Layout Panel row without a header position.

panel_anchor_not_found, header_target_mismatch, header_role_required

The Layout Panel header position is invalid. See Layout rows and panels.

row_not_found, position_not_found

row_ref or the resolved position does not exist.

invalid_slot_identity, item_identity_unconfirmed

Saved slot UIDs are missing, invalid or duplicated.

slot_edit_conflict

remove_slot(): the Slot Editor has the target open.

header_layout_disabled

Warning: the item is in, or goes to, a header whose Header Layout is off. anchor_uid.

target_index_out_of_range, target_rejected, document_version_rejected, dry_run_rejected

Lists and fixed slots: the normal operation refused the change.

apply_failed, post_apply_failed

Lists and fixed slots: the change or its editor hook raised, and the order was restored. The traceback is printed to the console.

popup_add_failed, popup_remove_failed, popup_move_failed

The write raised. exception_type and message. See recovery.

popup_restore_failed

The restore after a failed write raised. status is unknown.

refresh_failed

The editor refresh raised after the write. The saved status stays.

popup_readback_failed

The final readback raised. after_order or after_rows is None and the changed UID lists are empty.

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

update_slots(), clear_slots()

expected_version, and expected mapping each slot UID to any subset of its slot snapshot.

add_slot()

expected_version, and the complete expected returned by a previous call.

remove_slot() on a list

expected_version, and expected with any subset of the target’s snapshot. The dry run returns all of it.

remove_slot(), move_slot(), swap_slots() on a Pop-up Dialog or Floating Panel

expected_version, and the complete expected returned by a previous call.

move_slot() on a list, swap_slots() on fixed slots

expected_version only. expected raises TypeError.

transfer_slot()

The complete expected returned by the same transfer’s dry run, covering both menus. No expected_version.

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.

Returns:

Input name mapped to a description.

Return type:

dict[str, dict]

Each description has these keys:

Key

Present for

Value

type

all

"STRING", "BOOLEAN", "ENUM", "FLOAT", or "mapping" for modal_input

description

all except modal_input

The editor’s tooltip text. Empty for some inputs.

values

ENUM

Accepted identifiers. mode does not list EMPTY.

length

array inputs

Number of items: 3 for button_background_color

fields

modal_input

Field 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, prop or custom, a Menu slot’s prefix as expand_menu and use_frame, a hotkey split into key and modifiers.

Parameters:
  • pm_uid (str) – UID of the menu.

  • slot_uids (iterable of str or None) – UIDs of the slots to return. None returns every slot.

Returns:

pm_uid and slots.

Return type:

dict

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_uid

str

The pm_uid argument.

slots

list[dict]

In saved order: uid, index and edit per slot.

edit

dict or None

Every name in Slot input fields except modal_input; a Modal Operator slot adds modal_input. None for 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

  • edit can be passed to update_slots() unchanged, for the same slot or another one. Passed back to its own slot, it returns unchanged without writing.

  • A Hotkey slot whose saved text contains any reads any=True. Set it to False before passing edit back: no slot saves any, and update_slots() raises ValueError for True.

  • On a Menu slot that links a Regular Menu, menu_presentation is the saved value, or the value read from the @ prefix when none is saved. Other slots read BUTTON.

  • 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:
  • pm_uid (str) – UID of the menu.

  • slot_uids (iterable of str or None) – UIDs of the slots to report. None reports every slot.

Returns:

pm_uid and slots.

Return type:

dict

Raises:

ValueError – The menu UID is missing, invalid or ambiguous, or a requested slot UID is not in the menu.

Result

slots lists the slots in saved order. Each entry has these keys:

Key

Type

Value

uid, index

str, int

Slot UID and position.

auto_icon

bool

True when the slot is a Command slot with Auto Icon on.

source

dict or None

What the command names for an icon. None when auto_icon is False or the command is not a single tool or brush activation.

resolved

bool

True when the lookup finds an icon.

manual_icon

str

The saved icon. The slot shows it when resolved is False.

source has these keys:

kind

Key

Value

"tool"

tool

Tool identifier, such as builtin.knife.

"tool"

space_type

Space type named in the command, or None.

"asset"

asset

Brush asset identifier, relative to its library.

"asset"

library_type, library_identifier

Library 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_version when 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 with stale_slot when a value differs.

Returns:

The slot save result.

Return type:

dict

Raises:
  • TypeError – edits, expected, a slot’s changes or a slot’s expected values are not mappings; expected_version is not a non-negative int; modal_input is not a mapping or names an unknown field.

  • ValueError – The menu UID is missing, invalid or ambiguous; the menu type has its own editor; expected names a slot not in edits; a slot UID is malformed; an input name is unknown, mode is "EMPTY", any is True, or a value fails its type check; modal_input has a non-finite number or is given for a menu that is not a Modal Operator; use_frame is True while the slot’s resulting expand_menu is False. 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 unchanged slot 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 reported committed; its before and after are equal.

  • A committed slot can carry slot_value_not_retained: the save succeeded, and a requested field does not read back as requested. Check the diagnostics of committed slots, not only status.

  • An empty slot edited without mode is saved as COMMAND and reports slot_mode_normalized. A blank name can be filled from the editor’s suggested name. Read the after value instead of assuming an input stayed empty.

  • The editor normalizes the saved slot. before and after show 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 in side_effects and structure_changes.

  • A Command edit in a Pie Menu or Vector Menu keeps the other slots and their order.

  • An icon-only edit leaves mode and menu_target_uid out; 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:

dict

Raises:

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_enabled

False

menu_expand_width

-1.0

menu_expand_offset_x, menu_expand_offset_y

0.0

vector_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 accept mode="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 returns clear_unsupported.

  • Each cleared slot increases the menu version once, also when it was already empty. An empty slot_uids returns unchanged. A refresh can fail after a clear committed; call read_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 is result["slots"][0]["uid"].

Parameters:
  • pm_uid (str) – UID of the menu.

  • kind (str or None) – Kind of item. See Kinds below. None uses 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_uid and after_uid; neither appends to the end.

  • expected_version (int or None) – Menu version the call requires.

  • expected (dict or None) – The complete expected returned 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. True adds the automatic spacer: before an anchor the order is new item, spacer, anchor; after an anchor it is anchor, spacer, new item. Default False, 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) or edge. See Layout rows and panels.

  • edge (str or None) – "START" or "END" of the header named by header_anchor_uid.

Returns:

The item operation result.

Return type:

dict

Raises:
  • TypeError – kind is not a string or None; expected is not a mapping; an anchor UID is not a non-empty string; use_spacer or dry_run is not a bool; expected_version is not a non-negative int.

  • ValueError – The menu UID is missing, invalid or ambiguous; both before_uid and after_uid are given; header_anchor_uid or edge is given for a menu that is not a Pop-up Dialog or Floating Panel; edge is given without header_anchor_uid; a header position is not exactly one; edge is not START or END; a list anchor UID is malformed.

Kinds

Menu type

kind

New item

Regular Menu

ITEM (default)

COMMAND named Slot

Regular Menu

LABEL

Label: EMPTY, name Label, text label

Regular Menu

SPACER

EMPTY, text spacer

Regular Menu

SEPARATOR

EMPTY, empty text

Regular Menu

COLUMN

EMPTY, text column

Pop-up Dialog, Floating Panel

None or BUTTON

Empty Command button

Macro Operator, Modal Operator, Stack Key

None

The 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_uid and after_uid are exact saved positions; markers between items are not skipped. The automatic spacer appears in created_uids, side_effects and structure_changes, not in slots.

  • 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; use clear_slots(). A list rejects use_spacer=True with unsupported_position. Regular Menu kind="SPACER" is a separate item kind.

  • A dry run returns validated or rejected with slots=[]. 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. Its expected can be passed to the same call without dry_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 complete expected returned by a previous call.

  • dry_run (bool) – Check the removal and return without writing.

Returns:

The item operation result. The removed item’s after is None.

Return type:

dict

Raises:
  • TypeError – slot_uid is not a non-empty string; expected is not a mapping; dry_run is not a bool; expected_version is not a non-negative int.

  • ValueError – The menu UID is missing, invalid or ambiguous; on a list, slot_uid is 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 expected is the target’s full snapshot on a list and the complete collection on a Pop-up Dialog or Floating Panel. Both are valid expected values for the same call without dry_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 with slot_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; use clear_slots().

  • A dry run returns validated or rejected and shows the target with equal before and after. 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": ...}. Requires edge. See Layout rows and panels.

  • edge (str or None) – "START" or "END" of the row named by row_ref, or of the header named by header_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 expected returned by a previous call.

  • use_spacer (bool) – Pop-up Dialog and Floating Panel only. True applies the normal Move spacer rules. Default False, 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_uid or edge.

Returns:

The item operation result.

Return type:

dict

Raises:
  • TypeError – slot_uid or an anchor UID is not a non-empty string; row_ref does not have exactly kind and slot_uid; expected is given for a menu that is not a Pop-up Dialog or Floating Panel; use_spacer or dry_run is not a bool; expected_version is not a non-negative int.

  • ValueError – The menu UID is missing, invalid or ambiguous; the number of position forms is not one; edge is missing, not START or END, or given without row_ref or header_anchor_uid; new_row is not "END"; row_ref has an invalid kind; header_anchor_uid is 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_uid and after_uid are 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; use swap_slots(). row_ref, new_row or use_spacer=True on a list is rejected with unsupported_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, unchanged or rejected; before / after and the orders stay the saved state and do not predict the move. It does not reserve the position; the call without dry_run checks 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 expected returned 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:

dict

Raises:
  • TypeError – A UID is not a non-empty string; dry_run is not a bool; expected_version is not a non-negative int; expected is 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 unchanged without 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; use move_slot() for lists.

  • A dry run returns validated, unchanged or rejected without 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, enabled included, follow the normal Paste rules. Both menus are saved before the editor hooks run. The two menus must differ; use move_slot() or swap_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" of row_ref or of the header named by header_anchor_uid.

  • new_row (str or None) – "END": a new last row of a Pop-up Dialog or Floating Panel destination.

  • use_spacer (bool) – True applies 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. Default False, regardless of the Preferences setting.

  • header_anchor_uid (str or None) – Layout Panel anchor of the destination header, with before_uid, after_uid or edge.

  • expected (dict or None) – The complete expected returned by the same transfer’s dry run. None skips 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:

dict

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_spacer or dry_run is not a bool; row_ref does not have exactly kind and slot_uid; expected has values of the wrong type or non-JSON values.

  • ValueError – More than one destination form is given; expected keys do not match a transfer snapshot or a version is negative; a layout position is malformed.

Destination

Destination

Position

Fixed slots

destination_slot_uid of an empty slot. A Sticky Key slot is empty when it is COMMAND with 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_ref with edge, or new_row="END". An empty menu takes no position. The new item gets a new UID.

Layout Panel header

header_anchor_uid with before_uid / after_uid or edge. Required even when Header Layout is on. A header that is off stays off and reports header_layout_disabled.

Result

Key

Type

Value

status

str

See Status below.

committed

bool

True only when status is "committed".

moved

dict or None

After a commit: from and to, each with pm_uid and slot_uid. to.slot_uid is the receiving item.

expected

dict or None

Opaque snapshot of both menus, the target arguments and the linked menu facts. It survives a JSON round trip. None when the call was rejected before the source slot was found.

effects

list[dict]

Predicted and observed effects. See Effects.

loss

list[dict]

Values that are not transferred. See Notes.

diagnostics

list[dict]

code and details. See Diagnostics.

from, to

dict

One side each: pm_uid; before and after, the saved item collection; changed; version_before and version_after. to adds insertion_position. A Pop-up Dialog or Floating Panel side adds before_rows and after_rows. Unreadable after values are None.

Status

status

Meaning

validated

dry_run=True and the transfer is acceptable. Nothing was written.

committed

Both menus are saved. Each menu’s version increased once.

rejected

Nothing was written. diagnostics names the cause.

restored_failure

A write failed and both saved item collections match their prior snapshots. Macro registration is reported in effects.

unknown

A write failed and the restore or readback could not confirm the prior state. Call read_pm() before deciding; do not retry automatically.

Effects

kind

Value

prediction

destination_fields: the saved fields the destination will receive, enabled included. icon_prediction is "dynamic" when the destination computes the icon, otherwise "known".

registration

Macro Operator registration, phase before, after or recovery, with pm_uid and the observed state.

hook

An editor hook that ran: pm_uid and hook.

recovery

saved_restored: whether both menus were restored after a failure.

Diagnostics

code

Cause, and extra keys

menu_identity_unconfirmed

A menu UID does not resolve to one menu.

same_menu

The source and destination are the same menu.

slot_transfer_unsupported

A menu type has its own editor or no slot clipboard.

source_identity_unconfirmed

source_slot_uid is not in the source menu.

stale_transfer

expected differs from the current snapshot.

source_has_no_content

The source slot is empty.

popup_position_requires_popup_menu

A layout position is given for a destination that is not a Pop-up Dialog or Floating Panel.

sticky_slot_role_invalid

A Sticky Key slot is not On Press or On Release.

paste_mode_unsupported

The destination does not accept this slot mode from this menu type.

destination_identity_unconfirmed, destination_occupied

destination_slot_uid is not found, or is not empty.

destination_slot_requires_fixed_menu

destination_slot_uid is given for a list or layout destination.

anchor_identity_unconfirmed, destination_anchor_required

The 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_required

The 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_supported

A Menu slot’s resolved link is not valid at the destination.

menu_reference_unresolved

Warning: the link is missing or ambiguous and keeps its raw value. kind.

slot_edit_conflict

The Slot Editor has an affected item open: the source, a fixed destination, or a layout entry that cleanup would remove or rewrite.

header_layout_disabled

Warning: a header involved has Header Layout off. anchor_uid.

slot_transfer_failed

A write raised. exception_type and message.

slot_transfer_restore_failed, slot_transfer_registration_restore_failed

The restore raised. status is unknown.

transfer_snapshot_failed, transfer_cleanup_failed

Reading the menus or planning the cleanup raised.

transfer_readback_failed, transfer_rows_readback_failed

Reading a side after the call raised. side. That side’s after or after_rows is None; the status stays. Read the menu again instead of repeating a committed transfer.

transfer_refresh_failed

A refresh raised after the call. operation. A committed status stays.

macro_registration_read_failed

Reading 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, position is {"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_panel is not transferred. It stays on a fixed source and is lost with a removed list source. loss reports it: kind "layout_panel", value, transferred (False) and source_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. before and after are 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.