Skip to main content

Control Flow Actions

BetterTouchTool offers various control flow actions.

if condition

If Conditions​

If conditions always need at least 3 actions in BTT:

  • The condition (which can be based on variables, on whether a specific image or text is visible on your screen, on a JavaScript function ("If Java Script Returns True") or on an AI prompt ("If AI Condition Is True"))
  • An action that runs if the condition is true
  • The "End If Condition"

If you want to run different actions when the condition is false, add the following before the End If:

  • The "Else" branch action
  • The actions that should run if the condition is false

The screenshot above shows an example that starts by asking the user for input. That input is saved to the variable var1. Next comes an if condition that checks whether var1 is 1 and, if so, runs a "Show HUD" action. After that, another if condition runs different actions depending on whether var1 equals 0 or not.

Repeat actions after accumulating movement​

Only Continue After Accumulating Movement / Value lets a continuous gesture repeat a discrete action or keyboard shortcut once per distance traveled. Find it under Action Sequence Flow Control and place it before the actions you want to repeat, in the same continuous action category.

For example, add the following under a trackpad gesture's Swipe Right (Continuous) category:

  1. Only Continue After Accumulating Movement / Value, with Movement / Value Threshold set to 5.
  2. A keyboard shortcut that selects the next tab.

The following actions run once for each threshold crossed. For continuous swipes and edge slides, 5 means 5% of the trackpad's width or height after activation. Pinch uses magnification percentage points, rotation uses degrees, and mouse drags use pixels; other value-producing triggers use their own change units. Unlike Debounce, this measures movement rather than elapsed time.

Partial movement is retained: with a threshold of 5, movements of 3 then 4 run the following sequence once and leave 2 toward the next execution. One larger update can run the sequence multiple times. There is a limit of 32 executions per input update; extra whole steps are skipped and the fractional remainder is kept.

Reset Partial Movement When Direction Reverses is enabled by default. It is useful in While Moving, where one action receives both directions. New continuous trackpad gestures also reset the remainder, as does returning to a directional swipe category after reversing. Mouse drags can keep partial movement across separate drags and pauses.

Use separate threshold actions in opposite directional categories when you want different shortcuts in each direction. An execution below the threshold stops that sequence; it does not leave it waiting in the background. Without a numeric trigger value, the actions after this gate do not run.

Debounce For complete setups, see Fluid / Continuous Gestures and Continuous Mouse Drags. If the action already has a numeric field you can drive directly, use an Action Value Binding instead.

Wait For Condition To Become True​

This action is helpful if you want to wait for something before triggering other actions. For example, to create a keyboard shortcut that automatically maximizes a window once the app has fully launched, you could do it like in this screenshot: if condition

Loops​

If you want to repeat the same actions multiple times, use the "Start Repeat / For Loop" action.

The following screenshot shows an example that first asks the user how many times the loop should repeat, then runs a "Show HUD" action that many times.

You can access a loop's current counter (e.g. from scripts) via the variable loop_loopname, which BTT fills in automatically.

loop

Cycle Through Multiple Actions​

Sometimes you might want one trigger to run different actions when you trigger it repeatedly. For example, a keyboard shortcut you press several times to cycle through different window positions. You can do this with the "Cycle through multiple actions (on repeated trigger)" action. It can contain multiple action sequences that run step by step: one action sequence each time the trigger fires.

First, assign the "Cycle through multiple actions (on repeated trigger)" meta-action to a trigger: alt text

Then you can configure the different "cycle phases" and assign multiple actions to each phase: cycle multiple cycle multiple 2

Delays​

You can use several types of delays in your action sequences.

Async / Non-Blocking Delay​

This is the most common and most useful type of delay (predefined action "Pause Execution / Delay Next Action (async / not blocking)"). It makes an action sequence wait for the specified amount of time, but doesn't block anything else in BTT.

Async Delay

Blocking Delay​

A blocking delay (predefined action "Pause Execution / Delay Next Action (blocking)") freezes the whole BetterTouchTool process for the specified amount of time. This can be useful in some situations, but use it carefully. Usually the async delay is much better.

Execute Action Sequence After Delay​

This is a powerful advanced feature (predefined action "Execute Action Sequence after Timeout / Delay"). When executed, it starts a named timer with a fixed duration. Once the time is up, the assigned action sequence runs. The great thing is that you can cancel the timer as long as it hasn't run its actions yet. Use the predefined action "Cancel Timed Action Sequence" for that.

alt text alt text