Scripting¶

PME allows for advanced customization and automation using Blender’s Python API. This article provides an overview of PME’s scripting capabilities and explains the built-in global variables and functions.

Tutorials¶

Global Variables¶

Variables available within each PME slot editor.

Variable	Description
`menu`	Name of the active menu
`slot`	Name of the active slot
`C`	bpy.context
`D`	bpy.data
`O`	bpy.ops
`T`	bpy.types
`P`	bpy.props
`L`	Current UILayout object L.box().label(text="My Label")
`E`	Current Event object E.ctrl and E.shift and message_box("Ctrl+Shift Pressed")
`U`	pme.UserData instance for user data storage U.foo = "value" U.update(foo="value1", bar="value2") U.foo U.get("foo", "default_value")

Global Functions¶

Functions available within PME slot editors. Different functions are available in Command tab and Custom tab.

Common Functions¶

execute_script(path, **kwargs)¶

Execute an external Python script.

Parameters:

path (str) – Script file path. Relative path (from pie_menu_editor folder, recommended) or absolute path.
kwargs – Additional keyword arguments passed to the script.

Returns:

return_value from the script, or True by default.

Warning

Only place and execute scripts from trusted sources
Review contents before execution and verify in a backup or test environment if necessary
Scripts may contain operations that affect your environment, such as file operations or settings changes

Variables available in script: kwargs, __file__, return_value, all PME global variables

Examples:

# Basic execution and return value
execute_script("scripts/hello_world.py", msg="Hello World!")
message_box(execute_script("scripts/get_message.py"))

# scripts/hello_world.py
message_box(kwargs["msg"])

# scripts/get_message.py
return_value = "Hi!"

# Processing with parameters
# scripts/process_data.py
kwargs = locals().get("kwargs", {})
result = my_function(kwargs.get("param1"), kwargs.get("param2", "default"))
return_value = result

# Call
result = execute_script("scripts/process_data.py", param1=200, param2="Hello")

# UI drawing in Custom tab
# scripts/custom_ui.py
msg = kwargs.get("msg", pme.context.text or "Default Message")
box = L.box()
box.label(text=msg, icon=pme.context.icon, icon_value=pme.context.icon_value)

# Call
execute_script("scripts/custom_ui.py", msg="Custom message")

props(name=None, value=None)¶

Get or set the value of a PME Property.

Parameters:

name (str) – Name of the property.
value – New value of the property.

Returns:

PME property container if name is None, property value if only name is given, True if setting a value.

Example:

# Get property value using string notation
value = props("MyProperty")

# Alternative: get property using attribute notation
value = props().MyProperty  # props() returns property container

# Set property value using string notation
props("MyProperty", value)

# Alternative: set property using attribute notation
props().MyProperty = value  # props() returns property container

paint_settings()¶

Retrieve the context-sensitive paint settings.

Returns:: The current paint settings or None if not in a paint mode.

Example:

ps = paint_settings(); ps and L.template_ID_preview(ps, 'brush')

find_by(collection, key, value)¶

Find the first item in collection where key equals value.

Returns:: Collection item if found, otherwise None.

Example:

m = find_by(C.active_object.modifiers, "type", 'SUBSURF')

setattr(object, name, value)¶

Same as Python’s built-in setattr(), but returns True after setting.

Returns:: True

Command Tab Functions¶

open_menu(name, slot=None, **kwargs)¶

Open menu, pie menu, popup dialog or execute a stack key, sticky key, modal operator, or macro operator by name.

Parameters:

name (str) – Name of the menu.
slot – Index or name of the slot for Stack Key execution.
kwargs – Arguments for Modal / Macro Operators used as local variables.

Returns:

True if the menu exists, False otherwise.

Example:

# Open the menu depending on the active object's type:
open_menu("Lamp Pie Menu" if C.active_object.type == 'LAMP' else "Object Pie Menu")

# Call "My Stack Key" slot depending on Ctrl modifier:
open_menu("My Stack Key", "Ctrl slot" if E.ctrl else "Shift slot")

toggle_menu(name, value=None)¶

Enable or disable a menu.

Parameters:

name (str) – Name of the menu.
value (bool) – True to enable, False to disable, None to toggle.

Returns:

True if the menu exists, False otherwise.

tag_redraw(area=None, region=None)¶

Redraw UI areas or regions.

Parameters:

area (str) – The Area.type to redraw. Redraw all areas if None.
region (str) – The Region.type to redraw. Redraw all regions if None.

Returns:

True

close_popups()¶

Close all popup dialogs.

Returns:: True

overlay(text, **kwargs)¶

Draw an overlay message.

Parameters:

text (str) – Message to display.
kwargs –
- alignment: One of ['TOP', 'TOP_LEFT', 'TOP_RIGHT', 'BOTTOM', 'BOTTOM_LEFT', 'BOTTOM_RIGHT']. Default is 'TOP' .
- duration: Duration in seconds. Default is 2.0 .
- offset_x: Horizontal offset. Default is 10 px.
- offset_y: Vertical offset. Default is 10 px.

Returns:

True

Example:

overlay('Hello PME!', offset_y=100, duration=1.0)

message_box(text, icon='INFO', title='Pie Menu Editor')¶

Show a message box.

Parameters:

text (str) – Message to display.
icon (str) – Icon name (e.g. ‘INFO’, ‘ERROR’, ‘QUESTION’, etc.).
title (str) – Window title.

Returns:

True

input_box(func=None, prop=None)¶

Show an input box.

Parameters:

func – Function to call with the input value.
prop (str) – Path to the property to edit.

Returns:

True

Example:

# Rename object:
input_box(prop="C.active_object.name")

# Display input value:
input_box(func=lambda value: overlay(value))

Custom Tab Functions¶

draw_menu(name, frame=True, dx=0, dy=0)¶

Draw a popup dialog inside another popup dialog or a pie menu.

Parameters:

name (str) – Name of the menu (popup dialog).
frame (bool) – Whether to draw a frame.
dx (int) – Horizontal offset.
dy (int) – Vertical offset.

Returns:

True if the popup dialog exists, otherwise False.

operator(layout, operator, text='', icon='NONE', emboss=True, icon_value=0, **kwargs)¶

Similar to UILayout.operator(), but allows filling operator properties.

Parameters:

layout – A UILayout instance.
operator (str) – Identifier of the operator.

Returns:

OperatorProperties object.

Example:

operator(L, "wm.context_set_int", "Material Slot 1",
        data_path="active_object.active_material_index", value=0)

# Same as:
# op = L.operator("wm.context_set_int", text="Material Slot 1")
# op.data_path = "active_object.active_material_index"
# op.value = 0

custom_icon(filename)¶

Get the integer value associated with a custom icon.

Parameters:: filename (str) – Icon filename without extension, located in pie_menu_editor/icons/.
Returns:: The integer value of the custom icon.

Example:

L.label(text="My Custom Icon", icon_value=custom_icon("p1"))

panel(pt, frame=True, header=True, expand=None, poll=True, layout=None)¶

Draws a panel by its ID.

Parameters:

pt (Union[str, Type]) – Panel class or panel class name string. If string, the corresponding class is searched from bpy.types.
frame (bool) – Controls whether to frame the panel. If True, uses layout.box(). If False, uses layout.column().
header (bool) – Controls panel header display style.
expand (Optional[bool]) – Controls initial expansion state of panel. True: start expanded, False: start collapsed, None: retain previous state.
poll (bool) – Controls whether to execute the panel’s poll method. If True, checks the panel’s display conditions.
layout (Optional[Any]) – Specify a custom layout.

Returns:

True

Return type:

bool

Example:

panel("MATERIAL_PT_context_material", True, True, True)

# Change panel size
L.scale_x = 0.8; panel("USERPREF_PT_interface", layout=L.box())

Auto-run Scripts¶

PME allows you to create Python scripts that automatically execute when Blender starts. To use this feature, place files in the pie_menu_editor/scripts/autorun folder using any of these methods:

Direct .py files
Folders containing scripts
Symbolic links

Warning

Only place and execute scripts from trusted sources
Review contents before execution and verify in a backup or test environment if necessary
Scripts may contain operations that affect your environment, such as file operations or settings changes

Add Custom Global Functions¶

To use custom functions in PME:

Place your script in pie_menu_editor/scripts/autorun folder
Register functions using pme.context.add_global()

Example:

def hello_world():
    print("Hello World")

pme.context.add_global("hello", hello_world)

The registered function hello() becomes available in:

Command tab
Custom tab
External scripts

PME Components¶

PME maintains a global context that provides access to commonly used functions, variables, and user-defined additions. This context is accessible through two main interfaces:

class pme.context¶

globals: dict¶

Access PME’s global context dictionary. Contains:

Built-in shortcuts (C, D, O, L, etc.)
Registered custom functions and values
User data storage (U)

from pie_menu_editor import pme

# Access globals from external scripts
g = pme.context.globals
props = g.get('props')
user_data = g.get('U')

add_global(key, value)¶

Parameters:

key (str) – Name for accessing the item
value – Function or value to register

Return type:

None

# Register a function
def my_tool():
    bpy.ops.mesh.select_all(action='TOGGLE')

pme.context.add_global("toggle_select", my_tool)

# Register a constant
pme.context.add_global("MAX_ITEMS", 10)

# Access from PME menus via Command tab:
# toggle_select()
# MAX_ITEMS

class pme.UserData¶

Flexible storage for user-defined data that persists during the Blender session.

get(name, default=None)¶

Get a stored value.

Parameters:

name (str) – Data key
default – Value to return if key doesn’t exist

Returns:

Stored value or default

update(**kwargs)¶

Update multiple values at once.

U = pme.context.globals['U']  # Get UserData instance
U.update(tool_state="active", count=5)
print(U.tool_state)  # "active"