Menu type settings¶
Each menu type has its own settings, such as a Pop-up Dialog’s Mode and width or a Pie Menu’s radius. They are read and written by name. Slots, hotkeys and the menu name are separate operations.
Function |
Purpose |
|---|---|
Returns the current values under |
|
Describes the settings a menu accepts. |
|
Changes settings. |
Reading settings¶
read_pm(pm_uid)["settings"] is a mapping of setting name to current value.
Names are the saved names listed under Settings by menu type. Values
are what the editor shows: an Enum is its identifier string, not a stored number.
>>> pme.editing.read_pm(pm_uid)["settings"]
{'pd_panel': 'PANEL', 'pd_width': 300, 'pd_title': True, 'pd_box': True,
'pd_use_property_split': False, 'pd_use_property_decorate': False,
'pd_extend_target': '', 'pd_extend_side': 'append', 'pd_extend_order': 0,
'pd_extend_is_right': False}
A menu type without settings returns {}. If the saved data cannot be parsed,
settings is {} and read_pm() also returns settings_diagnostics
with the code settings_data_unreadable.
Functions¶
- pme.editing.setting_fields(pm_uid)¶
Describe the settings that the menu’s type accepts.
- Parameters:
pm_uid (str) – UID of the menu.
- Returns:
Setting name mapped to a description.
- Return type:
- Raises:
ValueError – The UID is missing, invalid or ambiguous.
RuntimeError – Called off Blender’s main thread, or before PME has finished loading.
Each description has these keys:
Key
Present for
Value
typeall
"BOOLEAN","INT","STRING"or"ENUM"descriptionall
The editor’s tooltip text. Empty for Stack Key settings.
min,maxINTInclusive range accepted by
update_settings()valuesENUMAccepted identifiers
flagsvm_start_inputsFlag name mapped to its bit value
>>> pme.editing.setting_fields(pm_uid)["pd_width"] {'type': 'INT', 'description': 'Width of the popup', 'min': 100, 'max': 2000}
- pme.editing.update_settings(pm_uid, changes, *, expected=None, dry_run=False)¶
Change settings of the menu’s type.
All changes are checked before the first write. If any is rejected, nothing is written.
- Parameters:
pm_uid (str) – UID of the menu.
changes (dict) – Setting name mapped to its new value. Partial: settings that are not named keep their values.
expected (dict or None) – Setting name mapped to the value it must have now. Any subset of the settings. The update is rejected with
stale_settingswhen a value differs.dry_run (bool) – Check the changes and return without writing.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
changesorexpectedis not a mapping with string keys, ordry_runis not a bool.ValueError – The UID is missing, invalid or ambiguous.
RuntimeError – Called off Blender’s main thread, or before PME has finished loading.
Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".dry_runbool
The
dry_runargument.pm_uidstr
The
pm_uidargument.beforedict
Settings read before the call.
afterdict
Settings read after the call. Equal to
beforeunless something was written.changed_fieldslist[str]
Names whose value differs between
beforeandafter.recoverydict or None
Set after a failed write:
scope("settings"),saved_settings_matchandsaved_data_matches.diagnosticslist[dict]
One entry per problem:
code,field(orfields) andmessage, plus the details listed under Diagnostics.Status
statusMeaning
committedEvery requested value is saved.
validateddry_run=Trueand the changes are acceptable. Nothing was written.unchangedEvery requested value already equals the saved value.
rejectedNothing was written.
diagnosticsnames the cause.restored_failureA write failed and the settings were restored to
before.unknownA write failed and the restore could not be confirmed. Call
read_pm()before retrying.Diagnostics
codeCause, and extra keys
setting_not_applicableThe name is not a setting of this menu type.
availablelists the names that are.setting_type_mismatchThe value has the wrong Python type. An
INTsetting does not accept a float or a bool.setting_out_of_rangeAn integer is outside
min..max. The value is not clamped.setting_not_a_choiceAn Enum value is not in
values.setting_not_representableA string contains
&or=, which the saved format cannot hold.extend_target_unknownThe extend target is not a registered Panel, Header or Menu type.
extend_target_not_extendableThe extend target is a type PME does not extend, such as PME’s own panels.
setting_requires_extend_targetAn extend side, order or right-region flag was given without an extend target.
stale_settingsA value in
expecteddiffers from the saved value.fieldslists the names.settings_data_unreadableThe saved data cannot be parsed.
exception_typenames the error.setting_value_not_retainedA setter did not keep the requested value.
requestedandactualgive both values.setting_write_failedA setter raised.
exception_typenames the error.Example
Create a Pop-up Dialog in Popup Mode, 420 pixels wide:
created = pme.create_pm(pme.PmCreationSpec("DIALOG", name="Bone Collections")) result = pme.editing.update_settings( created.pm_uid, {"pd_panel": "POPUP", "pd_width": 420}, expected={"pd_panel": "PANEL"}, ) assert result["status"] == "committed", result["diagnostics"]
Notes
Extend settings are written in the order target, side, right region, order. Setting an extend target also sets the side to
"append".Extend targets and Panel Group placement register with Blender inside the call, as they do in the editor.
The call does not save Preferences to disk, add an Undo step, or invoke the menu.
Settings by menu type¶
The Menu type value is the mode_id given to PmCreationSpec and
returned as read_pm()["mode"]. Types that are not listed have no settings.
A Property is edited with update_property() and a Property Stack with its
own operations.
Pie Menu (PMENU)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
INT |
-1 .. 1000 |
-1 |
Radius of the pie menu. -1 uses the default. |
|
INT |
-1 .. 1000 |
-1 |
Minimum distance from the center before an item can be selected. -1 uses the default. |
|
INT |
-1 .. 1000 |
-1 |
Additional distance beyond the threshold for automatic confirmation. 0 disables it; -1 uses the default. |
|
BOOLEAN |
True |
Confirm the selection when the hotkey is released. |
Vector Menu (VMENU)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
BOOLEAN |
False |
Wait for a mouse button or pen tip before starting; release that input to confirm. |
|
|
INT |
0 .. 15 |
15 |
Inputs that start the menu, as bit flags: 1 left mouse, 2 middle mouse, 4 right mouse, 8 pen tip. |
Regular Menu (RMENU)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
BOOLEAN |
True |
Show the title. |
|
|
STRING |
Menu type name |
|
Blender Menu that this menu’s content is added to, for example
|
|
ENUM |
|
|
Position relative to the original content. |
|
INT |
0 and up |
0 |
Display order when several menus extend the same target. |
Pop-up Dialog (DIALOG)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
ENUM |
|
|
Mode: Pie Mode, Dialog Mode or Popup Mode. |
|
INT |
100 .. 2000 |
300 |
Width of the popup. |
|
BOOLEAN |
True |
Show the title. |
|
|
BOOLEAN |
True |
Use a frame. |
|
|
BOOLEAN |
False |
Draw property labels in a separate column, as Blender’s property panels do. |
|
|
BOOLEAN |
False |
Show the animation decorator column. Effective only with Property Split. |
|
|
STRING |
Panel or Header type name |
|
Blender Panel or Header that this menu’s content is added to, for
example |
|
ENUM |
|
|
Position relative to the original content. |
|
INT |
0 and up |
0 |
Display order when several menus extend the same target. |
|
BOOLEAN |
False |
Draw in the right region of the Top Bar. |
Floating Panel (FPANEL)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
BOOLEAN |
False |
Draw property labels in a separate column. |
|
|
BOOLEAN |
False |
Show the animation decorator column. Effective only with Property Split. |
Panel Group (PANEL)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
ENUM |
Space type, see |
|
Editor that shows the panels. |
|
ENUM |
|
|
Region that shows the panels. |
|
ENUM |
Context, see |
|
Panel context, such as |
|
STRING |
Without |
|
Sidebar tab. |
|
BOOLEAN |
False |
Use wide icon buttons. |
Modal Operator (MODAL)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
BOOLEAN |
False |
Confirm when the key or mouse button that started the operator is released. |
|
|
BOOLEAN |
True |
Block other hotkeys. |
|
|
BOOLEAN |
True |
Keep the mouse cursor within the current area. |
Sticky Key (STICKY)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
BOOLEAN |
False |
Block other tools while the Sticky Key is active. |
Stack Key (SCRIPT)¶
Name |
Type |
Values |
Default |
Description |
|---|---|---|---|---|
|
BOOLEAN |
False |
Undo the previous command. |
|
|
BOOLEAN |
False |
Remember the last executed slot. |
|
|
ENUM |
|
|
When remembered slots advance: on every press, or only when pressed again within the timeout. |
|
INT |
1 and up |
600 |
Timed repeat window in milliseconds. |