Defining the Mouse Chord Behavior to Accomplish
This tutorial will cover how to give a Normal Mouse the following functionality:
- Button 3: 3 Finger Swipe Left
- Button 4: 3 Finger Swipe Right
- Button 3 Held + Right Click: Move Right a Space
- Button 3 Held + Left Click: Move Left a Space
Explanation / Background
I have a non-Apple-spec mouse with two side buttons. For years, my side buttons (3 & 4) have been set to 3-Finger Swipe Left and Right respectively in BTT, allowing me to forward and backward navigate windows in Finder, browsers, etc.
I had a second BTT function assigned to mouse buttons 3 & 4 which required Control as a modifier to either Move Left a Space or Move Right a Space between desktop spaces. I also had Middle Click set to Mission Control.
I hated that I could not navigate between spaces without reaching for my keyboard with my left hand to key Control. I also wanted to be able to selectively Middle Click a link to open it in a new tab, as is the default behavior for Middle Click, while still using Middle Click for Mission Control. Last night I decided to figure out how to do it once and for good, which took painful hours of experimentation and research.
I read a great number of unanswered help requests, feature requests, and discussions here on these forums asking for the same and similar behaviors. The closest to an answer typically found in these threads was unsatisfactory suggestions to use additional software in combination with BTT to achieve the desired behavior. Intuitively, I knew there must be a way to accomplish the desired behaviors only using BTT. This is the working solution I eventually pieced together. Perhaps this is obvious to seasoned BTT tinkerers, but it was far from obvious to me.
I will attempt here to offer the simple explanation I wish I had many agonizing hours ago. I think this will be most effective if I use my specific use case as an example, from which future readers of this should be able to immediately infer what must be done for their own use cases.
Implementing Mouse Chords
The key to mouse chords is using conditional logic under the "Advanced Conditions" option to define our mouse button behaviors.
Create a trigger for Button 3 with action 3 Finger Swipe Left and one for Button 4 with action 3 Finger Swipe Right. Importantly, set both of these actions to Trigger on Mouse Up (for consistency) to avoid triggering any unintended 3 Finger Swipes while moving between spaces.
Button 3 (as it is the pseudo-modifier key in this example) also gets one additional setting, which is a Maximum Hold Time of 200ms. This is again important in order to avoid unintentional 3 Finger Swipes upon completion of a Move [Direction] a Space action; i.e. immediately issuing a 3 Finger Swipe upon arriving at your destined space.
Button 3 configs should look like this:
Important: Complete the following instructions in sequence to eliminate the possibility of getting stuck with no mouse inputs.
Create a new trigger, but do not assign it yet. Instead, we will first assign the resulting action. Select Move Left a Space, then go to the Advanced tab and open Advanced Conditions. Enter the following condition either as code or via the GUI:
currently_pressed_mouse_buttons CONTAINS "3,"
Note: If you are using a different mouse button as your pseudo modifier, replace "3," with the value shown in the righthand panel while test clicking the button.
Required: You must set the logic to CONTAINS and include the comma in the value input.
Next, under the Basic Config tab, assign this trigger to Left Click and then check the box to allow binding without modifiers:
Finally, repeat Step 2 for the Right Click / Move Right a Space pairing, and test your triggers to ensure they are working correctly. With any luck you'll have now successfully implemented the desired behaviors in a small fraction of the time and headache it costed me!
Step 3 (Optional)
Extend the same pattern of conditions and behaviors to any other mouse buttons and actions you may desire. E.g. Button 3 Held + Scroll Up: Mission Control
Important: If you want to apply this type of behavior to other mouse buttons which are also assigned to another trigger/action (non-default button behavior), you may have to implement counter-exclusive logic in the Advanced Conditions of both trigger/action sets.
E.g. If Middle Click is assigned Mission Control and "Button 3 Held + Middle Click" is assigned some other behavior, you may find instances where you need to add conditional logic to the Advanced Conditions of both trigger sets specifying the behavior is only valid when Button 3 is pressed and not pressed respectively.