aboutsummaryrefslogtreecommitdiff
path: root/docs/tap_hold.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/tap_hold.md')
-rw-r--r--docs/tap_hold.md32
1 files changed, 21 insertions, 11 deletions
diff --git a/docs/tap_hold.md b/docs/tap_hold.md
index 18c90c6932..fe862894b4 100644
--- a/docs/tap_hold.md
+++ b/docs/tap_hold.md
@@ -8,7 +8,9 @@ These options let you modify the behavior of the Tap-Hold keys.
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.
-?> `DYNAMIC_TAPPING_TERM_ENABLE` enables three special keys that can help you quickly find a comfortable tapping term for you. See "Dynamic Tapping Term" for more details.
+::: tip
+`DYNAMIC_TAPPING_TERM_ENABLE` enables three special keys that can help you quickly find a comfortable tapping term for you. See "Dynamic Tapping Term" for more details.
+:::
You can set the global time for this by adding the following setting to your `config.h`:
@@ -38,7 +40,7 @@ uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
}
```
-### Dynamic Tapping Term :id=dynamic-tapping-term
+### Dynamic Tapping Term {#dynamic-tapping-term}
`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.
@@ -126,13 +128,13 @@ The code which decides between the tap and hold actions of dual-role keys suppor
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.
-### Comparison :id=comparison
+### Comparison {#comparison}
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.
Note: "`kc` held" in the "Physical key event" column means that the key wasn't physically released yet at this point in time.
-#### Distinct taps (AABB) :id=distinct-taps
+#### Distinct taps (AABB) {#distinct-taps}
| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` |
|------|--------------------|----------------|-------------------|----------------------------|
@@ -149,7 +151,7 @@ Note: "`kc` held" in the "Physical key event" column means that the key wasn't p
| 205 | `KC_B` down | b | b | b |
| 210 | `KC_B` up | b | b | b |
-#### Nested tap (ABBA) :id=nested-tap
+#### Nested tap (ABBA) {#nested-tap}
| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` |
|------|--------------------|----------------|-------------------|----------------------------|
@@ -174,7 +176,7 @@ Note: "`kc` held" in the "Physical key event" column means that the key wasn't p
| 210 | `KC_B` up | B | B | B |
| 220 | `LSFT_T(KC_A)` up | B | B | B |
-#### Rolling keys (ABAB) :id=rolling-keys
+#### Rolling keys (ABAB) {#rolling-keys}
| Time | Physical key event | Default | `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` |
|------|--------------------|----------------|-------------------|----------------------------|
@@ -296,7 +298,9 @@ However, this slightly different sequence will not be affected by the “permiss
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).
-?> 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`.
+::: tip
+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`.
+:::
For more granular control of this feature, you can add the following to your `config.h`:
@@ -394,7 +398,9 @@ With default settings, `a` will be sent on the first release, then `a` will be s
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.
-!> `QUICK_TAP_TERM` timing will also impact anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tap Toggle).
+::: warning
+`QUICK_TAP_TERM` timing will also impact anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tap Toggle).
+:::
For more granular control of this feature, you can add the following to your `config.h`:
@@ -415,7 +421,9 @@ uint16_t get_quick_tap_term(uint16_t keycode, keyrecord_t *record) {
}
```
-?> If `QUICK_TAP_TERM` is set higher than `TAPPING_TERM`, it will default to `TAPPING_TERM`.
+::: tip
+If `QUICK_TAP_TERM` is set higher than `TAPPING_TERM`, it will default to `TAPPING_TERM`.
+:::
## Retro Tapping
@@ -483,11 +491,13 @@ Examples:
#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) }
```
-!> 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.
+::: warning
+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.
+:::
### Retro Shift
-[Auto Shift,](feature_auto_shift.md) 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](feature_auto_shift.md#retro-shift) for more information.
+[Auto Shift,](feature_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](feature_auto_shift#retro-shift) for more information.
## Why do we include the key record for the per key functions?