Docs
Download

Modal operators

Operators that keep running and follow the mouse and keyboard until they end.

A modal operator keeps running after it starts and gets every event (each mouse move, click and key press) until it ends. Blender's Grab (G), Knife and Loop Cut work like this: you move the mouse, the result follows, and a click or Esc ends it. Set an Operator node's Invoke Type to Modal under Settings to build one.

The example on this page is Scrub Frames: move the mouse left or right to change the current frame, click to confirm.

The Scrub Frames modal operator: Start sets a header text and cursor, Modal finishes on a left click and otherwise adds the mouse movement to the current frame, End clears the header text and cursor

How it runs

With Invoke Type Modal, the Operator node has three flows:

OutputRuns
StartOnce, when the operator starts. Set things up: a header text, the cursor
ModalFor every event while it runs. Event is the current event
EndOnce, when it ends, however it ends: finished, cancelled, or stopped by Blender. Clean up here

The operator keeps running until a Return node in the Modal flow ends it, or Esc or right click cancels it.

Building Scrub Frames

Add an Operator node, label it "Scrub Frames" and set Invoke Type to Modal in Settings.

On Start: a Set Header Text with "Move the mouse to change the frame, click to confirm", then a Set Cursor set to Scroll-X.

On Modal: an If/Else. Its Condition is an Is Key set to Left Mouse and Press, with the Operator's Event connected. Then goes to a Return set to Finish.

On Else: a Set Property for Blender's scene.frame_current. Its Value is a Math (Add) of the current frame (a Blender Data node, scene.frame_current) and X of Event Info › Mouse Offset, through a Separate Vector. Use the Integer Result: frames are whole numbers.

On End: a Set Header Text with an empty text, which removes it, and a Set Cursor set to Default.

Run it from a button or a shortcut over the 3D Viewport. The header text shows at the top of the editor while it runs:

The 3D Viewport with the text "Move the mouse to change the frame, click to confirm" below its header

Ending it

Return (Add › Operators › Modal) decides what happens after the current event:

Result
FinishEnds the operator; what it did gets an undo step. End runs
CancelEnds the operator without an undo step. End runs. What it changed stays changed: to undo it, store the old values in Start (in operator properties) and set them back before you cancel
Pass ThroughKeeps running and lets Blender handle the event too, e.g. so the mouse wheel still zooms the view
Keep RunningSkips the rest of the flow and waits for the next event

Without a Return, the operator keeps running after each event and Blender doesn't see the event.

Settings

Two settings in the Operator's Settings popup only show for Modal:

  • Cancel with Esc / Right Click (on by default): pressing Esc or the right mouse button cancels the operator before the Modal flow runs. Turn it off to handle these keys yourself, e.g. to restore values before you cancel.
  • Timer: also runs Modal every this many seconds, even when nothing happens. The event's type is then TIMER. Use it for animations or to check something regularly. 0 (the default) means only real events.

Nodes for modal operators

All under Add › Operators › Modal:

Node
ReturnEnds the operator, passes the event on or waits for the next one, see Ending it
Is KeyIs Key is True if the Event is the picked key or mouse button and, with Press or Release, was pressed or released (Any: either). The list has all of Blender's keys, mouse buttons, the wheel and more. Default Left Mouse
Event InfoWhat the Event is, see below
Set Header TextShows Text at the top of the current editor. An empty text removes it
Set Status TextShows Text in the status bar instead of Blender's own, e.g. "Click: confirm, Esc: cancel". An empty text shows Blender's own again
Set CursorChanges the mouse cursor to the picked one (default Crosshair) until it's changed again. Default sets it back

Is Key and Event Info need an event: connect the Operator's Event output. In a function called from a modal operator they use the caller's event when the input isn't connected.

Set Header Text, Set Status Text and Set Cursor work in any operator, but they stay until something sets them back. Reset them in End, which runs on every way the operator can end.

Event Info

Output
TypeThe key or button, as Blender names it: "LEFTMOUSE", "A", "WHEELUPMOUSE", "MOUSEMOVE", "TIMER"
Value"PRESS", "RELEASE", "CLICK", "DOUBLE_CLICK", "CLICK_DRAG" or "NOTHING" (mouse moves)
Previous Type / Previous ValueThe same for the event before
Is RepeatTrue for a key held down that repeats
Shift, Ctrl, Alt, OS KeyWhether these modifier keys are held (OS Key: Cmd or the Windows key)
TextThe character a key types, for text input; empty for other keys
Mouse in RegionThe mouse position in the editor's main region, in pixels from its bottom left
Mouse in WindowThe mouse position in the Blender window
Mouse OffsetHow far the mouse moved since the previous event, in pixels (X, Y)
PressureTablet pen pressure, 0 to 1 (1 for a mouse)
TiltTablet pen tilt (X, Y)

Limitations

  • A modal operator only starts from the interface: a button, a menu, a shortcut, the operator search, or a Run Operator with Invoke Default. With Exec Default (the default of Run Operator) or from Python, it runs its Execute flow instead, and nothing if that isn't connected.
  • The operator runs in the editor it was started from. Mouse positions are relative to that editor's region.
  • Each event runs the whole Modal flow. Keep it fast: heavy work on every mouse move makes Blender lag.