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 `python<br>L.box().label(text="My Label")<br>`
`E`	Current Event object `python<br>E.ctrl and E.shift and message_box("Ctrl+Shift Pressed")<br>`
`U`	pme.UserData instance for user data storage `python<br>U.foo = "value"<br>U.update(foo="value1", bar="value2")<br>U.foo<br>U.get("foo", "default_value")<br>`

Global Functions

Below is a list of global functions provided by PME.

Common Functions

execute_script(path, **kwargs)

Execute an external Python script.

:param str path: Path to the .py file. :param kwargs: Additional keyword arguments passed to the script. :return: 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.

:param str name: Name of the property. :param value: New value of the property. :return: 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.

:return: 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.

:return: 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.

:return: 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.

:param str name: Name of the menu. :param slot: Index or name of the slot for Stack Key execution. :param kwargs: Arguments for Modal / Macro Operators used as local variables. :return: 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.

:param str name: Name of the menu. :param bool value: True to enable, False to disable, None to toggle. :return: True if the menu exists, False otherwise.

tag_redraw(area=None, region=None)

Redraw UI areas or regions.

:param str area: The Area.type to redraw. Redraw all areas if None. :param str region: The Region.type to redraw. Redraw all regions if None. :return: True

close_popups()

Close all popup dialogs.

:return: True

overlay(text, **kwargs)

Draw an overlay message.

:param str text: Message to display. :param 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. :return: True

Example:

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

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

Show a message box.

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

input_box(func=None, prop=None)

Show an input box.

:param func: Function to call with the input value. :param str prop: Path to the property to edit. :return: 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.

:param str name: Name of the menu (popup dialog). :param bool frame: Whether to draw a frame. :param int dx: Horizontal offset. :param int dy: Vertical offset. :return: 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.

:param layout: A UILayout instance. :param str operator: Identifier of the operator. :return: 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.

:param str filename: Icon filename without extension, located in pie_menu_editor/icons/. :return: 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.

:param str id: ID of the panel. :param bool frame: Draw a framed panel. :param bool header: Draw the panel header. :param expand: True to expand, False to collapse, None to use the current state. :return: 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:

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)

:param str key: Name for accessing the item :param value: Function or value to register :rtype: 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.

:param str name: Data key :param default: Value to return if key doesn’t exist :return: 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"