PME2: Macro operator improvements - description and argument-free invocation

[Pluglug]

Summary

Improve dynamically generated macro operators to support:

1. User-defined bl_description for proper tooltips
2. Argument-free invocation (auto-build from pmi)

Background

Current Problem

When registering a PME macro to standard Blender UI (toolbar, menu, etc.):

Option 1: Via pme_user_pie_menu_call

layout.operator("wm.pme_user_pie_menu_call", text="My Macro").pie_menu_name = "My Macro"
# Tooltip: "Call PME menu" ← Generic, not helpful

Option 2: Direct macro operator

bpy.ops.pme.macro_my_macro(
    MESH_OT_primitive_cube_add={"size": 2, ...},
    PME_OT_macro_exec1={"cmd": "bpy.ops.transform.translate()"},
    # ... all arguments required!
)
# Tooltip: (undocumented operator) ← No bl_description set

Desired Behavior

# Argument-free invocation
bpy.ops.pme.macro_my_macro()  # Auto-builds args from pmi internally

# Proper tooltip when registered to UI
layout.operator("pme.macro_my_macro")
# Tooltip: "Add cube and transform" ← User-defined description!

---

Proposed Changes

1. Add description property to PMItem

File: pme_types.py (around line 359)

description: StringProperty(
    name="Description",
    description="Description shown in tooltips when registered to Blender UI",
    default="",
    maxlen=CC.MAX_STR_LEN,
)

2. Set bl_description in macro generation

File: infra/macro.py - add_macro() function

defs = {
    "bl_label": pm.name,
    "bl_idname": tp_bl_idname,
    "bl_options": {'REGISTER', 'UNDO'},
}

# NEW: Set bl_description from pm.description
if hasattr(pm, 'description') and pm.description:
    defs["bl_description"] = pm.description

3. Support argument-free invocation

Option A: Modify dynamic macro's invoke() to auto-fill props

Option B: Expose execute_macro(pm) via API

# api/dynamic.py
def call_macro(name: str) -> set[str]:
    """Call macro by name (auto-builds args from pmi)"""
    from ..infra.macro import execute_macro
    pm = get_prefs().pie_menus.get(name)
    return execute_macro(pm) if pm else {'CANCELLED'}

Note: execute_macro() already exists in infra/macro.py:238-273 and uses _fill_props() to auto-build arguments from pmi.

---

JSON Schema v2 Integration

{
  "uid": "mc_9f7c2k3h",
  "name": "My Macro",
  "type": "MACRO",
  "description": "Add cube and transform",
  "items": [...]
}

The description field maps to bl_description for macro operators.

---

Benefits

Before	After
Generic "Call PME menu" tooltip	User-defined description
"Undocumented operator" warning	Proper operator info
All arguments required	Argument-free invocation possible
Hard to use in external scripts	pme.call_macro("name") API

---

Related Issues

• PME2: GPU-rendered description tooltip for Pie Menu #100 - GPU-rendered description tooltip for Pie Menu (PME internal tooltips)
• PME2: description / description_expr implementation #81 - description/description_expr implementation (JSON schema)

This issue focuses on Blender UI integration (external tooltips), while #100 focuses on PME internal tooltip rendering.

---

Implementation Notes

• execute_macro() already handles pmi → props conversion
• Minimal changes to add_macro() for bl_description
• API exposure is optional but recommended for external scripting

[Pluglug]

Implementation Complete! 🎉

Summary

Both Phase A and Phase B are now implemented and tested successfully.

What was implemented

Phase A: Static bl_description for dynamic macro operators

• Added description field to PMItem (menu-level description)
• add_macro() now sets bl_description on dynamically generated macro classes
• UI field added to Macro Editor ("Tooltip" text field)
• Auto-update: changing description triggers macro rebuild

Phase B: Wrapper operator with dynamic description

• New PME_OT_invoke_macro operator (pme.invoke_macro)
• Uses description() classmethod for dynamic tooltips
• Internally calls execute_macro(pm) for automatic argument construction

---

💡 Key Discovery: Dynamic Operator Description

Blender supports dynamic operator descriptions via a classmethod. This is a powerful but underutilized feature!

The Pattern

```python
class MyOperator(bpy.types.Operator):
bl_idname = "my.operator"
bl_label = "My Operator"
bl_description = "Default fallback description"

target_name: StringProperty()

@classmethod
def description(cls, context, properties):
    """Called by Blender to get the tooltip dynamically."""
    # Access operator properties via properties.xxx
    name = properties.target_name
    if name:
        return f"Do something with {name}"
    return "Select a target first"

def execute(self, context):
    ...

```

Key Points

1. Signature: description(cls, context, properties) - must be a @classmethod
2. properties parameter: Access operator properties (e.g., properties.target_name)
3. context parameter: Access current Blender context (mode, selection, etc.)
4. Return value: String that becomes the tooltip
5. Fallback: If method returns None or isn't defined, bl_description is used

Use Cases

• Context-sensitive tooltips: Different text for Object Mode vs Edit Mode
• Property-based tooltips: Show information based on operator parameters
• Dynamic operators: Wrapper operators that invoke different actions based on a name/ID
• Internationalization: Return translated strings based on user locale

References

• Blender Python API - Operator
• Dynamic operator description - Interplanety

---

Files Changed

File	Change
pme_types.py	Added PMItem.description field with update callback
infra/macro.py	Set bl_description in add_macro()
editors/macro.py	Added draw_extra_settings() with Tooltip field
operators/macro.py	NEW - PME_OT_invoke_macro with dynamic description
operators/__init__.py	Import for new operator

Usage

```python

In your UI code

op = layout.operator("pme.invoke_macro", text="Run My Macro")
op.pm_name = "My Macro Name"

Tooltip will show the macro's description field!

Or from Python

bpy.ops.pme.invoke_macro(pm_name="My Macro Name")
```