kb01/zmk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs comments

Browse source
This commit is contained in:
jmding8 2021-10-29 02:31:32 +00:00
parent f5426939ef
commit f35d4a44fe
1 changed files with 17 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
docs/docs/behaviors/hold-tap.md
View file

@ -95,9 +95,17 @@ This example configures a hold-tap that works well for homerow mods:
If this config does not work for you, try the flavor "balanced" with a medium `tapping-term-ms` such as 200ms. If this config does not work for you, try the flavor "balanced" with a medium `tapping-term-ms` such as 200ms.
#### Positional hold-tap and `hold-enabler-keys` #### Positional hold-tap and `hold-trigger-key-positions`
Including `hold-enabler-keys` in your hold-tap behavior definition enables the positional hold-tap feature. With positional hold-tap enabled, your hold-tap behavior will only produce a hold behavior if while the hold-tap key is still pressed, the first other key to be pressed is one of the `hold-enabler-keys`. For example, with the following hold-tap behavior definiton: * Including `hold-trigger-key-postions` in your hold-tap behavior definition enables the positional hold-tap feature.
* With positional hold-tap enabled, your hold-tap behavior will only produce a hold behavior if, while the hold-tap key is still held down, the next key to be pressed is at one of the positions listed in the `hold-trigger-key-postions` array.
* `hold-trigger-key-postions` is an array of key positions. See the info section below about how to figure out the positions of keys on your board.
:::info
Key positions are numbered according to the keys in your keymap, starting at 0. So, if the first key in your keymap is Q, this key is in position 0. The next key (possibly W) will have position 1, etcetera.
:::
* See the following example, which references the below hold-tap behavior definiton:
``` ```
#include <dt-bindings/zmk/keys.h> #include <dt-bindings/zmk/keys.h>
@ -113,7 +121,7 @@ Including `hold-enabler-keys` in your hold-tap behavior definition enables the p
tapping-term-ms = <400>; tapping-term-ms = <400>;
quick-tap-ms = <200>; quick-tap-ms = <200>;
bindings = <&kp>, <&kp>; bindings = <&kp>, <&kp>;
hold-enabler-keys = <1>; // <---[[the W key]] hold-trigger-key-positions = <1>; // <---[[the W key]]
}; };
}; };
@ -122,20 +130,21 @@ Including `hold-enabler-keys` in your hold-tap behavior definition enables the p
label ="Default keymap"; label ="Default keymap";
default_layer { default_layer {
bindings = < bindings = <
&cht LEFT_SHIFT Q &kp W &kp E // position 0 position 1 position 2
&pht LEFT_SHIFT Q &kp W &kp E
>; >;
}; };
}; };
}; };
``` ```
The sequence `(cht_down, W_down, W_up, E_down, E_up, cht_up)` produces `WE`. The positional hold-tap **IS** permitted to produce a hold behavior, because the first key pressed after the hold-tap key (i.e. the W key, in position 1) **IS** one of the `hold-enabler-keys`. * The sequence `(pht_down, W_down, W_up, E_down, E_up, pht_up)` produces `WE`. The positional hold-tap **IS** permitted to produce a hold behavior, because the first key pressed after the hold-tap key (i.e. the W key, in position 1) **IS** one of the `hold-trigger-key-positions`.
Meanwhile, the sequence `(cht_down, E_down, E_up, W_down, W_up cht_up)` produces `qew`. The positional hold-tap is **NOT** permitted to produce a hold behavior, because the first key pressed after the hold-tap key (i.e. the E key, in position 2) is **NOT** one of the `hold-enabler-keys`. * Meanwhile, the sequence `(pht_down, E_down, E_up, W_down, W_up pht_up)` produces `qew`. The positional hold-tap is **NOT** permitted to produce a hold behavior, because the first key pressed after the hold-tap key (i.e. the E key, in position 2) is **NOT** one of the `hold-trigger-key-positions`.
Positional hold-taps can be useful with home-row modifiers. By using a positional hold-tap behavior for home-row modifiers on the left hand, and setting `hold-enabler-keys` to the keys under the right hand, positional hold-tap will only allow hold behaviors to occur with cross-hand keypresses. * Positional hold-taps can be useful with home-row modifiers. By using a positional hold-tap behavior for home-row modifiers on the left hand, and setting `hold-trigger-key-positions` to the keys under the right hand, positional hold-tap will only allow hold behaviors to occur with cross-hand keypresses.
Note that for regular hold-tap behaviors a shorter `tapping-term` encourages hold decisions. However the opposite is true for positional hold-tap behaviors, where a shorter `tapping-term` actually encourages tap decisions. This is because when the `tapping-term` expires, this triggers the behavior to decide as either a tap or a hold. But if the user has not yet had time to press one of the `hold-enabler-keys`, then with positional hold-tap the behavior will decide as a tap. * Note that for regular hold-tap behaviors a shorter `tapping-term` encourages hold decisions. However the opposite is true for positional hold-tap behaviors, where a shorter `tapping-term` actually encourages tap decisions. This is because when the `tapping-term` expires, this triggers the behavior to decide as either a tap or a hold. But if the user has not yet had time to press one of the `hold-trigger-key-positions`, then with positional hold-tap the behavior will decide as a tap.
#### Comparison to QMK #### Comparison to QMK