tap_hold.md (40908B)
1 # Tap-Hold Configuration Options 2 3 While Tap-Hold options are fantastic, they are not without their issues. We have tried to configure them with reasonable defaults, but that may still cause issues for some people. 4 5 These options let you modify the behavior of the tap-hold keys. 6 7 ## Tapping Term 8 9 The crux of all of the following features is the tapping term setting. This determines what is a tap and what is a hold. The exact timing for this to feel natural can vary from keyboard to keyboard, from switch to switch, and from key to key. 10 11 ::: tip 12 `DYNAMIC_TAPPING_TERM_ENABLE` enables three special keys that can help you quickly find a comfortable tapping term for you. See [Dynamic Tapping Term](#dynamic-tapping-term) for more details. 13 ::: 14 15 You can set the global time for this by adding the following setting to your `config.h`: 16 17 ```c 18 #define TAPPING_TERM 200 19 ``` 20 21 This setting is defined in milliseconds and defaults to 200ms. This is a good average for the majority of people. 22 23 For more granular control of this feature, you can add the following to your `config.h`: 24 ```c 25 #define TAPPING_TERM_PER_KEY 26 ``` 27 28 You can then add the following function to your `keymap.c` to customise the tapping term for each key: 29 30 ```c 31 uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { 32 switch (keycode) { 33 case SFT_T(KC_SPC): 34 return TAPPING_TERM + 1250; 35 case LT(1, KC_GRV): 36 return 130; 37 default: 38 return TAPPING_TERM; 39 } 40 } 41 ``` 42 43 ### Example 44 45 You can compare keycodes to `QK_MOD_TAP`/`QK_MOD_TAP_MAX` and `QK_LAYER_TAP`/`QK_LAYER_TAP_MAX` to filter out Mod-Tap/Layer-Tap keys, rather than checking such keys manually in a switch-case. For instance, this example sets all Mod-Tap keys to have a higher tapping term, while leaving all other tap-hold keys unchanged: 46 47 ```c 48 uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { 49 switch (keycode) { 50 case QK_MOD_TAP ... QK_MOD_TAP_MAX: 51 return TAPPING_TERM + 100; 52 default: 53 return TAPPING_TERM; 54 } 55 } 56 ``` 57 58 You can also use functions like `QK_MOD_TAP_GET_MODS`, `QK_LAYER_MOD_GET_MODS`, and `QK_ONE_SHOT_MOD_GET_MODS` to filter Mod-Tap/Layer-Mod/One Shot keys by their mods. 59 60 For instance, this example sets a higher tapping term for `AltGr` Mod-Taps and lower tapping terms for `Shift` Mod-Taps: 61 62 ```c 63 uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { 64 uint8_t mod = mod_config(QK_MOD_TAP_GET_MODS(keycode)); 65 if (mod & MOD_LSFT != 0 || mod & MOD_RSFT != 0) { 66 return 100; 67 } 68 if (mod & MOD_RALT != 0) { 69 return TAPPING_TERM + 50; 70 } 71 return TAPPING_TERM; 72 } 73 ``` 74 75 ### Dynamic Tapping Term {#dynamic-tapping-term} 76 77 `DYNAMIC_TAPPING_TERM_ENABLE` is a feature you can enable in `rules.mk` that lets you use three special keys in your keymap to configure the tapping term on the fly: 78 79 | Key | Aliases | Description | 80 |-------------------------------|---------|-------------------------------------------------------------------------------------------| 81 |`QK_DYNAMIC_TAPPING_TERM_PRINT`|`DT_PRNT`| Types the current tapping term, in milliseconds | 82 |`QK_DYNAMIC_TAPPING_TERM_UP` |`DT_UP` | Increases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) | 83 |`QK_DYNAMIC_TAPPING_TERM_DOWN` |`DT_DOWN`| Decreases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) | 84 85 Set the tapping term as usual with `#define TAPPING_TERM <value>` in `config.h` and add `DYNAMIC_TAPPING_TERM_ENABLE = yes` in `rules.mk`. Then, place the above three keys somewhere in your keymap and flash the new firmware onto your board. 86 87 Now, you can try using your dual-role keys such as Layer-Taps and Mod-Taps and use `DT_DOWN` and `DT_UP` to adjust the tapping term immediately. If you find that you frequently trigger the modifier of your Mod-Tap(s) by accident, for example, that's a sign that your tapping term may be too low, so tap `DT_UP` a few times to increase the tapping term until that no longer happens. Conversely, if you get superfluous characters when you actually intended to momentarily activate a layer, tap `DT_DOWN` to lower the tapping term. Do note that these keys affect the *global* tapping term, you cannot change the tapping term of a specific key on the fly. 88 89 Once you're satisfied with the current tapping term value, you can tap the `DT_PRNT` key to see your new tapping term, and you can replace the tapping term in `config.h` with this new value. 90 91 It's important to update `TAPPING_TERM` with the new value because the adjustments made using `DT_UP` and `DT_DOWN` are *not* persistent. 92 93 The value by which the tapping term increases or decreases when you tap `DT_UP` and `DT_DOWN` can be configured in `config.h` with `#define DYNAMIC_TAPPING_TERM_INCREMENT <new value>`. Note that the tapping term is *not* modified when *holding* down the tap term keys, so if you need to, for example, decrease the current tapping term by 50ms, you cannot just press down and hold `DT_DOWN`; you will have to tap it 10 times in a row with the default increment of 5ms. 94 95 If you need more flexibility, nothing prevents you from defining your own custom keys to dynamically change the tapping term. 96 97 ```c 98 enum custom_dynamic_tapping_term_keys = { 99 DT_UP_50 = SAFE_RANGE, 100 DT_DOWN_50, 101 DT_UP_X2, 102 DT_DOWN_X2, 103 } 104 105 bool process_record_user(uint16_t keycode, keyrecord_t *record) { 106 switch (keycode) { 107 case DT_UP_50: 108 if (record->event.pressed) { 109 g_tapping_term += 50; 110 } 111 break; 112 case DT_DOWN_50: 113 if (record->event.pressed) { 114 g_tapping_term -= 50; 115 } 116 break; 117 case DT_UP_X2: 118 if (record->event.pressed) { 119 g_tapping_term *= 2; 120 } 121 break; 122 case DT_DOWN_X2: 123 if (record->event.pressed) { 124 g_tapping_term /= 2; 125 } 126 break; 127 } 128 return true; 129 }; 130 ``` 131 132 In order for this feature to be effective, if you use per-key tapping terms, then you need to make a few changes to the syntax of the `get_tapping_term` function. All you need to do is replace every occurrence of `TAPPING_TERM` in the `get_tapping_term` function by lowercase `g_tapping_term`. If you don't do this, you will still see the value typed by `DT_PRNT` go up and down as you configure the tapping term on the fly, but you won't feel those changes as they don't get applied. If you can go as low as 10ms and still easily trigger the tap function of a dual-role key, that's a sign that you forgot to make the necessary changes to your `get_tapping_term` function. 133 134 For instance, here's how the example `get_tapping_term` shown earlier should look after the transformation: 135 136 ```c 137 uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { 138 switch (keycode) { 139 case SFT_T(KC_SPC): 140 return g_tapping_term + 1250; 141 case LT(1, KC_GRV): 142 return 130; 143 default: 144 return g_tapping_term; 145 } 146 } 147 ``` 148 149 The reason is that `TAPPING_TERM` is a macro that expands to a constant integer and thus cannot be changed at runtime, whereas `g_tapping_term` is a variable whose value can be changed at runtime. If you want, you can temporarily enable `DYNAMIC_TAPPING_TERM_ENABLE` to find a suitable tapping term value and then disable that feature and revert back to using the classic syntax for per-key tapping term settings. In case you need to access the tapping term from elsewhere in your code, you can use the `GET_TAPPING_TERM(keycode, record)` macro. This macro will expand to whatever is the appropriate access pattern given the current configuration. 150 151 ## Tap-Or-Hold Decision Modes 152 153 The code which decides between the tap and hold actions of dual-role keys supports three different modes, in increasing order of preference for the hold action: 154 155 1. The default mode selects the hold action only if the dual-role key is held down longer than the tapping term. In this mode, pressing other keys while the dual-role key is held down does not influence the tap-or-hold decision. In other words, this mode ignores interrupts. 156 157 2. The "permissive hold" mode, in addition to the default behavior, immediately selects the hold action when another key is tapped (pressed and then released) while the dual-role key is held down, even if this happens earlier than the tapping term. If another key is just pressed, but then the dual-role key is released before that other key (and earlier than the tapping term), this mode will still select the tap action. That is, this mode converts "nested" sequences, but not "rolls". 158 159 3. The "hold on other key press" mode, in addition to the default behavior, immediately selects the hold action when another key is pressed while the dual-role key is held down, even if this happens earlier than the tapping term. 160 161 Note that until the tap-or-hold decision completes (which happens when either the dual-role key is released, or the tapping term has expired, or the extra condition for the selected decision mode is satisfied), key events are delayed and not transmitted to the host immediately. The default mode gives the most delay (if the dual-role key is held down, this mode always waits for the whole tapping term), and the other modes may give less delay when other keys are pressed, because the hold action may be selected earlier. 162 163 ### Comparison {#comparison} 164 165 To better illustrate the tap-or-hold decision modes, let us compare the expected output of each decision mode in a handful of tapping scenarios involving a Mod-Tap key (`LSFT_T(KC_A)`) and a regular key (`KC_B`) with the `TAPPING_TERM` set to 200ms. 166 167 Note: "`kc` held" in the "Physical key event" column means that the key wasn't physically released yet at this point in time. 168 169 #### Distinct taps (AABB) {#distinct-taps} 170 171 | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | 172 |------|--------------------|----------------|-------------------|----------------------------| 173 | 0 | `LSFT_T(KC_A)` down| | | | 174 | 199 | `LSFT_T(KC_A)` up | a | a | a | 175 | 210 | `KC_B` down | ab | ab | ab | 176 | 220 | `KC_B` up | ab | ab | ab | 177 178 | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | 179 |------|--------------------|----------------|-------------------|----------------------------| 180 | 0 | `LSFT_T(KC_A)` down| | | | 181 | 200 | `LSFT_T(KC_A)` held|<kbd>Shift</kbd>| <kbd>Shift</kbd> | <kbd>Shift</kbd> | 182 | 201 | `LSFT_T(KC_A)` up |<kbd>Shift</kbd>| <kbd>Shift</kbd> | <kbd>Shift</kbd> | 183 | 205 | `KC_B` down | b | b | b | 184 | 210 | `KC_B` up | b | b | b | 185 186 #### Nested tap (ABBA) {#nested-tap} 187 188 | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | 189 |------|--------------------|----------------|-------------------|----------------------------| 190 | 0 | `LSFT_T(KC_A)` down| | | | 191 | 110 | `KC_B` down | | | B | 192 | 120 | `KC_B` up | | B | B | 193 | 199 | `LSFT_T(KC_A)` up | ab | B | B | 194 195 | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | 196 |------|--------------------|----------------|-------------------|----------------------------| 197 | 0 | `LSFT_T(KC_A)` down| | | | 198 | 110 | `KC_B` down | | | B | 199 | 120 | `KC_B` up | | B | B | 200 | 200 | `LSFT_T(KC_A)` held| B | B | B | 201 | 210 | `LSFT_T(KC_A)` up | B | B | B | 202 203 | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | 204 |------|--------------------|----------------|-------------------|----------------------------| 205 | 0 | `LSFT_T(KC_A)` down| | | | 206 | 200 | `LSFT_T(KC_A)` held|<kbd>Shift</kbd>| <kbd>Shift</kbd> | <kbd>Shift</kbd> | 207 | 205 | `KC_B` down | B | B | B | 208 | 210 | `KC_B` up | B | B | B | 209 | 220 | `LSFT_T(KC_A)` up | B | B | B | 210 211 #### Rolling keys (ABAB) {#rolling-keys} 212 213 | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | 214 |------|--------------------|----------------|-------------------|----------------------------| 215 | 0 | `LSFT_T(KC_A)` down| | | | 216 | 110 | `KC_B` down | | | B | 217 | 130 | `LSFT_T(KC_A)` up | ab | ab | B | 218 | 140 | `KC_B` up | ab | ab | B | 219 220 | Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | 221 |------|--------------------|----------------|-------------------|----------------------------| 222 | 0 | `LSFT_T(KC_A)` down| | | | 223 | 110 | `KC_B` down | | | B | 224 | 200 | `LSFT_T(KC_A)` held| B | B | B | 225 | 205 | `LSFT_T(KC_A)` up | B | B | B | 226 | 210 | `KC_B` up | B | B | B | 227 228 ### Default Mode 229 Example sequence 1 (the `L` key is also mapped to `KC_RGHT` on layer 2): 230 231 ``` 232 TAPPING_TERM 233 +---------------|--------------------+ 234 | +-------------|-------+ | 235 | | LT(2, KC_A) | | | 236 | +-------------|-------+ | 237 | | +--------------+ | 238 | | | KC_L | | 239 | | +--------------+ | 240 +---------------|--------------------+ 241 ``` 242 The above sequence would send a `KC_RGHT`, since `LT(2, KC_A)` is held longer than the `TAPPING_TERM`. 243 244 --- 245 246 Example sequence 2 (the `L` key is also mapped to `KC_RGHT` on layer 2): 247 248 ``` 249 TAPPING_TERM 250 +-----------------------------|------+ 251 | +---------------+ | | 252 | | LT(2, KC_A) | | | 253 | +---------------+ | | 254 | +--------------+ | | 255 | | KC_L | | | 256 | +--------------+ | | 257 +-----------------------------|------+ 258 ``` 259 The above sequence will not send `KC_RGHT` but `KC_A` `KC_L` instead, since `LT(2, KC_A)` is not held longer than the `TAPPING_TERM`. 260 261 --- 262 263 Example sequence 3 (Mod-Tap): 264 265 ``` 266 TAPPING_TERM 267 +---------------------------|--------+ 268 | +-------------+ | | 269 | | SFT_T(KC_A) | | | 270 | +-------------+ | | 271 | +--------------+ | | 272 | | KC_X | | | 273 | +--------------+ | | 274 +---------------------------|--------+ 275 ``` 276 In the above sequence, `SFT_T(KC_A)` has been released before the end of its `TAPPING_TERM` and as such will be interpreted as `KC_A`, 277 followed by any key event that happened after the initial press of `SFT_T(KC_A)`. In this instance, the output would be `KC_A` `KC_X`. 278 279 ### Permissive Hold 280 281 The "permissive hold" mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`: 282 283 ```c 284 #define PERMISSIVE_HOLD 285 ``` 286 287 This makes tap and hold keys (like Layer-Tap) work better for fast typists, or for high `TAPPING_TERM` settings. 288 289 If you press a dual-role key, tap another key (press and release) and then release the dual-role key, all within the tapping term, by default the dual-role key will perform its tap action. If the `PERMISSIVE_HOLD` option is enabled, the dual-role key will perform its hold action instead. 290 291 An example of a sequence that is affected by the "permissive hold" mode: 292 293 - `LT(2, KC_A)` Down 294 - `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2) 295 - `KC_L` Up 296 - `LT(2, KC_A)` Up 297 298 ``` 299 TAPPING_TERM 300 +---------------------------|--------+ 301 | +----------------------+ | | 302 | | LT(2, KC_A) | | | 303 | +----------------------+ | | 304 | +--------------+ | | 305 | | KC_L | | | 306 | +--------------+ | | 307 +---------------------------|--------+ 308 ``` 309 310 Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `PERMISSIVE_HOLD` option enabled, the Layer-Tap key is considered as a layer switch if another key is tapped, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2). We could describe this sequence as a "nested tap" (the modified key's key down and key up events are "nested" between the dual-role key's key down and key up events). 311 312 However, this slightly different sequence will not be affected by the "permissive hold" mode: 313 314 - `LT(2, KC_A)` Down 315 - `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2) 316 - `LT(2, KC_A)` Up 317 - `KC_L` Up 318 319 ``` 320 TAPPING_TERM 321 +---------------------------|--------+ 322 | +-------------+ | | 323 | | LT(2, KC_A) | | | 324 | +-------------+ | | 325 | +--------------+ | | 326 | | KC_L | | | 327 | +--------------+ | | 328 +---------------------------|--------+ 329 ``` 330 331 In the sequence above the dual-role key is released before the other key is released, and if that happens within the tapping term, the "permissive hold" mode will still choose the tap action for the dual-role key, and the sequence will be registered as `al` by the host. We could describe this as a "rolling press" (the two keys' key down and key up events behave as if you were rolling a ball across the two keys, first pressing each key down in sequence and then releasing them in the same order). 332 333 ::: tip 334 The `PERMISSIVE_HOLD` option is not noticeable if you also enable `HOLD_ON_OTHER_KEY_PRESS` because the latter option considers both the "nested tap" and "rolling press" sequences like shown above as a hold action, not the tap action. `HOLD_ON_OTHER_KEY_PRESS` makes the tap-or-hold decision earlier in the chain of key events, thus taking a precedence over `PERMISSIVE_HOLD`. 335 ::: 336 337 For more granular control of this feature, you can add the following to your `config.h`: 338 339 ```c 340 #define PERMISSIVE_HOLD_PER_KEY 341 ``` 342 343 You can then add the following function to your keymap: 344 345 ```c 346 bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) { 347 switch (keycode) { 348 case LT(1, KC_BSPC): 349 // Immediately select the hold action when another key is tapped. 350 return true; 351 default: 352 // Do not select the hold action when another key is tapped. 353 return false; 354 } 355 } 356 ``` 357 358 As in the earlier example, you can filter Mod-Tap/Layer-Mod/One Shot keys by their mods rather than checking such keys manually in a switch-case. (Also applicable to the other following `PER_KEY` functions.) 359 360 ### Hold On Other Key Press 361 362 The "hold on other key press" mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`: 363 364 ```c 365 #define HOLD_ON_OTHER_KEY_PRESS 366 ``` 367 368 This mode makes tap and hold keys (like Layer-Tap) work better for fast typists, or for high `TAPPING_TERM` settings. Compared to the "permissive hold" mode, this mode selects the hold action in more cases. 369 370 If you press a dual-role key, press another key, and then release the dual-role key, all within the tapping term, by default the dual-role key will perform its tap action. If the `HOLD_ON_OTHER_KEY_PRESS` option is enabled, the dual-role key will perform its hold action instead. 371 372 An example of a sequence that is affected by the "hold on other key press" mode, but not by the "permissive hold" mode: 373 374 - `LT(2, KC_A)` Down 375 - `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2) 376 - `LT(2, KC_A)` Up 377 - `KC_L` Up 378 379 ``` 380 TAPPING_TERM 381 +---------------------------|--------+ 382 | +-------------+ | | 383 | | LT(2, KC_A) | | | 384 | +-------------+ | | 385 | +--------------+ | | 386 | | KC_L | | | 387 | +--------------+ | | 388 +---------------------------|--------+ 389 ``` 390 391 Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `HOLD_ON_OTHER_KEY_PRESS` option enabled, the Layer-Tap key is considered as a layer switch if another key is pressed, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2). 392 393 For more granular control of this feature, you can add the following to your `config.h`: 394 395 ```c 396 #define HOLD_ON_OTHER_KEY_PRESS_PER_KEY 397 ``` 398 399 You can then add the following function to your keymap: 400 401 ```c 402 bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) { 403 switch (keycode) { 404 case LT(1, KC_BSPC): 405 // Immediately select the hold action when another key is pressed. 406 return true; 407 default: 408 // Do not select the hold action when another key is pressed. 409 return false; 410 } 411 } 412 ``` 413 414 ## Quick Tap Term 415 416 When the user holds a key after tapping it, the tapping function is repeated by default, rather than activating the hold function. This allows keeping the ability to auto-repeat the tapping function of a dual-role key. `QUICK_TAP_TERM` enables fine tuning of that ability. If set to `0`, it will remove the auto-repeat ability and activate the hold function instead. 417 418 `QUICK_TAP_TERM` is set to `TAPPING_TERM` by default, which is the maximum allowed value for `QUICK_TAP_TERM`. To override its value (in milliseconds) add the following to your `config.h`: 419 420 ```c 421 #define QUICK_TAP_TERM 120 422 ``` 423 424 Example: 425 426 - `SFT_T(KC_A)` Down 427 - `SFT_T(KC_A)` Up 428 - `SFT_T(KC_A)` Down 429 - (wait until tapping term expires...) 430 431 With default settings, `a` will be sent on the first release, then `a` will be sent on the second press, allowing the computer to trigger its auto repeat function until the key is released. 432 433 With `QUICK_TAP_TERM` configured, the timing between `SFT_T(KC_A)` up and `SFT_T(KC_A)` down must be within `QUICK_TAP_TERM` to trigger auto-repeat. Otherwise, the second press will be sent as a Shift. If `QUICK_TAP_TERM` is set to `0`, the second press will always be sent as a Shift, effectively disabling auto-repeat. 434 435 ::: warning 436 `QUICK_TAP_TERM` timing will also impact anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tap Toggle). 437 ::: 438 439 For more granular control of this feature, you can add the following to your `config.h`: 440 441 ```c 442 #define QUICK_TAP_TERM_PER_KEY 443 ``` 444 445 You can then add the following function to your keymap: 446 447 ```c 448 uint16_t get_quick_tap_term(uint16_t keycode, keyrecord_t *record) { 449 switch (keycode) { 450 case SFT_T(KC_SPC): 451 return QUICK_TAP_TERM - 20; 452 default: 453 return QUICK_TAP_TERM; 454 } 455 } 456 ``` 457 458 ::: tip 459 If `QUICK_TAP_TERM` is set higher than `TAPPING_TERM`, it will default to `TAPPING_TERM`. 460 ::: 461 462 ## Flow Tap 463 464 Flow Tap modifies mod-tap `MT` and layer-tap `LT` keys such that when pressed within a short timeout of the preceding key, the tapping behavior is triggered. This is particularly useful for home row mods to avoid accidental mod triggers. It basically disables the hold behavior during fast typing, creating a "flow of taps." This also helps to reduce the input lag of tap-hold keys during fast typing, since the tapped behavior is sent immediately. 465 466 Flow Tap is enabled by defining `FLOW_TAP_TERM` in your `config.h` with the desired timeout in milliseconds. A timeout of 150 ms is recommended as a starting point: 467 468 ```c 469 #define FLOW_TAP_TERM 150 470 ``` 471 472 By default, Flow Tap is enabled when: 473 474 * The tap-hold key is pressed within `FLOW_TAP_TERM` milliseconds of the previous key press. 475 476 * The tapping keycodes of the previous key and tap-hold key are *both* among `KC_A`–`KC_Z`, `KC_COMM`, `KC_DOT`, `KC_SCLN`, `KC_SLSH` (the main alphas area of a conventional QWERTY layout) or `KC_SPC`. 477 478 As an exception to the above, Flow Tap is temporarily disabled while a tap-hold key is undecided. This is to allow chording multiple mod-tap keys without having to wait out the Flow Tap term. 479 480 481 ### is_flow_tap_key() 482 483 Optionally, define the `is_flow_tap_key()` callback to specify where Flow Tap is enabled. The callback is called for both the tap-hold key *and* the key press immediately preceding it, and if the callback returns true for both keycodes, Flow Tap is enabled. 484 485 The default implementation of this callback is: 486 487 ```c 488 bool is_flow_tap_key(uint16_t keycode) { 489 if ((get_mods() & (MOD_MASK_CG | MOD_BIT_LALT)) != 0) { 490 return false; // Disable Flow Tap on hotkeys. 491 } 492 switch (get_tap_keycode(keycode)) { 493 case KC_SPC: 494 case KC_A ... KC_Z: 495 case KC_DOT: 496 case KC_COMM: 497 case KC_SCLN: 498 case KC_SLSH: 499 return true; 500 } 501 return false; 502 } 503 ``` 504 505 Copy the above to your `keymap.c` and edit to customize. For instance, remove the `case KC_SPC` line to disable Flow Tap for the Space key. 506 507 ### get_flow_tap_term() 508 509 Optionally, for further flexibility, define the `get_flow_tap_term()` callback. Flow Tap acts only when key events are closer together than the time returned by the callback. Return a time of 0 to disable filtering. In this way, Flow Tap may be disabled for certain tap-hold keys, or when following certain previous keys. 510 511 The default implementation of this callback is 512 513 ```c 514 uint16_t get_flow_tap_term(uint16_t keycode, keyrecord_t* record, 515 uint16_t prev_keycode) { 516 if (is_flow_tap_key(keycode) && is_flow_tap_key(prev_keycode)) { 517 return FLOW_TAP_TERM; 518 } 519 return 0; 520 } 521 ``` 522 523 In this callback, `keycode` and `record` correspond to the current tap-hold key, and `prev_keycode` is the keycode of the previous key. Return the timeout to use. Returning `0` disables Flow Tap. This callback enables setting per-key timeouts. It is also possible to enable or disable Flow Tap for certain tap-hold keys or when following certain previous keys. Example: 524 525 ```c 526 uint16_t get_flow_tap_term(uint16_t keycode, keyrecord_t* record, 527 uint16_t prev_keycode) { 528 if (is_flow_tap_key(keycode) && is_flow_tap_key(prev_keycode)) { 529 switch (keycode) { 530 case LCTL_T(KC_F): 531 case RCTL_T(KC_H): 532 return FLOW_TAP_TERM - 25; // Short timeout on these keys. 533 534 default: 535 return FLOW_TAP_TERM; // Longer timeout otherwise. 536 } 537 } 538 return 0; // Disable Flow Tap. 539 } 540 ``` 541 542 ::: tip If you define both `is_flow_tap_key()` and `get_flow_tap_term()`, then the latter takes precedence. 543 ::: 544 545 ## Chordal Hold 546 547 Chordal Hold is intended to be used together with either Permissive Hold or Hold 548 On Other Key Press. Chordal Hold is enabled by adding to your `config.h`: 549 550 ```c 551 #define CHORDAL_HOLD 552 ``` 553 554 Chordal Hold implements, by default, an "opposite hands" rule. Suppose a 555 tap-hold key is pressed and then, before the tapping term, another key is 556 pressed. With Chordal Hold, the tap-hold key is settled as tapped if the two 557 keys are on the same hand. 558 559 Otherwise, if the keys are on opposite hands, Chordal Hold introduces no new 560 behavior. Hold On Other Key Press or Permissive Hold may be used together with 561 Chordal Hold to configure the behavior in the opposite hands case. With Hold On 562 Other Key Press, an opposite hands chord is settled immediately as held. Or with 563 Permissive Hold, an opposite hands chord is settled as held provided the other 564 key is pressed and released (nested press) before releasing the tap-hold key. 565 566 Chordal Hold may be useful to avoid accidental modifier activation with 567 mod-taps, particularly in rolled keypresses when using home row mods. 568 569 Notes: 570 571 * Chordal Hold has no effect after the tapping term. 572 573 * Combos are exempt from the opposite hands rule, since "handedness" is 574 ill-defined in this case. Even so, Chordal Hold's behavior involving combos 575 may be customized through the `get_chordal_hold()` callback. 576 577 An example of a sequence that is affected by “chordal hold”: 578 579 - `SFT_T(KC_A)` Down 580 - `KC_C` Down 581 - `KC_C` Up 582 - `SFT_T(KC_A)` Up 583 584 ``` 585 TAPPING_TERM 586 +---------------------------|--------+ 587 | +----------------------+ | | 588 | | SFT_T(KC_A) | | | 589 | +----------------------+ | | 590 | +--------------+ | | 591 | | KC_C | | | 592 | +--------------+ | | 593 +---------------------------|--------+ 594 ``` 595 596 If the two keys are on the same hand, then this will produce `ac` with 597 `SFT_T(KC_A)` settled as tapped the moment that `KC_C` is pressed. 598 599 If the two keys are on opposite hands and the `HOLD_ON_OTHER_KEY_PRESS` option 600 enabled, this will produce `C` with `SFT_T(KC_A)` settled as held when `KC_C` is 601 pressed. 602 603 Or if the two keys are on opposite hands and the `PERMISSIVE_HOLD` option is 604 enabled, this will produce `C` with `SFT_T(KC_A)` settled as held when that 605 `KC_C` is released. 606 607 As an exception to the opposite hands rule, Chordal Hold supports combining 608 multiple same-side modifiers within the tapping term. This is useful for 609 multi-mod hotkeys like Ctrl + Shift + V. For instance with Chordal Hold together 610 with either Permissive Hold or Hold On Other Key Press, the following input 611 results in Ctrl + Shift + V being sent, supposing `J` and `K` are on the right 612 hand side and `V` is on the left hand side: 613 614 - `SFT_T(KC_J)` Down 615 - `CTL_T(KC_K)` Down 616 - `KC_V` Down 617 - `KC_V` Up 618 - `SFT_T(KC_J)` Up 619 - `CTL_T(KC_K)` Up 620 621 ### Chordal Hold Handedness 622 623 Determining whether keys are on the same or opposite hands involves defining the 624 "handedness" of each key position. By default, if nothing is specified, 625 handedness is guessed based on keyboard geometry. 626 627 Handedness may be specified with `chordal_hold_layout`. In keymap.c, define 628 `chordal_hold_layout` in the following form: 629 630 ```c 631 const char chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS] PROGMEM = 632 LAYOUT( 633 'L', 'L', 'L', 'L', 'L', 'L', 'R', 'R', 'R', 'R', 'R', 'R', 634 'L', 'L', 'L', 'L', 'L', 'L', 'R', 'R', 'R', 'R', 'R', 'R', 635 'L', 'L', 'L', 'L', 'L', 'L', 'R', 'R', 'R', 'R', 'R', 'R', 636 'L', 'L', 'L', 'R', 'R', 'R' 637 ); 638 ``` 639 640 Use the same `LAYOUT` macro as used to define your keymap layers. Each entry is 641 a character indicating the handedness of one key, either `'L'` for left, `'R'` 642 for right, or `'*'` to exempt keys from the "opposite hands rule." A key with 643 `'*'` handedness may settle as held in chords with any other key. This could be 644 used perhaps on thumb keys or other places where you want to allow same-hand 645 chords. 646 647 Keyboard makers may specify handedness in keyboard.json. Under `"layouts"`, 648 specify the handedness of a key by adding a `"hand"` field with a value of 649 either `"L"`, `"R"`, or `"*"`. Note that if `"layouts"` contains multiple 650 layouts, only the first one is read. For example: 651 652 ```json 653 {"matrix": [5, 6], "x": 0, "y": 5.5, "w": 1.25, "hand": "*"}, 654 ``` 655 656 Alternatively, handedness may be defined functionally with 657 `chordal_hold_handedness()`. For example, in keymap.c define: 658 659 ```c 660 char chordal_hold_handedness(keypos_t key) { 661 if (key.col == 0 || key.col == MATRIX_COLS - 1) { 662 return '*'; // Exempt the outer columns. 663 } 664 // On split keyboards, typically, the first half of the rows are on the 665 // left, and the other half are on the right. 666 return key.row < MATRIX_ROWS / 2 ? 'L' : 'R'; 667 } 668 ``` 669 670 Given the matrix position of a key, the function should return `'L'`, `'R'`, or 671 `'*'`. Adapt the logic in this function according to the keyboard's matrix. 672 673 ::: warning 674 Note the matrix may have irregularities around larger keys, around the edges of 675 the board, and around thumb clusters. You may find it helpful to use [this 676 debugging example](faq_debug#which-matrix-position-is-this-keypress) to 677 correspond physical keys to matrix positions. 678 ::: 679 680 ::: tip If you define both `chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS]` and 681 `chordal_hold_handedness(keypos_t key)` for handedness, the latter takes 682 precedence. 683 ::: 684 685 686 ### Per-chord customization 687 688 Beyond the per-key configuration possible through handedness, Chordal Hold may 689 be configured at a *per-chord* granularity for detailed tuning. In keymap.c, 690 define `get_chordal_hold()`. Returning `true` allows the chord to be held, while 691 returning `false` settles as tapped. 692 693 For example: 694 695 ```c 696 bool get_chordal_hold(uint16_t tap_hold_keycode, keyrecord_t* tap_hold_record, 697 uint16_t other_keycode, keyrecord_t* other_record) { 698 // Exceptionally allow some one-handed chords for hotkeys. 699 switch (tap_hold_keycode) { 700 case LCTL_T(KC_Z): 701 if (other_keycode == KC_C || other_keycode == KC_V) { 702 return true; 703 } 704 break; 705 706 case RCTL_T(KC_SLSH): 707 if (other_keycode == KC_N) { 708 return true; 709 } 710 break; 711 } 712 // Otherwise defer to the opposite hands rule. 713 return get_chordal_hold_default(tap_hold_record, other_record); 714 } 715 ``` 716 717 As shown in the last line above, you may use 718 `get_chordal_hold_default(tap_hold_record, other_record)` to get the default tap 719 vs. hold decision according to the opposite hands rule. 720 721 722 ## Retro Tapping 723 724 To enable `retro tapping`, add the following to your `config.h`: 725 726 ```c 727 #define RETRO_TAPPING 728 ``` 729 730 Holding and releasing a dual-function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term. 731 732 For instance, holding and releasing `LT(2, KC_SPC)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPC` instead. 733 734 ``` 735 TAPPING_TERM 736 +-----------------|------------------+ 737 | +---------------|-------+ | 738 | | LT(2, KC_SPC) | | | 739 | +---------------|-------+ | 740 | | | 741 | | | 742 | | | 743 +-----------------|------------------+ 744 ``` 745 746 For more granular control of this feature, you can add the following to your `config.h`: 747 748 ```c 749 #define RETRO_TAPPING_PER_KEY 750 ``` 751 752 You can then add the following function to your keymap: 753 754 ```c 755 bool get_retro_tapping(uint16_t keycode, keyrecord_t *record) { 756 switch (keycode) { 757 case LT(2, KC_SPC): 758 return true; 759 default: 760 return false; 761 } 762 } 763 ``` 764 765 If the programs you use bind an action to taps of modifier keys (e.g. tapping left GUI to bring up the applications menu or tapping left Alt to focus the menu bar), you may find that using retro-tapping falsely triggers those actions. To counteract this, you can define a `DUMMY_MOD_NEUTRALIZER_KEYCODE` in `config.h` that will get sent in between the register and unregister events of a held Mod-Tap key. That way, the programs on your computer will no longer interpret the mod suppression induced by retro-tapping as a lone tap of a modifier key and will thus not falsely trigger the undesired action. 766 767 Naturally, for this technique to be effective, you must choose a `DUMMY_MOD_NEUTRALIZER_KEYCODE` for which no keyboard shortcuts are bound to. Recommended values are: `KC_RIGHT_CTRL` or `KC_F18`. 768 Please note that `DUMMY_MOD_NEUTRALIZER_KEYCODE` must be a basic, unmodified, HID keycode, so values like `KC_NO`, `KC_TRANSPARENT`, or `KC_PIPE` (aka `S(KC_BACKSLASH)`) are not permitted. 769 770 By default, only left Alt and left GUI are neutralized. If you want to change the list of applicable modifier masks, use the following in your `config.h`: 771 772 ```c 773 #define MODS_TO_NEUTRALIZE { <mod_mask_1>, <mod_mask_2>, ... } 774 ``` 775 776 Examples: 777 778 ```c 779 #define DUMMY_MOD_NEUTRALIZER_KEYCODE KC_RIGHT_CTRL 780 781 // Neutralize left alt and left GUI (Default value) 782 #define MODS_TO_NEUTRALIZE { MOD_BIT(KC_LEFT_ALT), MOD_BIT(KC_LEFT_GUI) } 783 784 // Neutralize left alt, left GUI, right GUI and left Control+Shift 785 #define MODS_TO_NEUTRALIZE { MOD_BIT(KC_LEFT_ALT), MOD_BIT(KC_LEFT_GUI), MOD_BIT(KC_RIGHT_GUI), MOD_BIT(KC_LEFT_CTRL)|MOD_BIT(KC_LEFT_SHIFT) } 786 ``` 787 788 ::: warning 789 Do not use `MOD_xxx` constants like `MOD_LSFT` or `MOD_RALT`, since they're 5-bit packed bit-arrays while `MODS_TO_NEUTRALIZE` expects a list of 8-bit packed bit-arrays. Use `MOD_BIT(<kc>)` or `MOD_MASK_xxx` instead. 790 ::: 791 792 ### Retro Shift 793 794 [Auto Shift](features/auto_shift) has its own version of `retro tapping` called `retro shift`. It is extremely similar to `retro tapping`, but holding the key past `AUTO_SHIFT_TIMEOUT` results in the value it sends being shifted. Other configurations also affect it differently; see [here](features/auto_shift#retro-shift) for more information. 795 796 ## Speculative Hold 797 798 Speculative Hold makes mod-tap keys more responsive by applying the modifier instantly on keydown, before the tap-hold decision is made. This is especially useful for actions like Shift+Click with a mouse, which can feel laggy with standard mod-taps. 799 800 The firmware holds the modifier speculatively. Once the key's behavior is settled: 801 802 * If held, the modifier remains active as expected until the key is released. 803 * If tapped, the speculative modifier is canceled just before the tapping keycode is sent. 804 805 Speculative Hold applies the modifier early but does not change the underlying tap-hold decision logic. Speculative Hold is compatible to use in combination with any other tap-hold options. 806 807 To enable Speculative Hold, add the following to your `config.h`: 808 809 ```c 810 #define SPECULATIVE_HOLD 811 ``` 812 813 By default, Speculative Hold applies to mod-taps using Shift, Ctrl, or Shift + Ctrl. You can override this behavior by defining the `get_speculative_hold()` callback in your keymap, for instance: 814 815 ```c 816 bool get_speculative_hold(uint16_t keycode, keyrecord_t* record) { 817 switch (keycode) { // These keys may be speculatively held. 818 case LCTL_T(KC_ESC): 819 case LSFT_T(KC_Z): 820 case RSFT_T(KC_SLSH): 821 return true; 822 } 823 return false; // Disable otherwise. 824 } 825 ``` 826 827 Some operating systems or applications assign actions to tapping a modifier key by itself, e.g., tapping GUI to open a start menu. Because Speculative Hold sends a lone modifier key press in some cases, it can falsely trigger these actions. To prevent this, set `DUMMY_MOD_NEUTRALIZER_KEYCODE` (and optionally `MODS_TO_NEUTRALIZE`) in your `config.h` in the same way as described above for [Retro Tapping](#retro-tapping). 828 829 ## Why do we include the key record for the per key functions? 830 831 One thing that you may notice is that we include the key record for all of the "per key" functions, and may be wondering why we do that. 832 833 Well, it's simple really: customization. But specifically, it depends on how your keyboard is wired up. For instance, if each row is actually using a row in the keyboard's matrix, then it may be simpler to use `if (record->event.key.row == 3)` instead of checking a whole bunch of keycodes, which is especially good for those people using the tap-hold keys on the home row (see about *home row mods* [here](https://precondition.github.io/home-row-mods)). So, you could fine-tune those to not interfere with your normal typing. 834 835 ## Why are there no `*_kb` or `*_user` functions?! 836 837 Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum- or keyboard-level function. Only user-level functions are useful here, so there is no need to mark them as such.