From d34fdde1fda8d6dbc7547d727fe3233fd6640a07 Mon Sep 17 00:00:00 2001 From: jmding8 <44815547+jmding8@users.noreply.github.com> Date: Tue, 22 Dec 2020 14:28:44 -0800 Subject: [PATCH] docs(behaviors): add usage notes for hold-taps chore(tests): remove useless &cp test --- app/tests/keypress/behavior_keymap.dtsi | 3 ++- app/tests/keypress/cp-press-release/events.patterns | 1 - .../cp-press-release/keycode_events.snapshot | 2 -- .../keypress/cp-press-release/native_posix.keymap | 5 ----- .../keypress/kp-press-release/native_posix.keymap | 5 ++++- docs/docs/behaviors/hold-tap.md | 12 +++++++++--- 6 files changed, 15 insertions(+), 13 deletions(-) delete mode 100644 app/tests/keypress/cp-press-release/events.patterns delete mode 100644 app/tests/keypress/cp-press-release/keycode_events.snapshot delete mode 100644 app/tests/keypress/cp-press-release/native_posix.keymap diff --git a/app/tests/keypress/behavior_keymap.dtsi b/app/tests/keypress/behavior_keymap.dtsi index 216e760a..64851a84 100644 --- a/app/tests/keypress/behavior_keymap.dtsi +++ b/app/tests/keypress/behavior_keymap.dtsi @@ -10,7 +10,8 @@ default_layer { bindings = < &kp B &none - &kp C_NEXT &none>; + &none &none + >; }; }; }; diff --git a/app/tests/keypress/cp-press-release/events.patterns b/app/tests/keypress/cp-press-release/events.patterns deleted file mode 100644 index 833100f6..00000000 --- a/app/tests/keypress/cp-press-release/events.patterns +++ /dev/null @@ -1 +0,0 @@ -s/.*hid_listener_keycode_//p \ No newline at end of file diff --git a/app/tests/keypress/cp-press-release/keycode_events.snapshot b/app/tests/keypress/cp-press-release/keycode_events.snapshot deleted file mode 100644 index 95d24a49..00000000 --- a/app/tests/keypress/cp-press-release/keycode_events.snapshot +++ /dev/null @@ -1,2 +0,0 @@ -pressed: usage_page 0x0c keycode 0xb5 mods 0x00 -pressed: usage_page 0x0c keycode 0xb5 mods 0x00 diff --git a/app/tests/keypress/cp-press-release/native_posix.keymap b/app/tests/keypress/cp-press-release/native_posix.keymap deleted file mode 100644 index bf93af7d..00000000 --- a/app/tests/keypress/cp-press-release/native_posix.keymap +++ /dev/null @@ -1,5 +0,0 @@ -#include "../behavior_keymap.dtsi" - -&kscan { - events = ; -}; \ No newline at end of file diff --git a/app/tests/keypress/kp-press-release/native_posix.keymap b/app/tests/keypress/kp-press-release/native_posix.keymap index 279b084d..0ddb7ab6 100644 --- a/app/tests/keypress/kp-press-release/native_posix.keymap +++ b/app/tests/keypress/kp-press-release/native_posix.keymap @@ -1,5 +1,8 @@ #include "../behavior_keymap.dtsi" &kscan { - events = ; + events = < + ZMK_MOCK_PRESS(0,0,10) + ZMK_MOCK_RELEASE(0,0,10) + >; }; \ No newline at end of file diff --git a/docs/docs/behaviors/hold-tap.md b/docs/docs/behaviors/hold-tap.md index f3c3c664..758e1996 100644 --- a/docs/docs/behaviors/hold-tap.md +++ b/docs/docs/behaviors/hold-tap.md @@ -15,11 +15,11 @@ The `tapping_term_ms` parameter decides between a 'tap' and a 'hold'. ![Simple behavior](../assets/hold-tap/case1_2.png) -By default, the hold-tap is configured to also select the 'hold' functionality if another key is tapped while it's active: +By default, the hold-tap and mod-tap (but NOT layer-tap) are configured to also select the 'hold' functionality if another key is tapped while it's active: ![Hold preferred behavior](../assets/hold-tap/case1_2.png) -We call this the 'hold-preferred' flavor of hold-taps. While this flavor may work very well for a ctrl/escape key, it's not very well suited for home-row mods or layer-taps. That's why there are two more flavors to choose from: 'tap-preferred' and 'balanced'. +We call this the 'hold-preferred' flavor of hold-taps. While this flavor may work very well for a control/escape key, it's not very well suited for home-row mods. That's why there are two more flavors to choose from: 'tap-preferred' and 'balanced'. #### Flavors @@ -31,6 +31,12 @@ When the hold-tap key is released and the hold behavior has not been triggered, ![Hold-tap comparison](../assets/hold-tap/comparison.png) +The 'hold-preferred' flavor tends to work well in combination with the shift, control, caps lock, escape, tab and similar keys because they do not typically occur in the middle words or other rapid typing sequences in which the user may (unknowingly) execute a rolling keystroke, where they press the next key before the fully releasing the prior (hold/mod/layer-tap) key. Futhermore, because the decision to emit the hold behavior is made upon the second key being pressed, the 'hold-preferred' flavor most closely mimics the behavior of the shift key on a normal keyboard, and therefore tends to feel quite natural to users. However, because it biases towards the hold behavior in rolling keystroke situations, this flavor tends not to work well in combination with the letter keys or the spacebar, except for the small percentage of users that have very strict key-up habits. + +The 'tap-preferred' and 'balanced' flavors tend to work better in combination with the letter keys or spacebar because they will emit the tap behavior if the key is involved in a rolling keystroke, as long as it happens quickly. This can work well with home-row modifiers. + +Because 'tap-preferred' and 'balanced' tend to be quite timing sensitive, they often require `tapping_term_ms` configured on a per-user basis to work consistently. Therefore for developers designing keymaps for many users who may have differing typing speeds and habits, it often makes sense to prioritize using the 'hold-preferred' flavor in combination with non-letter, non-spacebar keys first, since it tends to behave more intuitively for more people, without requiring as much retraining. + ### Basic usage For basic usage, please see [mod-tap](./mod-tap.md) and [layer-tap](./layers.md) pages. @@ -72,4 +78,4 @@ If this config does not work for you, try the flavor "balanced" with a medium ta #### Comparison to QMK -The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting in QMK. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`. +The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting in QMK. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the 'tap-preferred' flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`.