diff options
16 files changed, 303 insertions, 31 deletions
diff --git a/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml b/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml index 575754116b..76f14d12d4 100644 --- a/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml +++ b/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml @@ -37,6 +37,10 @@ properties: - "balanced" - "tap-preferred" - "tap-unless-interrupted" + hold-while-undecided: + type: boolean + hold-while-undecided-linger: + type: boolean retro-tap: type: boolean hold-trigger-key-positions: diff --git a/app/src/behaviors/behavior_hold_tap.c b/app/src/behaviors/behavior_hold_tap.c index efc96c1a3f..01587caf5e 100644 --- a/app/src/behaviors/behavior_hold_tap.c +++ b/app/src/behaviors/behavior_hold_tap.c @@ -45,6 +45,7 @@ enum status { }; enum decision_moment { + HT_KEY_DOWN, HT_KEY_UP, HT_OTHER_KEY_DOWN, HT_OTHER_KEY_UP, @@ -59,6 +60,8 @@ struct behavior_hold_tap_config { int quick_tap_ms; int require_prior_idle_ms; enum flavor flavor; + bool hold_while_undecided; + bool hold_while_undecided_linger; bool retro_tap; bool hold_trigger_on_release; int32_t hold_trigger_key_positions_len; @@ -387,47 +390,87 @@ static inline const char *decision_moment_str(enum decision_moment decision_mome } } -static int press_binding(struct active_hold_tap *hold_tap) { - if (hold_tap->config->retro_tap && hold_tap->status == STATUS_HOLD_TIMER) { - return 0; - } +static int press_hold_binding(struct active_hold_tap *hold_tap) { + struct zmk_behavior_binding_event event = { + .position = hold_tap->position, + .timestamp = hold_tap->timestamp, + }; + struct zmk_behavior_binding binding = {0}; + binding.behavior_dev = hold_tap->config->hold_behavior_dev; + binding.param1 = hold_tap->param_hold; + return behavior_keymap_binding_pressed(&binding, event); +} + +static int press_tap_binding(struct active_hold_tap *hold_tap) { struct zmk_behavior_binding_event event = { .position = hold_tap->position, .timestamp = hold_tap->timestamp, }; struct zmk_behavior_binding binding = {0}; - if (hold_tap->status == STATUS_HOLD_TIMER || hold_tap->status == STATUS_HOLD_INTERRUPT) { - binding.behavior_dev = hold_tap->config->hold_behavior_dev; - binding.param1 = hold_tap->param_hold; - } else { - binding.behavior_dev = hold_tap->config->tap_behavior_dev; - binding.param1 = hold_tap->param_tap; - store_last_hold_tapped(hold_tap); - } + binding.behavior_dev = hold_tap->config->tap_behavior_dev; + binding.param1 = hold_tap->param_tap; + store_last_hold_tapped(hold_tap); return behavior_keymap_binding_pressed(&binding, event); } -static int release_binding(struct active_hold_tap *hold_tap) { - if (hold_tap->config->retro_tap && hold_tap->status == STATUS_HOLD_TIMER) { - return 0; - } +static int release_hold_binding(struct active_hold_tap *hold_tap) { + struct zmk_behavior_binding_event event = { + .position = hold_tap->position, + .timestamp = hold_tap->timestamp, + }; + struct zmk_behavior_binding binding = {0}; + binding.behavior_dev = hold_tap->config->hold_behavior_dev; + binding.param1 = hold_tap->param_hold; + return behavior_keymap_binding_released(&binding, event); +} + +static int release_tap_binding(struct active_hold_tap *hold_tap) { struct zmk_behavior_binding_event event = { .position = hold_tap->position, .timestamp = hold_tap->timestamp, }; struct zmk_behavior_binding binding = {0}; + binding.behavior_dev = hold_tap->config->tap_behavior_dev; + binding.param1 = hold_tap->param_tap; + return behavior_keymap_binding_released(&binding, event); +} + +static int press_binding(struct active_hold_tap *hold_tap) { + if (hold_tap->config->retro_tap && hold_tap->status == STATUS_HOLD_TIMER) { + return 0; + } + if (hold_tap->status == STATUS_HOLD_TIMER || hold_tap->status == STATUS_HOLD_INTERRUPT) { - binding.behavior_dev = hold_tap->config->hold_behavior_dev; - binding.param1 = hold_tap->param_hold; + if (hold_tap->config->hold_while_undecided) { + // the hold is already active, so we don't need to press it again + return 0; + } else { + return press_hold_binding(hold_tap); + } } else { - binding.behavior_dev = hold_tap->config->tap_behavior_dev; - binding.param1 = hold_tap->param_tap; + if (hold_tap->config->hold_while_undecided && + !hold_tap->config->hold_while_undecided_linger) { + // time to release the hold before pressing the tap + release_hold_binding(hold_tap); + } + return press_tap_binding(hold_tap); + } +} + +static int release_binding(struct active_hold_tap *hold_tap) { + if (hold_tap->config->retro_tap && hold_tap->status == STATUS_HOLD_TIMER) { + return 0; + } + + if (hold_tap->status == STATUS_HOLD_TIMER || hold_tap->status == STATUS_HOLD_INTERRUPT) { + return release_hold_binding(hold_tap); + } else { + return release_tap_binding(hold_tap); } - return behavior_keymap_binding_released(&binding, event); } static bool is_first_other_key_pressed_trigger_key(struct active_hold_tap *hold_tap) { @@ -474,6 +517,12 @@ static void decide_hold_tap(struct active_hold_tap *hold_tap, return; } + if (hold_tap->config->hold_while_undecided && decision_moment == HT_KEY_DOWN) { + LOG_DBG("%d hold behavior pressed while undecided", hold_tap->position); + press_hold_binding(hold_tap); + return; + } + // If the hold-tap behavior is still undecided, attempt to decide it. switch (hold_tap->config->flavor) { case FLAVOR_HOLD_PREFERRED: @@ -561,6 +610,8 @@ static int on_hold_tap_binding_pressed(struct zmk_behavior_binding *binding, decide_hold_tap(hold_tap, HT_QUICK_TAP); } + decide_hold_tap(hold_tap, HT_KEY_DOWN); + // if this behavior was queued we have to adjust the timer to only // wait for the remaining time. int32_t tapping_term_ms_left = (hold_tap->timestamp + cfg->tapping_term_ms) - k_uptime_get(); @@ -588,6 +639,10 @@ static int on_hold_tap_binding_released(struct zmk_behavior_binding *binding, decide_retro_tap(hold_tap); release_binding(hold_tap); + if (hold_tap->config->hold_while_undecided && hold_tap->config->hold_while_undecided_linger) { + release_hold_binding(hold_tap); + } + if (work_cancel_result == -EINPROGRESS) { // let the timer handler clean up // if we'd clear now, the timer may call back for an uninitialized active_hold_tap. @@ -685,6 +740,12 @@ static int keycode_state_changed_listener(const zmk_event_t *eh) { return ZMK_EV_EVENT_BUBBLE; } + // hold-while-undecided can produce a mod, but we don't want to capture it. + if (undecided_hold_tap->config->hold_while_undecided && + undecided_hold_tap->status == STATUS_UNDECIDED) { + return ZMK_EV_EVENT_BUBBLE; + } + // only key-up events will bubble through position_state_changed_listener // if a undecided_hold_tap is active. LOG_DBG("%d capturing 0x%02X %s event", undecided_hold_tap->position, ev->keycode, @@ -743,6 +804,8 @@ static int behavior_hold_tap_init(const struct device *dev) { ? DT_INST_PROP(n, quick_tap_ms) \ : DT_INST_PROP(n, require_prior_idle_ms), \ .flavor = DT_ENUM_IDX(DT_DRV_INST(n), flavor), \ + .hold_while_undecided = DT_INST_PROP(n, hold_while_undecided), \ + .hold_while_undecided_linger = DT_INST_PROP(n, hold_while_undecided_linger), \ .retro_tap = DT_INST_PROP(n, retro_tap), \ .hold_trigger_on_release = DT_INST_PROP(n, hold_trigger_on_release), \ .hold_trigger_key_positions = DT_INST_PROP(n, hold_trigger_key_positions), \ diff --git a/app/tests/hold-tap/hold-while-undecided/1-tap/events.patterns b/app/tests/hold-tap/hold-while-undecided/1-tap/events.patterns new file mode 100644 index 0000000000..fdf2b15cf2 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/1-tap/events.patterns @@ -0,0 +1,4 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p +s/.*on_hold_tap_binding/ht_binding/p +s/.*decide_hold_tap/ht_decide/p
\ No newline at end of file diff --git a/app/tests/hold-tap/hold-while-undecided/1-tap/keycode_events.snapshot b/app/tests/hold-tap/hold-while-undecided/1-tap/keycode_events.snapshot new file mode 100644 index 0000000000..7cbc826886 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/1-tap/keycode_events.snapshot @@ -0,0 +1,8 @@ +ht_binding_pressed: 0 new undecided hold_tap +ht_decide: 0 hold behavior pressed while undecided +kp_pressed: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +ht_decide: 0 decided tap (balanced decision moment key-up) +kp_released: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +kp_pressed: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00 +kp_released: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00 +ht_binding_released: 0 cleaning up hold-tap diff --git a/app/tests/hold-tap/hold-while-undecided/1-tap/native_posix_64.keymap b/app/tests/hold-tap/hold-while-undecided/1-tap/native_posix_64.keymap new file mode 100644 index 0000000000..09396dd824 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/1-tap/native_posix_64.keymap @@ -0,0 +1,36 @@ +#include <dt-bindings/zmk/keys.h> +#include <behaviors.dtsi> +#include <dt-bindings/zmk/kscan_mock.h> + +/ { + behaviors { + ht_bal: behavior_hold_tap_balanced { + compatible = "zmk,behavior-hold-tap"; + label = "HOLD_TAP_BALANCED"; + #binding-cells = <2>; + flavor = "balanced"; + tapping-term-ms = <300>; + quick-tap-ms = <200>; + bindings = <&kp>, <&kp>; + hold-while-undecided; + }; + }; + + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &ht_bal LEFT_SHIFT A &ht_bal LEFT_CONTROL B + &kp D &kp RIGHT_CONTROL>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,0,10) + ZMK_MOCK_RELEASE(0,0,10) + >; +}; diff --git a/app/tests/hold-tap/hold-while-undecided/2-hold/events.patterns b/app/tests/hold-tap/hold-while-undecided/2-hold/events.patterns new file mode 100644 index 0000000000..fdf2b15cf2 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/2-hold/events.patterns @@ -0,0 +1,4 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p +s/.*on_hold_tap_binding/ht_binding/p +s/.*decide_hold_tap/ht_decide/p
\ No newline at end of file diff --git a/app/tests/hold-tap/hold-while-undecided/2-hold/keycode_events.snapshot b/app/tests/hold-tap/hold-while-undecided/2-hold/keycode_events.snapshot new file mode 100644 index 0000000000..d9eed61285 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/2-hold/keycode_events.snapshot @@ -0,0 +1,6 @@ +ht_binding_pressed: 0 new undecided hold_tap +ht_decide: 0 hold behavior pressed while undecided +kp_pressed: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +ht_decide: 0 decided hold-timer (balanced decision moment timer) +kp_released: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +ht_binding_released: 0 cleaning up hold-tap diff --git a/app/tests/hold-tap/hold-while-undecided/2-hold/native_posix_64.keymap b/app/tests/hold-tap/hold-while-undecided/2-hold/native_posix_64.keymap new file mode 100644 index 0000000000..e3eaa8e05e --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/2-hold/native_posix_64.keymap @@ -0,0 +1,36 @@ +#include <dt-bindings/zmk/keys.h> +#include <behaviors.dtsi> +#include <dt-bindings/zmk/kscan_mock.h> + +/ { + behaviors { + ht_bal: behavior_hold_tap_balanced { + compatible = "zmk,behavior-hold-tap"; + label = "HOLD_TAP_BALANCED"; + #binding-cells = <2>; + flavor = "balanced"; + tapping-term-ms = <100>; + quick-tap-ms = <200>; + bindings = <&kp>, <&kp>; + hold-while-undecided; + }; + }; + + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &ht_bal LEFT_SHIFT A &ht_bal LEFT_CONTROL B + &kp D &kp RIGHT_CONTROL>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,0,150) + ZMK_MOCK_RELEASE(0,0,10) + >; +}; diff --git a/app/tests/hold-tap/hold-while-undecided/3-linger/events.patterns b/app/tests/hold-tap/hold-while-undecided/3-linger/events.patterns new file mode 100644 index 0000000000..fdf2b15cf2 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/3-linger/events.patterns @@ -0,0 +1,4 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p +s/.*on_hold_tap_binding/ht_binding/p +s/.*decide_hold_tap/ht_decide/p
\ No newline at end of file diff --git a/app/tests/hold-tap/hold-while-undecided/3-linger/keycode_events.snapshot b/app/tests/hold-tap/hold-while-undecided/3-linger/keycode_events.snapshot new file mode 100644 index 0000000000..55c9bb32f7 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/3-linger/keycode_events.snapshot @@ -0,0 +1,8 @@ +ht_binding_pressed: 0 new undecided hold_tap +ht_decide: 0 hold behavior pressed while undecided +kp_pressed: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +ht_decide: 0 decided tap (balanced decision moment key-up) +kp_pressed: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00 +kp_released: usage_page 0x07 keycode 0x04 implicit_mods 0x00 explicit_mods 0x00 +kp_released: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +ht_binding_released: 0 cleaning up hold-tap diff --git a/app/tests/hold-tap/hold-while-undecided/3-linger/native_posix_64.keymap b/app/tests/hold-tap/hold-while-undecided/3-linger/native_posix_64.keymap new file mode 100644 index 0000000000..4b694eb2d1 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/3-linger/native_posix_64.keymap @@ -0,0 +1,37 @@ +#include <dt-bindings/zmk/keys.h> +#include <behaviors.dtsi> +#include <dt-bindings/zmk/kscan_mock.h> + +/ { + behaviors { + ht_bal: behavior_hold_tap_balanced { + compatible = "zmk,behavior-hold-tap"; + label = "HOLD_TAP_BALANCED"; + #binding-cells = <2>; + flavor = "balanced"; + tapping-term-ms = <100>; + quick-tap-ms = <300>; + bindings = <&kp>, <&kp>; + hold-while-undecided; + hold-while-undecided-linger; + }; + }; + + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &ht_bal LEFT_SHIFT A &ht_bal LEFT_CONTROL B + &kp D &kp RIGHT_CONTROL>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,0,10) + ZMK_MOCK_RELEASE(0,0,10) + >; +}; diff --git a/app/tests/hold-tap/hold-while-undecided/4-linger-sk/events.patterns b/app/tests/hold-tap/hold-while-undecided/4-linger-sk/events.patterns new file mode 100644 index 0000000000..fdf2b15cf2 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/4-linger-sk/events.patterns @@ -0,0 +1,4 @@ +s/.*hid_listener_keycode/kp/p +s/.*mo_keymap_binding/mo/p +s/.*on_hold_tap_binding/ht_binding/p +s/.*decide_hold_tap/ht_decide/p
\ No newline at end of file diff --git a/app/tests/hold-tap/hold-while-undecided/4-linger-sk/keycode_events.snapshot b/app/tests/hold-tap/hold-while-undecided/4-linger-sk/keycode_events.snapshot new file mode 100644 index 0000000000..74f88195b3 --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/4-linger-sk/keycode_events.snapshot @@ -0,0 +1,7 @@ +ht_binding_pressed: 0 new undecided hold_tap +ht_decide: 0 hold behavior pressed while undecided +kp_pressed: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +ht_decide: 0 decided tap (balanced decision moment key-up) +kp_pressed: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +kp_released: usage_page 0x07 keycode 0xE1 implicit_mods 0x00 explicit_mods 0x00 +ht_binding_released: 0 cleaning up hold-tap diff --git a/app/tests/hold-tap/hold-while-undecided/4-linger-sk/native_posix_64.keymap b/app/tests/hold-tap/hold-while-undecided/4-linger-sk/native_posix_64.keymap new file mode 100644 index 0000000000..a748ae51fc --- /dev/null +++ b/app/tests/hold-tap/hold-while-undecided/4-linger-sk/native_posix_64.keymap @@ -0,0 +1,37 @@ +#include <dt-bindings/zmk/keys.h> +#include <behaviors.dtsi> +#include <dt-bindings/zmk/kscan_mock.h> + +/ { + behaviors { + ht_bal: behavior_hold_tap_balanced { + compatible = "zmk,behavior-hold-tap"; + label = "HOLD_TAP_BALANCED"; + #binding-cells = <2>; + flavor = "balanced"; + tapping-term-ms = <100>; + quick-tap-ms = <200>; + bindings = <&kp>, <&sk>; + hold-while-undecided; + hold-while-undecided-linger; + }; + }; + + keymap { + compatible = "zmk,keymap"; + label ="Default keymap"; + + default_layer { + bindings = < + &ht_bal LEFT_SHIFT LEFT_SHIFT &ht_bal LEFT_SHIFT LEFT_CONTROL + &kp D &kp RIGHT_CONTROL>; + }; + }; +}; + +&kscan { + events = < + ZMK_MOCK_PRESS(0,0,10) + ZMK_MOCK_RELEASE(0,0,10) + >; +}; diff --git a/docs/docs/behaviors/hold-tap.mdx b/docs/docs/behaviors/hold-tap.mdx index 26af9f1d83..191e820dd4 100644 --- a/docs/docs/behaviors/hold-tap.mdx +++ b/docs/docs/behaviors/hold-tap.mdx @@ -83,6 +83,18 @@ For example, if you press `&mt LEFT_SHIFT A` and then release it without pressin }; ``` +#### `hold-while-undecided` + +If enabled, the hold behavior will immediately be held on hold-tap press, and will release before the behavior is sent in the event the hold-tap resolves into a tap. With most modifiers this will not affect typing, and is useful for using modifiers with the mouse. + +:::note Alt/Win/Cmd behavior +In some applications/desktop environments, pressing Alt keycodes by itself will have its own behavior like activate a menu and Gui keycodes will bring up the start menu or an application launcher. +::: + +#### `hold-while-undecided-linger` + +If your tap behavior activates the same modifier as the hold behavior, and you want to avoid a double tap when transitioning from the hold to the tap, you can use `hold-while-undecided-linger`. When enabled, the hold behavior will continue to be held until _after_ the tap behavior is released. For example, if the hold is `&kp LGUI` and the tap is `&sk LGUI`, then with `hold-while-undecided-linger` enabled, the host will see `LGUI` held down continuously until the sticky key is finished, instead of seeing a release and press when transitioning from hold to sticky key. + #### Positional hold-tap and `hold-trigger-key-positions` Including `hold-trigger-key-positions` in your hold-tap definition turns on the positional hold-tap feature. With positional hold-tap enabled, if you press any key **NOT** listed in `hold-trigger-key-positions` before `tapping-term-ms` expires, it will produce a tap. diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index c31de5dd0a..f8d2fe39eb 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -57,16 +57,18 @@ Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml](htt Applies to: `compatible = "zmk,behavior-hold-tap"` -| Property | Type | Description | Default | -| ---------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------ | -| `#binding-cells` | int | Must be `<2>` | | -| `bindings` | phandle array | A list of two behaviors (without parameters): one for hold and one for tap | | -| `flavor` | string | Adjusts how the behavior chooses between hold and tap | `"hold-preferred"` | -| `tapping-term-ms` | int | How long in milliseconds the key must be held to trigger a hold | | -| `quick-tap-ms` | int | Tap twice within this period (in milliseconds) to trigger a tap, even when held | -1 (disabled) | -| `require-prior-idle-ms` | int | Triggers a tap immediately if any non-modifier key was pressed within `require-prior-idle-ms` of the hold-tap. | -1 (disabled) | -| `retro-tap` | bool | Triggers the tap behavior on release if no other key was pressed during a hold | false | -| `hold-trigger-key-positions` | array | If set, pressing the hold-tap and then any key position _not_ in the list triggers a tap. | | +| Property | Type | Description | Default | +| ----------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------ | +| `#binding-cells` | int | Must be `<2>` | | +| `bindings` | phandle array | A list of two behaviors (without parameters): one for hold and one for tap | | +| `flavor` | string | Adjusts how the behavior chooses between hold and tap | `"hold-preferred"` | +| `tapping-term-ms` | int | How long in milliseconds the key must be held to trigger a hold | | +| `quick-tap-ms` | int | Tap twice within this period (in milliseconds) to trigger a tap, even when held | -1 (disabled) | +| `require-prior-idle-ms` | int | Triggers a tap immediately if any non-modifier key was pressed within `require-prior-idle-ms` of the hold-tap. | -1 (disabled) | +| `retro-tap` | bool | Triggers the tap behavior on release if no other key was pressed during a hold | false | +| `hold-while-undecided` | bool | Triggers the hold behavior immediately on press and releases before a tap | false | +| `hold-while-undecided-linger` | bool | Continues to hold the hold behavior until after the tap is released | false | +| `hold-trigger-key-positions` | array | If set, pressing the hold-tap and then any key position _not_ in the list triggers a tap. | | This behavior forwards the first parameter it receives to the parameter of the first behavior specified in `bindings`, and second parameter to the parameter of the second behavior. |