Choose the smallest correct layer
| Need | Use | Result |
|---|---|---|
| One trigger chooses one action now | Command branch | The decision happens when the item is invoked. |
| Two controls should appear only in their valid states | Poll methods | The invalid control is not offered. |
| One visible control should show the current state | Custom item | Its label, icon, and target can be derived while drawing. |
Command branch
Use a short conditional when only the action changes:
open_menu("Edit Tools") if C.mode == "EDIT_MESH" else open_menu("Object Tools")This is appropriate for routing an action. Keep branch order explicit and finish with a safe fallback.
Poll-gated alternatives
Use two items with mutually exclusive Poll methods when the user benefits from seeing only the action that can run. The historical edge-selection recipe illustrates the shape:
import bmesh
bm = bmesh.from_edit_mesh(C.object.data)
return any(edge.select for edge in bm.edges)The complement belongs on the alternate item. Ensure both expressions are evaluated only in a valid Edit Mesh context.
Custom stateful control
Use a Custom item when label and icon should describe the live state:
is_enabled = C.window_manager.some_feature_enabled
text = "Disable" if is_enabled else "Enable"
icon = "PAUSE" if is_enabled else "PLAY"
L.operator("example.toggle_feature", text=text, icon=icon)Replace the illustrative property and operator with the add-on or Blender API you actually own. The point is the separation: read state once, derive presentation, then draw the control.
Pitfalls
- Use Poll methods to prevent impossible actions while leaving ordinary choices visible.
- A Custom drawing expression can run repeatedly. Avoid mutating Blender data while drawing it.
- Conditions control availability; the item still needs a Blender editor and mode where its action is valid.