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

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

Below is a list of global functions provided by PME.

Common Functions

execute_script(path, **kwargs)

Execute an external Python script.

Parameters:

  • path (str) – Path to the .py file.

  • kwargs – Additional keyword arguments passed to the script.

Returns:

Value of local variable return_value if it exists, otherwise True.

Example:

# Display 'Hello World!' message:
execute_script("scripts/hello_world.py", msg="Hello World!")

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

# Display 'Hi!' message:
message_box(execute_script("scripts/hi.py"))

# scripts/hi.py:
# return_value = "Hi!"
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(id, frame=True, header=True, expand=None)

Draws a panel by its ID.

Parameters:

  • id (str) – ID of the panel.

  • frame (bool) – Draw a framed panel.

  • header (bool) – Draw the panel header.

  • expand – True to expand, False to collapse, None to use the current state.

Returns:

True

Example:

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

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

Scripts in the autorun folder are executed directly in PME’s context. Only use scripts from trusted sources.

Add Custom Global Functions

To use custom functions in PME:

  1. Place your script in pie_menu_editor/scripts/autorun folder

  2. 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)

Register a custom function or value in the global context.

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"