Hotkeys¶

A menu’s hotkey binding is 13 saved fields. They are read with read_pm() and changed with update_hotkey(), which reports Blender’s keymap registration separately from the saved values. Hotkey Modes are described under Hotkey Mode, the editor under Hotkey settings.

Function

Purpose

read_pm()

Returns the saved binding under hotkey.

update_hotkey()

Changes the binding and reports registration.

Reading the hotkey¶

read_pm(pm_uid)["hotkey"] maps each field name to its saved value. Every menu type returns it. Reading does not normalize values or touch Blender’s keymaps.

>>> pme.editing.read_pm(pm_uid)["hotkey"]
{'key': 'F6', 'key_mod': 'NONE', 'ctrl': True, 'shift': False, 'alt': False,
 'oskey': False, 'any': False, 'open_mode': 'PRESS', 'km_name': 'Window',
 'chord': 'NONE', 'drag_dir': 'ANY', 'tweak_dir': 'ANY', 'repeat': False}

Hotkey fields¶

Field

Type

Accepted values

Default

Meaning

key

str

Identifier of bpy.types.Event.type, or NONE

NONE

Key or button that invokes the menu. NONE: no hotkey.

key_mod

str

Identifier of bpy.types.Event.type, or NONE

NONE

Key held as a modifier (Key Modifier). A mouse button (LEFTMOUSE, MIDDLEMOUSE, RIGHTMOUSE, BUTTON4MOUSE to BUTTON7MOUSE) is tracked by a separate PME observer keymap item.

ctrl

bool

True, False

False

Ctrl held.

shift

bool

True, False

False

Shift held.

alt

bool

True, False

False

Alt held.

oskey

bool

True, False

False

OS key held.

any

bool

True, False

False

Match regardless of modifier keys (Any Modifier). The keymap item then ignores the four modifier fields.

open_mode

str

PRESS, HOLD, DOUBLE_CLICK, TWEAK, CHORDS, CLICK, CLICK_DRAG

PRESS

Hotkey Mode.

km_name

str

Keymap names separated by ;

Window

Keymaps in which the hotkey is active, such as "Window; 3D View".

chord

str

Identifier of bpy.types.Event.type, or NONE

NONE

Second key of a Key Chords sequence (open_mode CHORDS).

drag_dir

str

ANY, NORTH, NORTH_EAST, EAST, SOUTH_EAST, SOUTH, SOUTH_WEST, WEST, NORTH_WEST

ANY

Drag direction for CLICK_DRAG.

tweak_dir

str

Same as drag_dir

ANY

Drag direction for TWEAK. Separate from drag_dir; both are kept when open_mode changes.

repeat

bool

True, False

False

Accept repeated key presses while a key is held.

Default is the RNA default. Enum values are the identifiers of the running Blender, so the set of key identifiers can differ between Blender versions.

Property, Property Stack, Panel Group and Hidden Panel Group menus store these fields but have no hotkey. Their registration is never required.

Functions¶

pme.editing.update_hotkey(pm_uid, changes, *, expected=None, dry_run=False)¶

Change a menu’s hotkey binding.

All inputs are checked before the first write. Saved values are confirmed by reading them back; Blender’s keymap state is reported separately in registration.

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

  • changes (Mapping) – Field name mapped to its new value. Partial: fields that are not named keep their values.

  • expected (Mapping or None) – The complete read_pm()["hotkey"] mapping as read before. The update is rejected with stale_hotkey when a saved value differs. None skips the check.

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

Returns:

The result described below.

Return type:

dict

Raises:
  • TypeError – changes or expected is not a mapping; a Boolean field has a value that is not a bool (1 is rejected); another field has a value that is not a string; dry_run is not a bool.

  • ValueError – The UID is missing, invalid or ambiguous; a field name is unknown; an Enum value is not an accepted identifier; expected does not have exactly the 13 fields.

  • RuntimeError – Called outside Blender’s main thread, before PME has finished loading, or while PME preferences are unavailable. Also raised after writing has started; see Notes.

Result

Key

Type

Value

status

str

See Status below.

committed

bool

True only when status is "committed".

dry_run

bool

The dry_run argument.

pm_uid

str

UID of the menu.

before

dict

The 13 fields read before the call.

after

dict

The 13 fields read at the end. Equal to before unless status is "committed".

proposed

dict

The complete binding the call writes, or would write, after normalization.

changed_fields

list[str]

Fields whose value differs between before and after.

planned_fields

list[str]

Fields whose value differs between before and proposed.

adjustments

list[dict]

One entry per normalized field: field, requested and proposed. See Normalization.

diagnostics

list[dict]

One entry per problem or warning: code, plus the details listed under Diagnostics.

registration

dict

Blender’s keymap state at the end of the call. See Registration.

Status

status

Meaning

committed

Every field of proposed was read back. The keymap was updated; check registration for its state.

ready

dry_run=True and the change is acceptable. Nothing was written. proposed and planned_fields describe the change. This function returns ready, not validated.

unchanged

proposed equals the saved binding. Nothing was written. Registration is not repaired.

rejected

Nothing was saved. diagnostics names the cause.

The shared meaning of these values is defined on Results and guards. A failure after writing has started raises instead of returning a status.

Diagnostics

code

Cause, and extra keys

stale_hotkey

A value in expected differs from the saved value. fields lists the names. status is rejected, also with dry_run=True.

keymap_names_unavailable

km_name was given and Blender’s user keymaps cannot be read. message holds the error. status is rejected.

menu_hotkey_screen_editing_leftmouse

The binding puts a Left Mouse event into the Screen Editing keymap, which would block normal clicks. keymap_name names the keymap. status is rejected.

hotkey_write_mismatch

A written field did not read back as written. The saved values were restored and the restoration was confirmed. status is rejected.

current_hotkey_collision

Warning. The menu’s current registration collides with another keymap item. severity is "warning"; collision holds target and opponent. It does not block saving.

current_hotkey_collision_unavailable

The collision check raised. message holds the error.

Normalization

Input

Effect on proposed

km_name given

Split at ; and trimmed. Names that are not keymaps of Blender’s user keyconfig are dropped. The rest is joined with "; ". An empty result becomes "Window".

km_name not given

The saved names are kept, including names of keymaps that do not exist yet, such as imported ones.

open_mode given as CHORDS

A chord of NONE becomes A.

open_mode given as another mode

chord becomes NONE.

open_mode not given

chord is kept as given or saved.

The Screen Editing check runs on the requested and on the normalized keymap names, so a name dropped by normalization still rejects. It applies to menu types that have a hotkey.

Example

Preview, then apply F6 with Ctrl:

before = pme.editing.read_pm(pm_uid)["hotkey"]
changes = {"key": "F6", "ctrl": True, "open_mode": "PRESS"}
preview = pme.editing.update_hotkey(
    pm_uid, changes, expected=before, dry_run=True,
)
if preview["status"] == "ready":
    result = pme.editing.update_hotkey(pm_uid, changes, expected=before)
    print(result["after"], result["registration"])

Notes

  • Fields are written in the order open_mode, chord, then the others in table order; only fields that differ are set. The keymap is updated once, after every field has been read back.

  • Freshness is checked with expected only. A hotkey change does not change read_pm()["version"].

  • In a ready, unchanged or rejected result, registration and collision warnings describe the saved binding, not proposed. update_hotkey(pm_uid, {}, dry_run=True) returns the current registration without writing.

  • If a write raises or reads back differently, the saved values are restored before the keymap is touched. A confirmed restoration after a readback difference returns rejected with hotkey_write_mismatch; after a raising write, the exception propagates. If the restoration is not confirmed, the restoring step raises with the note Hotkey saved-value restoration is unconfirmed; host application has not started (RuntimeError("hotkey_saved_value_restore_mismatch") when the values differ).

  • If updating the keymap or refreshing raises, or the final readback differs from proposed (RuntimeError("hotkey_final_saved_value_mismatch")), the exception propagates with notes giving the saved readback, the changed fields and the registration. Saved values may already have changed. Read the hotkey before retrying.

  • If the mouse-button observer for a new key_mod cannot be registered, key_mod is restored and the other written fields keep their new values. This recovery covers key_mod only; registration can then be partial.

  • The call does not change the selected menu or the Slot Editor draft, save Preferences to disk, add an Undo step, or invoke the hotkey.

Registration¶

registration describes the keymap items PME has in Blender’s add-on keyconfig for this menu. It does not prove the final priority among user keymaps, input delivery, Poll, or execution.

Key

Type

Value

status

str

See below.

required

bool

True when the menu type has a hotkey, the menu is enabled, key is not NONE, and, for a Vector Menu, open_mode is not CLICK.

lanes

list[dict]

One entry per expected keymap item (each keymap in km_name times each event), plus one per leftover item.

diagnostics

list[dict]

Observation problems: code, and keymap_name or message where available.

status

Meaning

not_required

No registration is required and no leftover item remains.

registered

Every expected keymap item exists and matches.

partial

At least one lane has a reason: a missing, different or leftover item, or an unconfirmed mouse-button observer.

unknown

Registration could not be fully observed. diagnostics names the cause.

Lane¶

Key

Type

Value

keymap_name

str

Keymap of the item.

event_type

str

Event type of the item. "UNKNOWN" for a leftover item that could not be read.

expected

dict or None

The item PME registers: type, value, any, shift, ctrl, alt, oskey, hyper (0 or 1), key_modifier, direction, active, repeat, idname ("wm.pme_user_pie_menu_call"), pie_menu_name, invoke_mode ("HOTKEY"), keymap, source_pm_mode. None for a leftover item.

observed

dict or None

The same keys read from the actual item. None when the item is missing.

reason

str or None

None when observed equals expected. Otherwise one of the reasons below.

mouse_observer

dict

Present when key_mod is a mouse button: key, recorded (PME holds a claim on the observer) and present (an active observer item exists in the keymap).

A mouse button in key_mod is handled by the observer, so expected then has key_modifier "NONE".

reason

Meaning

hotkey_kmi_missing

The expected item is not registered.

hotkey_handle_missing_from_addon

PME’s record points to an item that is not in the add-on keyconfig.

hotkey_projection_mismatch

The item differs from expected.

mouse_modifier_observer_unconfirmed

The mouse-button observer for key_mod is not claimed or not present.

hotkey_projection_unreadable

The item could not be read. status is unknown.

unexpected_hotkey_projection

PME’s record holds more items for the keymap than expected.

untracked_hotkey_projection

The add-on keyconfig has an item for this menu that PME’s record does not track.

Registration diagnostics code

Cause

hotkey_owner_unavailable

Registration is required and PME has no record for the menu. status is unknown.

hotkey_registration_unavailable

Blender’s add-on keyconfig could not be read. message holds the error. status is unknown and lanes lists only the expected items.

hotkey_projection_unreadable

An item could not be read. message holds the error.

mouse_modifier_owner_remaining

Registration is not required and a mouse-button observer claim remains. status is unknown.

A disabled menu, a key of NONE, and a Vector Menu with CLICK require no registration. Their status is not_required only when no item or observer claim remains.