Common Button Settings¶
Whatever its type, a button carries the same blocks of settings. They appear in the editor's right column, and in the Edit Button dialog opened from Preview — Edit Mode.
Help Mode
With Options ▸ UI Settings ▸ Help Mode on, each block gets a ? button opening the matching section below.
Identity¶
Name¶
Internal name of the button, shown in the item list of the editor. It is never drawn in the menu — use it to find the button again in a long list.
Type¶
What the button does: see the button types overview.
Label¶
The text drawn in the menu. Leave it empty for an icon-only button.
A label can be dynamic: {{...}} tokens and pm.var() are evaluated at draw time, so the label can show the current mode, the active object or a variable.
Label Align¶
Where the label sits in the space the icon leaves free — Default (centered when there is no icon, next to the icon otherwise), Left, Center or Right.
Tooltip¶
The description shown when the button is hovered. Its show and hide delays are global: Options ▸ Menus Settings ▸ Tooltip Show / Hide Delay.
Tooltip Media¶
An image or a GIF displayed above the tooltip text, with its own width and playback speed. Useful to show what a tool actually does.
Icon Settings¶
Icon¶
Blender icon name (MESH_CUBE) or the path to your own image. The picker lists both; folders scanned for custom images are set in Options ▸ User Icon Directories.
Dynamic Icon¶
A Python expression evaluated at draw time, whose result is used as the icon name. This is how a button shows the state it controls — the pivot point, the current mode, the active brush.
See States for the full pattern.
Icon Size¶
Overrides the icon size for this button only. 0 = follow the menu design.
Icon Side¶
Which side of the label the icon is drawn on. Icon-only buttons stay centered whatever this says.
Action Settings¶
The middle block changes with the type — operator id, property path, target menu, drawer contents. Each type documents its own fields:
- Actions —
OPERATOR,PROPERTY,PYTHON,SHORTCUT,BUTTON_TOGGLE - Navigation —
PIE_CALL,MENU_CALL,LAYOUT_CALL,GPU_MENU - Widgets —
SLIDER,INT_PROP,FLOAT_PROP,ENUM_PROP,COLOR_PROP,SEARCH_PROP,LIST - Display —
LABEL,SECTION,DRAWER,SEPARATOR
Pre Operator¶
An operator run just before the button's own action — typically a mode change, so a pie called from Object Mode lands in the right mode.
Auto Open on Hover¶
For the buttons that open something (PIE_CALL, MENU_CALL, LAYOUT_CALL, GPU_MENU, DRAWER): open it on hover, with no click. Action buttons have the same switch to fire on hover.
Hover Open Delay¶
Seconds to wait before that hover fires, for this button only. 0 = instant. The global default is in Options ▸ Menus Settings ▸ Hover Open Delay.
Multi Edit¶
Whether the button acts on the whole selection or on the active object only.
Default means two different things, because the safe answer differs by type: properties and sliders are written to every selected object, operators run on the active object only. On and Off force it either way.
Conditions¶
Condition¶
Python expression deciding whether the button is drawn at all. Empty = always drawn.
Full syntax and a reference of the usual conditions: Conditions.
Depress Condition¶
Python expression deciding whether the button is drawn pressed, with the active color. This is how a button shows that the thing it toggles is currently on.
Toggle Condition¶
The ID of a BUTTON_TOGGLE button. The button is drawn only while that toggle is active — the tab mechanism.
Shortcuts¶
Hotkey¶
A key pressed while the menu is open to fire this button. Sequences and alternates are allowed: g, az, g, f2, num0 g.
Global Shortcut¶
A real keymap entry: the button fires from its own key with no menu open at all. Two modes:
- Shortcut — key plus modifiers, edited with Blender's own keymap widget (Press / Click / Double Click / Click Drag).
- Gesture — a key combination plus a 3x3 grid shape, so one key holds several buttons apart. See Preferences ▸ Gestures.
Context decides which editor the shortcut is active in.
Layout¶
Col Span and Row Span¶
How many grid columns and rows the button occupies. They only exist in a GRID direction — a SINGLE direction lays its buttons out in one line.
Details and examples: Layouts & Col Span.
Section Outside¶
Draws the button outside the section it sits next to, instead of inside it. Only offered when the container actually holds a SECTION.
Close on Click¶
Overrides, for this button, whether the menu closes when the button is clicked. Offered on menus and layouts, on pies without a center circle, and always on SEARCH_PROP — opening its dropdown is not the end of the interaction.
Colors¶
Override Colors¶
Replaces the menu design's colors for this button only: button, button hover and text.
Each one also accepts a Dynamic Color — a Python expression returning the color — and the whole override can be gated by a Color Condition, so the button only takes the custom colors when the condition is true.
Menu-wide colors are set in the design: Design.
Trigger Variants¶
The same button can carry up to 40 alternate actions, each with its own trigger: Shift / Ctrl / Alt click, drags in four directions, horizontal and vertical drag, key hold, hover.
See Trigger Variants.
States¶
A button can change label, icon and color depending on a condition, without becoming a second button.
See States.