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 |
|---|---|
Returns the saved binding under |
|
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 |
|---|---|---|---|---|
|
str |
Identifier of |
|
Key or button that invokes the menu. |
|
str |
Identifier of |
|
Key held as a modifier (Key Modifier). A mouse button
( |
|
bool |
|
|
Ctrl held. |
|
bool |
|
|
Shift held. |
|
bool |
|
|
Alt held. |
|
bool |
|
|
OS key held. |
|
bool |
|
|
Match regardless of modifier keys (Any Modifier). The keymap item then ignores the four modifier fields. |
|
str |
|
|
Hotkey Mode. |
|
str |
Keymap names separated by |
|
Keymaps in which the hotkey is active, such as |
|
str |
Identifier of |
|
Second key of a Key Chords sequence ( |
|
str |
|
|
Drag direction for |
|
str |
Same as |
|
Drag direction for |
|
bool |
|
|
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 withstale_hotkeywhen a saved value differs.Noneskips the check.dry_run (bool) – Check the change and return without writing.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
changesorexpectedis not a mapping; a Boolean field has a value that is not a bool (1is rejected); another field has a value that is not a string;dry_runis not a bool.ValueError – The UID is missing, invalid or ambiguous; a field name is unknown; an Enum value is not an accepted identifier;
expecteddoes 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
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".dry_runbool
The
dry_runargument.pm_uidstr
UID of the menu.
beforedict
The 13 fields read before the call.
afterdict
The 13 fields read at the end. Equal to
beforeunlessstatusis"committed".proposeddict
The complete binding the call writes, or would write, after normalization.
changed_fieldslist[str]
Fields whose value differs between
beforeandafter.planned_fieldslist[str]
Fields whose value differs between
beforeandproposed.adjustmentslist[dict]
One entry per normalized field:
field,requestedandproposed. See Normalization.diagnosticslist[dict]
One entry per problem or warning:
code, plus the details listed under Diagnostics.registrationdict
Blender’s keymap state at the end of the call. See Registration.
Status
statusMeaning
committedEvery field of
proposedwas read back. The keymap was updated; checkregistrationfor its state.readydry_run=Trueand the change is acceptable. Nothing was written.proposedandplanned_fieldsdescribe the change. This function returnsready, notvalidated.unchangedproposedequals the saved binding. Nothing was written. Registration is not repaired.rejectedNothing was saved.
diagnosticsnames 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
codeCause, and extra keys
stale_hotkeyA value in
expecteddiffers from the saved value.fieldslists the names.statusisrejected, also withdry_run=True.keymap_names_unavailablekm_namewas given and Blender’s user keymaps cannot be read.messageholds the error.statusisrejected.menu_hotkey_screen_editing_leftmouseThe binding puts a Left Mouse event into the Screen Editing keymap, which would block normal clicks.
keymap_namenames the keymap.statusisrejected.hotkey_write_mismatchA written field did not read back as written. The saved values were restored and the restoration was confirmed.
statusisrejected.current_hotkey_collisionWarning. The menu’s current registration collides with another keymap item.
severityis"warning";collisionholdstargetandopponent. It does not block saving.current_hotkey_collision_unavailableThe collision check raised.
messageholds the error.Normalization
Input
Effect on
proposedkm_namegivenSplit 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_namenot givenThe saved names are kept, including names of keymaps that do not exist yet, such as imported ones.
open_modegiven asCHORDSA
chordofNONEbecomesA.open_modegiven as another modechordbecomesNONE.open_modenot givenchordis 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
expectedonly. A hotkey change does not changeread_pm()["version"].In a
ready,unchangedorrejectedresult,registrationand collision warnings describe the saved binding, notproposed.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
rejectedwithhotkey_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_modcannot be registered,key_modis restored and the other written fields keep their new values. This recovery coverskey_modonly; registration can then bepartial.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 |
|---|---|---|
|
str |
See below. |
|
bool |
|
|
list[dict] |
One entry per expected keymap item (each keymap in |
|
list[dict] |
Observation problems: |
|
Meaning |
|---|---|
|
No registration is required and no leftover item remains. |
|
Every expected keymap item exists and matches. |
|
At least one lane has a |
|
Registration could not be fully observed. |
Lane¶
Key |
Type |
Value |
|---|---|---|
|
str |
Keymap of the item. |
|
str |
Event type of the item. |
|
dict or None |
The item PME registers: |
|
dict or None |
The same keys read from the actual item. |
|
str or None |
|
|
dict |
Present when |
A mouse button in key_mod is handled by the observer, so expected
then has key_modifier "NONE".
|
Meaning |
|---|---|
|
The expected item is not registered. |
|
PME’s record points to an item that is not in the add-on keyconfig. |
|
The item differs from |
|
The mouse-button observer for |
|
The item could not be read. |
|
PME’s record holds more items for the keymap than expected. |
|
The add-on keyconfig has an item for this menu that PME’s record does not track. |
Registration |
Cause |
|---|---|
|
Registration is required and PME has no record for the menu.
|
|
Blender’s add-on keyconfig could not be read. |
|
An item could not be read. |
|
Registration is not required and a mouse-button observer claim
remains. |
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.