Bundled Utilities¶

PME loads these helpers from its bundled assets/scripts/autorun/ folder when the add-on starts. Use their registered names directly in PME script fields; you do not need to import or copy the bundled files. Do not edit those files to customize them: updates can replace them. To register your own helpers, see Auto-run Scripts.

These utilities complement the API Reference. They are not menu editing operations in the Public API. To manage script files, see Managing Scripts.

Examples below are one-line expressions or statements for PME fields. L is available while drawing a Custom slot; E requires an input event. Pass C explicitly to helpers that accept a context so they use the invoking editor. Calls without a context use bpy.context, which can refer to another editor while a popup or Preferences is active. The helpers do not create missing editor context or make an unavailable Blender operator available.

Function index¶

Purpose

Registered names

Active tool

get_active_tool, get_active_tool_id

Mesh selection and pointer

get_mesh_selection_kind, pick_mesh_view3d, get_loc2d

Tool and DAT icons

get_tool_icon_value, get_dat_icon, release_dat_icons

Paint settings

ups, brush

Assignment and errors

setattr, try_setattr, raise_error

Event modifiers

event_mods

Existing name-based menu routing

CSM (see the collapsed reference below)

Active tool¶

get_active_tool(context=None)¶

Returns Blender’s active WorkSpaceTool-like object, or None when Blender’s tool resolver finds no tool. It uses the editor and mode of the supplied context, not a search for an arbitrary 3D View. Provide a context with a workspace and space data. Blender decides which editors expose a tool; this is not limited to mesh tools or the 3D View.

tool = get_active_tool(C); message_box(tool.idname if tool else "No active tool")

Use the returned object immediately; do not retain it across workspace, editor, or mode changes. This resolves the current tool; it does not activate a tool.

get_active_tool_id(context=None)¶

Returns the active tool’s idname as a string, such as "builtin.select_box". Returns "" if the context has no workspace or space data, or no tool is found. The ID is not the translated label or an icon name.

get_active_tool_id(C) == 'builtin.select_box'

Use that expression in a condition, or display the result in a Custom slot:

L.label(text=get_active_tool_id(C) or "No active tool")

Mesh selection and pointer¶

get_mesh_selection_kind(context, fallback=True)¶

Returns 1 for vertices, 2 for edges, 3 for faces, or 0 for no applicable selection. Requires Mesh Edit Mode to inspect geometry; outside EDIT_MESH it returns 0. It reads editable mesh data across objects with unique mesh data and does not change selection.

get_mesh_selection_kind(C, fallback=False) == 3
  • With one selection mode enabled and fallback=True, returns that mode even when nothing is selected.

  • With fallback=False, a single mode requires a selected, non-hidden element of that type; otherwise returns 0.

  • In mixed selection modes, selected vertices that do not belong to selected faces/edges in enabled modes take priority, then selected faces, then edges. Hidden elements are excluded.

  • If no eligible element is found and fallback=True, uses the enabled modes in vertex → face → edge order. With fallback=False, returns 0 instead.

This is an inference from selection flags, not a record of what was clicked last. Blender can represent a selected face and its selected corner vertices with the same flags. Use pick_mesh_view3d when the element under the pointer is the information you need. This function does not inspect UV selection.

pick_mesh_view3d(context, mouse_xy, radius=12)¶

Reads the object or mesh component under a window-coordinate pointer position without selecting it. Requires a 3D View WINDOW region, in Object Mode or Mesh Edit Mode. Other contexts return a no-hit dictionary.

Example in an event-backed Command slot:

hit = pick_mesh_view3d(C, (E.mouse_x, E.mouse_y)); message_box(hit['kind'] or "No hit")

Pass window coordinates, not mouse_region_x / mouse_region_y. The helper subtracts the target region’s origin. It uses the coordinates you supply at call time; it does not capture the menu-opening position or track later motion. If routing must use the opening position, retain that position in the caller.

Result key

Value

kind

'OBJECT', 'VERT', 'EDGE', 'FACE', or None

object

Hit Blender object, or None

index

Current BMesh iteration position for an Edit Mode component; otherwise None

mouse_xy

Region-relative (x, y) after conversion, or None for an invalid area/region

distance_px

Present only for a vertex/edge hit: distance from the pointer in screen pixels

In Object Mode this uses a scene ray cast and checks visibility of the returned object. It does not reproduce picking of non-surface objects such as lights or empties, and does not return a component index from the evaluated mesh.

In Mesh Edit Mode, vertices within radius win over edges within radius, then the nearest surface face. Only enabled selection modes are considered. A negative radius is treated as zero. Hidden elements are excluded; X-Ray allows vertex/edge hits through editable faces.

Limits: this is an approximation, not Blender’s native selection-buffer picker. It uses the editable cage, not modifier output. Backfaces count as surfaces, and viewport clipping planes are not reproduced. In Edit Mode only non-hidden editable mesh faces occlude hits; objects outside Edit Mode do not. Indices are valid for the immediate observation only and must not be saved as stable element identifiers. Geometry is rebuilt for each call: avoid repeated calls in draw code or frequently evaluated conditions on dense meshes. No handlers, timers, selection writes, or persistent geometry caches are installed.

get_loc2d(context, coord)¶

Projects a world-space 3D coordinate into region-relative 2D coordinates. Returns a mathutils.Vector with two components, or None if region/view data is unavailable or Blender cannot project the point (for example, behind a perspective view). context=None uses bpy.context.

point = get_loc2d(C, C.active_object.matrix_world.translation)

This example requires an active object and a 3D View drawing region. Convert a mesh-local coordinate with obj.matrix_world @ coord first. A returned point can be outside the viewport; it is not a visibility or occlusion test. The helper uses space_data.region_3d, so do not assume it selects the correct subview in every Quad View region. Unlike pick_mesh_view3d, its output is already region-relative.

Icons¶

get_tool_icon_value(name)¶

Returns an integer icon ID for a Blender tool icon handle, not a tool ID or an RNA icon enum. A typical handle is "ops.generic.select_box". Returns 0 for an empty name. It first uses Blender’s tool icon loader; if that raises, it falls back to get_dat_icon(name). Unavailable icons may resolve to Blender’s fallback icon or 0, so a nonzero ID is not proof of an exact match.

L.label(text="Box Select", icon_value=get_tool_icon_value('ops.generic.select_box'))

Use in a Custom slot with a drawing layout. Prefer PME’s Auto Icon option for a normal tool-switching slot; this helper is for custom drawing.

get_dat_icon(icon_name)¶

Returns an integer icon ID loaded from a .dat triangle icon. Pass its name without .dat, not a filesystem path. Search order is Blender’s DATAFILES/icons, PME user icon directories, then bundled icons.

L.label(text="Box Select", icon_value=get_dat_icon('ops.generic.select_box'))

Returns 0 for an empty name, a missing/ambiguous/unloadable icon, or when an old cached icon cannot be released before replacement. Missing/corrupt files produce a warning; ambiguous user names are reported through resource discovery. Loaded IDs are cached. Do not save these runtime IDs in a preset or reuse them across restarts. This is not a PNG loader. Icon availability depends on the installed Blender and configured resources, not the active modeling mode.

release_dat_icons()¶

Releases the DAT IDs owned by this helper and clears its Blender path lookup cache. Returns None. IDs that cannot be released remain tracked for a later retry. This does not release all Blender icons or icons owned by other loaders.

release_dat_icons()

This is a reload/development helper, not something to run on every draw. Stop using cached IDs before releasing them; request fresh IDs for subsequent UI.

Paint settings¶

ups()¶

Returns the raw Unified Paint Settings object for the current bpy.context. On hosts with scene-wide unified settings it returns that owner. On hosts with mode-specific settings it resolves the current paint mode independently of the active tool. It raises RuntimeError if that context has no unified settings.

Example Custom slot in an applicable paint context:

L.prop(ups(), 'size', text='Unified Size')

It does not choose a brush or switch modes. Property availability follows the host’s returned RNA object. In Blender 5.3, active use_unified_* flags live on the Brush; do not assume those flags exist on the object returned by ups().

brush(use_ups=False)¶

Returns the active Brush from Blender’s current paint settings, or None when no brush is available. With use_ups=True, returns ups() instead (including its errors); that result is unified settings, not a Brush. Uses bpy.context and Blender’s paint-settings resolver; mode and active tool can affect brush availability.

b = brush(); L.prop(b, 'strength', text='Strength') if b else L.label(text='No active brush')

This example belongs in a Custom slot in a paint/sculpt context. Do not dereference brush().size without ensuring a brush exists. The historical expression brush(ups().use_unified_size).size assumes unified flags live on Unified Paint Settings and is not suitable for hosts that put them on Brush.

Assignment, events, and errors¶

setattr(object, name, value)¶

Sets an attribute and returns True after a successful assignment. Unlike Python’s built-in setattr, PME’s registered helper returns a boolean. Assignment errors propagate. The target must exist and its property must be writable in the current context.

setattr(C.tool_settings, 'use_proportional_edit', True)

Use in a Command, not a drawing callback or a condition that should only read state. For a visible toggle, prefer a Custom slot widget such as L.prop(C.tool_settings, 'use_proportional_edit', toggle=True). This helper does not create its own Undo step.

try_setattr(object, name, value)¶

Attempts the same assignment, but catches assignment exceptions and always returns True, including when nothing was changed. This is existing behavior; do not use the result to verify success.

try_setattr(C.active_object, 'show_name', True)

No particular editor is required, but the target and property still determine whether the assignment can work. Use setattr when a failure should be visible, and read back the property when verifying a change. This helper neither reports the failure nor creates its own Undo step.

event_mods(event)¶

Returns a string joining active modifiers in Ctrl, Shift, Alt, OSKey order, for example "Ctrl+Shift". Returns the literal string "None" if none are set; missing modifier attributes count as false. Requires an event-like value, not a particular editor or mode. It does not report non-modifier keys.

message_box(event_mods(E))

Use from an event-backed Command. This reads the supplied event, not the keyboard’s current state at some later time.

raise_error(message)¶

Attempts to show PME’s error message box, then raises Exception(message). It has no normal return value and aborts the current script. Requires a UI context where the message-box operator can run; if that operator fails, its error propagates instead.

raise_error('Select a mesh before running this command')

Use for an actual error in a Command, not an ordinary false condition or repeated draw-time notification.

ContextSensitiveMenu (CSM)¶

For new menus, use Context Router. Separate editors with Keymap where possible, then use a Context Router for conditions within an editor. This makes branches explicit without relying on menu naming conventions. CSM remains available for existing customizations.

ContextSensitiveMenu compatibility reference and examples

CSM.from_context(context, prefix="", suffix="") returns a ContextSensitiveMenu instance with a resolved menu_name (string or None). Pass C to use the invoking context. It reads the active object, not the pointer hit or merely whether the selected-object list is empty.

Command example, with menus such as My Vertex Menu and My Mesh Menu already created:

CSM.from_context(C, prefix='My ', suffix=' Menu').open_menu()

Custom example, with drawable menus such as My Vertex Panel already created:

CSM.from_context(C, prefix='My ', suffix=' Panel').draw_menu(layout=L)

Names are formed by replacing underscores with spaces, applying title case, then adding the prefix/suffix. Only existing, enabled menus match.

  • No active object: resolves the name None Object; it does not fall back to Any Object in this branch.

  • Mesh Edit Mode: enabled selection modes in Vertex → Edge → Face order, then Edit Mesh, Mesh, Any Object. This tests enabled selection modes, not selected elements and not get_mesh_selection_kind().

  • Mesh in another non-Object mode: current mode, then Mesh, Any Object.

  • Mesh in Object Mode: Mesh, then Any Object.

  • Empty: Image, or Instance, or the force-field type followed by Field when applicable; then Empty, Any Object.

  • Other object types: current non-Object mode, object type, then Any Object.

open_menu(**kwargs) and draw_menu(**kwargs) return None; keyword arguments are passed to PME’s corresponding menu helper. Drawing requires a valid layout; opening requires a usable invocation context. Missing/disabled menus log a warning and do nothing. A failure from opening/drawing is reported as an error. An existing enabled menu may still be unavailable because of its Poll.

For inspection, CSM.has_menu(name) and instance.check_menu_exists() return booleans; the latter also warns on a missing menu. instance.format_name(name) returns the formatted string, and instance.check_and_set_menu(name) returns that string for an enabled menu or None (it does not assign menu_name). instance.gen_menu_name() recomputes the name and returns None. Create a new instance after context changes instead of retaining a captured active object across edits.