Browse the docs

Key or button held

Passes while a key or a mouse button is held down.

key is held down

Keyboard Maestro: Key (Down, Up), Mouse Button (Pressed, Not Pressed)

Examples #

Is Space held
Do
  1. If the key “space” is down
  2. Show “Space is down”
Open in Switchboard to try it
Is the left button held
Do
  1. If mouse button 1 is down
  2. Show “Left button is down”
  3. Else
  4. Show “Left button is up”
Open in Switchboard to try it

Details #

Passes while the key or mouse button you name is being held down at the moment the condition is checked. Give one of key or mouseButton; if both are given, key wins.

key is a key name or a virtual key code. A name is a letter or digit (a, 7), or one of the names a hotkey uses: space, return, tab, escape, delete, left, f5, keypad5 and so on, or a glyph such as ↩. A number is the key code itself: 0 is A, 49 is Space, 56 is Left Shift. Letters and punctuation are read from a US layout; use the code (or record the key in the Inspector) for a key that sits elsewhere on yours. mouseButton counts from 1: 1 is left, 2 is right, 3 is middle, and higher numbers are the extra buttons.

The trace shows the key code (and the keyName you wrote, if any) or the mouseButton, and whether it was down. For modifier keys alone, Modifier held is easier. Reading the keyboard and mouse is harmless, so it happens for real in a dry run too.

Every condition accepts "negate": true, which flips the verdict. The trace records what was compared before the flip, so a negated condition that blocks a macro still shows the real values.

Conditions in an Only if list combine with all: every one must pass, and an empty list always passes. An if step or a repeat loop takes a match of all (default) or any.

Parameters #

ParameterTypeRequiredValuesWhat it does
keyany valueThe key to test: a name such as a, space or f5, or a virtual key code as a number.
mouseButtonany valueThe mouse button to test, counting from 1: left, right, middle, then the extra buttons.

Gotchas #

  • With neither param it fails with inputDown needs a key code or a mouse button.

  • It reads the state at that instant. By the time a hotkey macro runs, the keys that fired it may already be up.

  • One key only: cmd+a fails with a message pointing at Modifier held, which checks modifiers.

  • A name it doesn't know fails with "…" isn't a key.

See also #