Skip to main content
Some workflows need a keyboard modifier to be held down while another action runs — for example, holding shift while clicking to extend a selection, holding ctrl while clicking multiple files, or holding alt while scrolling to trigger an alternate gesture. The key action supports an optional down parameter that controls whether the key is pressed, held, or released. Pair a down=true call with a later down=false call on the same key so the key never ends up stuck in the pressed state.
Key syntax: Use + to press keys together as one chord, e.g. ctrl+a or alt+tab. A chord can combine multiple modifiers (ctrl, alt, shift, win) but only one non-modifier key. Use spaces to press keys one after another, e.g. down down down (tap Down three times) or ctrl+c ctrl+v. Joining repeated or multiple non-modifier keys with + (e.g. down+down+down) is invalid — use spaces instead.

​
The down parameter

down is tri-state:
down only applies to the key action. It is ignored for type and every other action.

​
Basic usage pattern

To hold a key while performing another action:
1

Press the key down and hold

Call key with the key chord and down=true. The key stays pressed until you release it.
2

Perform the action

Call left_click, mouse_move, scroll, or any other action while the key is held.
3

Release the key

Call key again with the same key and down=false to release it.

​
Example: shift-click to extend a selection

​
Example: ctrl-click to toggle multi-select

​
Example: ctrl-scroll to zoom

​
Guidelines

  • Always pair down=true with a matching down=false. If you hold a modifier and forget to release it, every subsequent action in the workflow will be affected, and downstream typing or shortcuts will behave unexpectedly.
  • Release the same key you pressed. If you pressed shift down, release shift, not lshift or shiftleft.
  • Avoid key chords with down=true. down is designed for simple modifier keys like shift, ctrl, alt, and win. Do not use it with chords such as ctrl+shift.
  • Prefer the default full-press form when you don’t need to hold. If you just need ctrl+a as a one-shot, use action="key" with text="ctrl+a" and no down parameter. That’s the normal behavior.
  • Take a screenshot after releasing if you need to verify the result. The screenshot after a down=true call shows the screen while the key is held, which is usually not what you want to verify against.

​
Comparison with modifier-click shortcuts

For simple modifier combinations like ctrl+a (select all), ctrl+c (copy), or alt+tab (switch window), keep using the default key action with the chord directly:
This presses and releases the chord in one atomic step. You only need the down parameter when the held key has to span another action, such as a click, a mouse move, or a scroll.