Modifiers and timing
A gesture trigger can require modifiers: keyboard keys or extra mouse buttons that you hold or press along with the gesture. The same drawn shape can then run a different action with each modifier. This page states the exact rules. Hotkey triggers also have modifiers, with simpler rules (see Modifiers on a hotkey).
Choosing modifiers
Modifiers are part of a gesture trigger in the Action editor.
- Open the action on the Actions page and expand its gesture trigger.
- Under Modifiers, click each key or button the gesture needs ①. Click it again to remove it.
- In Advanced mode, choose Timing ②: Before, After or Either.
- In Advanced mode, with a keyboard modifier picked, choose what happens to the held keys while the action runs ③ (see Held modifier keys).
The modifiers you can pick:
| Modifier | Counts as |
|---|---|
| Ctrl, Shift, Alt, Win | Either key of the pair: left Ctrl and right Ctrl are both Ctrl. |
| Left button, Middle button, Right button, Side button 1, Side button 2 | A mouse button other than the one you draw with. |
When Windows has the mouse buttons switched, button names follow Windows: the right button is the one that opens context menus.
Advanced mode. Timing and Held modifier keys are shown in Advanced mode only. In Simple mode a new gesture trigger uses Either and Release, then restore. Simple mode never changes a value you set in Advanced mode.
The exact-match rule
A gesture records two sets of modifiers while you draw it:
- Held before: the keys and mouse buttons held at the moment you press the draw button, plus a recent wheel turn (Wheel turns).
- Pressed during: every key and mouse button you press after the gesture started. A key stays in this set even if you release it before you finish. A key you were already holding before the press does not count as pressed during, however long you hold it.
A trigger's modifiers must equal one of these sets exactly. A subset is not enough, and extra keys are not ignored:
- A trigger that needs Shift does not match while you hold Shift and Alt.
- A trigger that needs Shift and Alt does not match while you hold only Shift.
The two sets are never combined. Holding Shift before and pressing Ctrl during gives "Shift" before and "Ctrl" during. Neither set is "Shift and Ctrl", so a trigger that needs both keys does not match.
Timing
Timing says which of the two sets a trigger checks:
| Timing | The trigger matches when |
|---|---|
| Before | The keys held before equal its modifiers. What you press during does not matter. |
| After | The keys pressed during equal its modifiers. What you held before does not matter. |
| Either | Either set equals its modifiers. |
A new gesture trigger made in the configuration window uses Either. A gesture trigger written in the configuration file without a timing uses Before.
No modifiers means none at all
A trigger with no modifiers is the exception to the timing rule. It matches only when both sets are empty: nothing held when you pressed the draw button, nothing pressed while you drew, and no recent wheel turn. Its timing does not matter.
So a plain gesture never wins over its modified variant. If one action has a plain Swipe left and another has Swipe left with Ctrl, After, pressing Ctrl while you draw always runs the second one, whichever comes first in the list.
Timelines
In these examples the draw button is the right button, and Ctrl is an ignored modifier key, as it is by default (Ignored modifier keys).
| What you do | Held before | Pressed during | Matches | Does not match |
|---|---|---|---|---|
| Hold Shift. Press the right button, draw, release. Release Shift. | Shift | (none) | Shift Before, Shift Either | Shift After, no modifiers |
| Press the right button, start drawing, press and release Ctrl, finish, release. | (none) | Ctrl | Ctrl After, Ctrl Either | Ctrl Before, no modifiers |
| Hold Shift. Press the right button, press Alt while you draw, release. | Shift | Alt | Shift Before, Alt After, Shift Either, Alt Either | Shift and Alt (any timing) |
| Hold Shift and Alt. Press the right button, draw, release. | Shift, Alt | (none) | Shift and Alt Before or Either | Shift Before |
| Press the right button, draw, press and release Shift, then press Alt, release. | (none) | Shift, Alt | Shift and Alt After or Either | Shift After, Alt After |
| Hold Ctrl. Press the right button. | Nothing: Ctrl is an ignored modifier key, so the right-click goes to the window as a normal click and no gesture starts. | |||
| Hold the left button. Press the right button, draw, release. | Left button | (none) | Left button Before or Either | no modifiers |
| Press the right button, draw, click the middle button, release. | (none) | Middle button | Middle button After or Either | no modifiers |
| Turn the wheel, then press the right button within half a second and draw. | Wheel | (none) | No trigger made in the configuration window | no modifiers |
When more than one trigger in the same app group matches, as in the third row, the first one in match order runs (Matching).
Mouse buttons as modifiers
- Held before. A mouse button held when you press the draw button. The press of that button has already reached the window under the pointer, because no gesture was running yet.
- Pressed during. A mouse button pressed while you draw. Its press and release are kept from the window under the pointer and only count toward the gesture. This includes a second draw button: pressed during a gesture, it is a modifier, not the start of a new gesture.
A mouse-button global event still fires for a button pressed during a gesture (Global events).
Keys you can't hold before a gesture
Two kinds of modifier can never be held before a gesture starts:
- An ignored modifier key. Holding it when you press the draw button means "no gesture this time", so the gesture never starts (Ignored modifier keys).
- A draw button. Pressing a draw button starts its own gesture, so it can't be held waiting for another one.
With Before timing the modifier picker refuses both, and shows the reason when you point at the refused chip. With After or Either you can pick them, because pressing them during the gesture works. A trigger already set up that way (for example in the configuration file) shows its chip in red with the reason below, and never matches through the before set.
Wheel turns
Turning the mouse wheel shortly before you press a draw button counts as a modifier held before: Wheel modifier window on the General page sets how soon (default 500 ms). Turning the wheel while you draw counts as pressed during. Wheel up and wheel down are separate modifiers.
The engine matches wheel modifiers, but the modifier picker doesn't offer them, so a trigger made in the configuration window never has one. Such a trigger doesn't match a gesture you start within the wheel modifier window after scrolling: the recent wheel turn is a modifier the trigger doesn't list. This is by design. If you often draw right after scrolling, lower Wheel modifier window (Advanced mode); at 0, earlier wheel turns don't count. Wheel turns inside an exclusion zone that covers the wheel never count.
Held modifier keys
When an action starts, the keys you held for its trigger can still be down. An action that types text or presses keys would then send them with Ctrl or Alt still held. Held modifier keys chooses what happens:
- Release, then restore (the default for a new trigger). Before the action runs, the engine releases the modifier keys the trigger matched. When the action, including any before and after actions, has finished, it presses again only the keys you are still physically holding. While they are released, their key repeat is held back, so a held key doesn't press itself again in the middle of the action. A key you released and pressed again yourself is left to you.
- Leave held. Nothing is released. The action's script handles the keys itself. A trigger written in the configuration file without this setting uses Leave held.
For a gesture, only keyboard modifiers are released; a held mouse button is never released. The choice is shown only when the trigger has a keyboard modifier. If input handling stops while the action runs (for example the engine is disabled), nothing is pressed again.
How modifiers decide which action runs
Modifiers are one condition of a trigger, checked together with the gesture, the draw button, the active profile and, when the app group uses them, its regions. They never change which app group's actions are tried first:
- The app group of the window where the gesture starts is tried first. An action there whose trigger matches runs, even if a Global action would also match.
- Within the group, actions are tried in match order, and the first matching trigger wins; with regions on, the matching trigger with the fewest cells wins, and the order breaks ties (Scope and fallback).
- Only when nothing in the group matches does the gesture fall back to Global, if fallback is on (Scope and fallback).
The Action editor flags two triggers in one group that the same gesture can satisfy, unless the first one is the narrower of the two, and says which one wins.
Modifiers on a hotkey
A hotkey's modifiers are Ctrl, Shift, Alt and Win, and they must match exactly: Ctrl+K does not run for Ctrl+Shift+K. A hotkey has no timing and no mouse-button modifiers. See Hotkeys.