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

feat(behaviors): hold while undecided

Browse source
This commit is contained in:
Theo Lemay 2023-05-22 19:34:29 -07:00 • committed by Pete Johanson
parent 104c73d303
commit c007d60357
16 changed files with 306 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml
View file

@ -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:

101
app/src/behaviors/behavior_hold_tap.c
View file

@ -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};
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 {
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};
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_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) {
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 {
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;
}
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;
return release_hold_binding(hold_tap);
} else {
binding.behavior_dev = hold_tap->config->tap_behavior_dev;
binding.param1 = hold_tap->param_tap;
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), \

4
app/tests/hold-tap/hold-while-undecided/1-tap/events.patterns Normal file
View file

@ -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

8
app/tests/hold-tap/hold-while-undecided/1-tap/keycode_events.snapshot Normal file
View file

@ -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

36
app/tests/hold-tap/hold-while-undecided/1-tap/native_posix_64.keymap Normal file
View file

@ -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)
>;
};

4
app/tests/hold-tap/hold-while-undecided/2-hold/events.patterns Normal file
View file

@ -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

6
app/tests/hold-tap/hold-while-undecided/2-hold/keycode_events.snapshot Normal file
View file

@ -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

36
app/tests/hold-tap/hold-while-undecided/2-hold/native_posix_64.keymap Normal file
View file

@ -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)
>;
};

4
app/tests/hold-tap/hold-while-undecided/3-linger/events.patterns Normal file
View file

@ -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

8
app/tests/hold-tap/hold-while-undecided/3-linger/keycode_events.snapshot Normal file
View file

@ -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

37
app/tests/hold-tap/hold-while-undecided/3-linger/native_posix_64.keymap Normal file
View file

@ -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)
>;
};

4
app/tests/hold-tap/hold-while-undecided/4-linger-sk/events.patterns Normal file
View file

@ -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

7
app/tests/hold-tap/hold-while-undecided/4-linger-sk/keycode_events.snapshot Normal file
View file

@ -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

37
app/tests/hold-tap/hold-while-undecided/4-linger-sk/native_posix_64.keymap Normal file
View file

@ -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)
>;
};

12
docs/docs/behaviors/hold-tap.mdx
View file

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

4
docs/docs/config/behaviors.md
View file

@ -58,7 +58,7 @@ 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"` |
@ -66,6 +66,8 @@ Applies to: `compatible = "zmk,behavior-hold-tap"`
| `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.