Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Docs] Include ASCII diagram to explain tap-hold modes #15873

Merged
merged 3 commits into from
Mar 10, 2022
Merged

[Docs] Include ASCII diagram to explain tap-hold modes #15873

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
df77b2b
[Docs] Include ASCII diagram to explain tap-hold modes
wongjiahau Jan 14, 2022
1a1f34a
[Docs]: add examples for Default mode for Tap Hold
wongjiahau Jan 14, 2022
a0c8b07
[Docs] fix some wrong explanation in tap_hold.md
wongjiahau Jan 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions docs/tap_hold.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,61 @@ 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.

### Default Mode
Example sequence 1 (the `L` key is also mapped to `KC_RGHT` on layer 2):

```
TAPPING_TERM
+---------------|--------------------+
| +-------------|-------+ |
| | LT(2, KC_A) | | |
| +-------------|-------+ |
| | +--------------+ |
| | | KC_L | |
| | +--------------+ |
+---------------|--------------------+
```
The above sequence would send a `KC_RGHT`, since `LT(2, KC_A)` is held longer than the `TAPPING_TERM`.

---

Example sequence 2 (the `L` key is also mapped to `KC_RGHT` on layer 2):

```
TAPPING_TERM
+-----------------------------|------+
| +---------------+ | |
| | LT(2, KC_A) | | |
| +---------------+ | |
| +--------------+ | |
| | KC_L | | |
| +--------------+ | |
+-----------------------------|------+
```
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`.

---

Example sequence 3 (Mod Tap):

```
TAPPING_TERM
+---------------------------|--------+
| +-------------+ | |
| | SFT_T(KC_A) | | |
| +-------------+ | |
| +--------------+ | |
| | KC_X | | |
| +--------------+ | |
+---------------------------|--------+
```
Based previous examples, you might have expected the output of the above sequence to be `KC_A` `KC_X`
since `SFT_T(KC_A)` is NOT held longer than the `TAPPING_TERM`.
However, the actual output would be capital `X` (`SHIFT` + `x`) due to reasons
explained under [Ignore Mod Tap Interrupt](#ignore-mod-tap-interrupt).



### Permissive Hold

The “permissive hold” mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`:
Expand All @@ -145,6 +200,18 @@ An example of a sequence which is affected by the “permissive hold” mode:
- `KC_L` Up
- `LT(2, KC_A)` Up

```
TAPPING_TERM
+---------------------------|--------+
| +----------------------+ | |
| | LT(2, KC_A) | | |
| +----------------------+ | |
| +--------------+ | |
| | KC_L | | |
| +--------------+ | |
+---------------------------|--------+
```

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 press” (the modified key's key down and key up events are “nested” between the dual-role key's key down and key up events).

However, this slightly different sequence will not be affected by the “permissive hold” mode:
Expand All @@ -154,6 +221,18 @@ However, this slightly different sequence will not be affected by the “permiss
- `LT(2, KC_A)` Up
- `KC_L` Up

```
TAPPING_TERM
+---------------------------|--------+
| +-------------+ | |
| | LT(2, KC_A) | | |
| +-------------+ | |
| +--------------+ | |
| | KC_L | | |
| +--------------+ | |
+---------------------------|--------+
```

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 also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers both the “nested press” and “rolling press” sequences like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `PERMISSIVE_HOLD` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
Expand Down Expand Up @@ -198,6 +277,18 @@ An example of a sequence which is affected by the “hold on other key press”
- `LT(2, KC_A)` Up
- `KC_L` Up

```
TAPPING_TERM
+---------------------------|--------+
| +-------------+ | |
| | LT(2, KC_A) | | |
| +-------------+ | |
| +--------------+ | |
| | KC_L | | |
| +--------------+ | |
+---------------------------|--------+
```

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).

?> The `HOLD_ON_OTHER_KEY_PRESS` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers the “rolling press” sequence like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `HOLD_ON_OTHER_KEY_PRESS` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host.
Expand Down Expand Up @@ -245,6 +336,18 @@ An example of a sequence which will be affected by the `IGNORE_MOD_TAP_INTERRUPT
- `SFT_T(KC_A)` Up
- `KC_X` Up

```
TAPPING_TERM
+---------------------------|--------+
| +-------------+ | |
| | SFT_T(KC_A) | | |
| +-------------+ | |
| +--------------+ | |
| | KC_X | | |
| +--------------+ | |
+---------------------------|--------+
```

Normally, this would send a capital `X` (`SHIFT`+`x`), even if the sequence is performed faster than the `TAPPING_TERM`. However, if the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, the `SFT_T(KC_A)` key must be held longer than the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold will still output a capital `X` (`SHIFT`+`x`).

However, if the `HOLD_ON_OTHER_KEY_PRESS` option is enabled in addition to `IGNORE_MOD_TAP_INTERRUPT`, the above sequence will again send a capital `X` (`SHIFT`+`x`) even if performed faster that the `TAPPING_TERM`. The difference from the default configuration is that by default the host will receive the key events only after the `SFT_T(KC_A)` key is released, but with the `HOLD_ON_OTHER_KEY_PRESS` option the host will start receiving key events when the `KC_X` key is pressed.
Expand Down Expand Up @@ -327,6 +430,18 @@ Holding and releasing a dual function key without pressing another key will resu

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.

```
TAPPING_TERM
+-----------------|------------------+
| +---------------|-------+ |
| | LT(2, KC_SPC) | | |
| +---------------|-------+ |
| | |
| | |
| | |
+-----------------|------------------+
```

For more granular control of this feature, you can add the following to your `config.h`:

```c
Expand Down