QMK: Mouse Turbo Click

← More about keyboards

This post describes a QMK module “Mouse Turbo Click” that clicks the mouse rapidly:

• Pressing and holding the Turbo Click button sends rapid mouse clicks, about 12 clicks per second.

• Quickly double tapping the Turbo Click button “locks” it. Rapid mouse clicks are sent until the Turbo Click button is tapped again.

Turbo Click may be advantageous in certain computer games. It could also be used in art programs to paint in a dashed pattern. I don’t know that there is a “serious” use, but it is interesting how auto-repeating actions like this can be implemented in QMK.

Add it to your keymap

Step 1: Install my community modules. Then enable module getreuer/mouse_turbo_click in your keymap.json file. Or if keymap.json does not exist, create it with the following content:

{
  "modules": ["getreuer/mouse_turbo_click"]
}

Step 2: Use keycode TUBRO somewhere in your layout.

Non-module installation (historical)

Follow these instructions to install the non-module implementation of Mouse Turbo Click. If you are new to QMK macros, it may help to read my macro buttons post for an intro.

Step 1: In the directory containing your keymap.c, create a features subdirectory and copy mouse_turbo_click.h and mouse_turbo_click.c there.

Step 2: In your rules.mk file, add

SRC += features/mouse_turbo_click.c

MOUSEKEY_ENABLE = yes
DEFERRED_EXEC_ENABLE = yes

Step 3: In your keymap.c, add a custom keycode TURBO for activating Turbo Click and use the new keycode somewhere in your layout.

enum custom_keycodes {
  TURBO = SAFE_RANGE,
  // Other custom keys...
};

Step 4: Handle Turbo Click from your process_record_user() function by calling process_mouse_turbo_click(), passing your custom keycode as the third argument:

#include "features/mouse_turbo_click.h"

bool process_record_user(uint16_t keycode, keyrecord_t* record) {
  if (!process_mouse_turbo_click(keycode, record, TURBO)) { return false; }
  // Your macros ...

  return true;
}

Customization

Click period

The clicking speed is controlled by MOUSE_TURBO_CLICK_PERIOD, set to a period of 80 milliseconds by default for 1000 / 80 = 12.5 clicks per second. To change the click rate, define MOUSE_TURBO_CLICK_PERIOD in config.h like

// Click every 200 ms for 5 clicks per second.
#define MOUSE_TURBO_CLICK_PERIOD 200

A smaller period implies faster clicking. Beyond some point, it is conceivable that QMK or the application running on the computer is overwhelmed with handling the rapid mouse clicks. I suggest setting the period no smaller than 10 ms or hundred clicks per second.

Click key

By default, Turbo Click clicks the first mouse button MS_BTN1. To click a different button, define MOUSE_TURBO_CLICK_KEY in config.h. For instance, you could spam the Space key instead with

// Repeatedly click the Space key.
#define MOUSE_TURBO_CLICK_KEY KC_SPC

MOUSE_TURBO_CLICK_KEY may be set to any basic keycode or 16-bit keycode that works with register_code16(), which includes at least modifier + basic key chords. If set to a non-mouse key, MOUSEKEY_ENABLE = yes is no longer required.

Explanation

The implementation uses mouse keys and a periodic callback using the deferred execution API. When Turbo Click starts, turbo_click_callback() is scheduled. The callback executes twice per click, alternating between pressing and releasing MOUSE_TURBO_CLICK_KEY. When Turbo Click stops, the callback is canceled and the key is released if needed.

← More about keyboards

Google Scholar LinkedIn