From 544ddde113657a932275399f577a422a809d2880 Mon Sep 17 00:00:00 2001 From: Pascal Getreuer <50221757+getreuer@users.noreply.github.com> Date: Mon, 27 Jan 2025 03:32:23 -0800 Subject: [Core] Add Chordal Hold, an "opposite hands rule" tap-hold option similar to Achordion, Bilateral Combinations. (#24560) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Chordal Hold: restrict what chords settle as hold * Chordal Hold: docs and further improvements * Fix formatting. * Doc rewording and minor edit. * Support Chordal Hold of multiple tap-hold keys. * Fix formatting. * Simplification and additional test. * Fix formatting. * Tighten tests. * Add test two_mod_taps_same_hand_hold_til_timeout. * Revise handing of pairs of tap-hold keys. * Generate a default chordal_hold_layout. * Document chordal_hold_handedness(). * Add license notice to new and branched files in PR. * Add `tapping.chordal_hold` property for info.json. * Update docs/reference_info_json.md * Revise "hand" jsonschema. * Chordal Hold: Improved layout handedness heuristic. This commit improves the heuristic used in generate-keyboard-c for inferring key handedness from keyboard.json geometry data. Heuristic summary: 1. If the layout is symmetric (e.g. most split keyboards), guess the handedness based on the sign of (x - layout_x_midpoint). 2. Otherwise, if the layout has a key of >=6u width, it is probably the spacebar. Form a dividing line through the spacebar, nearly vertical but with a slight angle to follow typical row stagger. 3. Otherwise, assume handedness based on the widest horizontal separation. I have tested this strategy on a couple dozen keyboards and found it to work reliably. * Use Optional instead of `| None`. * Refactor to avoid lambdas. * Remove trailing comma in chordal_hold_layout. * Minor docs edits. * Revise to allow combining multiple same-hand mods. This commit revises Chordal Hold as described in discussion in https://github.com/qmk/qmk_firmware/pull/24560#discussion_r1894655238 1. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓, RCTL_T(KC_A)↑" before the tapping term, RCTL_T(KC_A) is settled as tapped. 2. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓, RSFT_T(KC_C)↑", both RCTL_T(KC_A) and RSFT_T(KC_C) are settled as tapped. 3. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓, KC_U↓" (all keys on the same side), both RCTL_T(KC_A) and RSFT_T(KC_C) are settled as tapped. 4. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓, LSFT_T(KC_T)↓", with the third key on the other side, we allow Permissive Hold or Hold On Other Keypress to decide how/when to settle the keys. 5. In "RCTL_T(KC_A)↓, RSFT_T(KC_C)↓" held until the tapping term, the keys are settled as held. 1–3 provide same-hand roll protection. 4–5 are for combining multiple same-hand modifiers. I've updated the unit tests and have been running it on my keyboard, for a few hours so far, and all seems good. I really like this scheme. It allows combining same-side mods, yet it also has roll protection on streaks. For me, this feels like Achordion, but clearly better streak handling and improved responsiveness. * Fix formatting. * Add a couple tests with LT keys. * Remove stale use of CHORDAL_HOLD_LAYOUT. * Fix misspelling lastest -> latest * Handling tweak for LTs and tests. * Fix formatting. * More tests with LT keys. * Fix formatting. --- docs/reference_info_json.md | 4 ++ docs/tap_hold.md | 163 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+) (limited to 'docs') diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 99ff7b1f7a..29b999c32e 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -74,6 +74,8 @@ You can create `info.json` files at every level under `qmk_firmware/keyboards/Boolean + * Default: `false` * `hold_on_other_key_press` Boolean * Default: `false` * `hold_on_other_key_press_per_key` Boolean @@ -328,6 +330,8 @@ The ISO enter key is represented by a 1.25u×2uh key. Renderers which utilize in * `h` KeyUnit * The height of the key, in key units. * Default: `1` (1u) + * `hand` String + * The handedness of the key for Chordal Hold, either `"L"` (left hand), `"R"` (right hand), or `"*"` (either or exempted handedness). * `label` String * What to name the key. This is *not* a key assignment as in the keymap, but should usually correspond to the keycode for the first layer of the default keymap. * Example: `"Escape"` diff --git a/docs/tap_hold.md b/docs/tap_hold.md index 9b7f6552cb..254d5de5ec 100644 --- a/docs/tap_hold.md +++ b/docs/tap_hold.md @@ -425,6 +425,169 @@ uint16_t get_quick_tap_term(uint16_t keycode, keyrecord_t *record) { If `QUICK_TAP_TERM` is set higher than `TAPPING_TERM`, it will default to `TAPPING_TERM`. ::: +## Chordal Hold + +Chordal Hold is intended to be used together with either Permissive Hold or Hold +On Other Key Press. Chordal Hold is enabled by adding to your `config.h`: + +```c +#define CHORDAL_HOLD +``` + +Chordal Hold implements, by default, an "opposite hands" rule. Suppose a +tap-hold key is pressed and then, before the tapping term, another key is +pressed. With Chordal Hold, the tap-hold key is settled as tapped if the two +keys are on the same hand. + +Otherwise, if the keys are on opposite hands, Chordal Hold introduces no new +behavior. Hold On Other Key Press or Permissive Hold may be used together with +Chordal Hold to configure the behavior in the opposite hands case. With Hold On +Other Key Press, an opposite hands chord is settled immediately as held. Or with +Permissive Hold, an opposite hands chord is settled as held provided the other +key is pressed and released (nested press) before releasing the tap-hold key. + +Chordal Hold may be useful to avoid accidental modifier activation with +mod-taps, particularly in rolled keypresses when using home row mods. + +Notes: + +* Chordal Hold has no effect after the tapping term. + +* Combos are exempt from the opposite hands rule, since "handedness" is + ill-defined in this case. Even so, Chordal Hold's behavior involving combos + may be customized through the `get_chordal_hold()` callback. + +An example of a sequence that is affected by “chordal hold”: + +- `SFT_T(KC_A)` Down +- `KC_C` Down +- `KC_C` Up +- `SFT_T(KC_A)` Up + +``` + TAPPING_TERM + +---------------------------|--------+ + | +----------------------+ | | + | | SFT_T(KC_A) | | | + | +----------------------+ | | + | +--------------+ | | + | | KC_C | | | + | +--------------+ | | + +---------------------------|--------+ +``` + +If the two keys are on the same hand, then this will produce `ac` with +`SFT_T(KC_A)` settled as tapped the moment that `KC_C` is pressed. + +If the two keys are on opposite hands and the `HOLD_ON_OTHER_KEY_PRESS` option +enabled, this will produce `C` with `SFT_T(KC_A)` settled as held when `KC_C` is +pressed. + +Or if the two keys are on opposite hands and the `PERMISSIVE_HOLD` option is +enabled, this will produce `C` with `SFT_T(KC_A)` settled as held when that +`KC_C` is released. + +### Chordal Hold Handedness + +Determining whether keys are on the same or opposite hands involves defining the +"handedness" of each key position. By default, if nothing is specified, +handedness is guessed based on keyboard geometry. + +Handedness may be specified with `chordal_hold_layout`. In keymap.c, define +`chordal_hold_layout` in the following form: + +```c +const char chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS] PROGMEM = + LAYOUT( + 'L', 'L', 'L', 'L', 'L', 'L', 'R', 'R', 'R', 'R', 'R', 'R', + 'L', 'L', 'L', 'L', 'L', 'L', 'R', 'R', 'R', 'R', 'R', 'R', + 'L', 'L', 'L', 'L', 'L', 'L', 'R', 'R', 'R', 'R', 'R', 'R', + 'L', 'L', 'L', 'R', 'R', 'R' + ); +``` + +Use the same `LAYOUT` macro as used to define your keymap layers. Each entry is +a character indicating the handedness of one key, either `'L'` for left, `'R'` +for right, or `'*'` to exempt keys from the "opposite hands rule." A key with +`'*'` handedness may settle as held in chords with any other key. This could be +used perhaps on thumb keys or other places where you want to allow same-hand +chords. + +Keyboard makers may specify handedness in keyboard.json. Under `"layouts"`, +specify the handedness of a key by adding a `"hand"` field with a value of +either `"L"`, `"R"`, or `"*"`. Note that if `"layouts"` contains multiple +layouts, only the first one is read. For example: + +```json +{"matrix": [5, 6], "x": 0, "y": 5.5, "w": 1.25, "hand", "*"}, +``` + +Alternatively, handedness may be defined functionally with +`chordal_hold_handedness()`. For example, in keymap.c define: + +```c +char chordal_hold_handedness(keypos_t key) { + if (key.col == 0 || key.col == MATRIX_COLS - 1) { + return '*'; // Exempt the outer columns. + } + // On split keyboards, typically, the first half of the rows are on the + // left, and the other half are on the right. + return key.row < MATRIX_ROWS / 2 ? 'L' : 'R'; +} +``` + +Given the matrix position of a key, the function should return `'L'`, `'R'`, or +`'*'`. Adapt the logic in this function according to the keyboard's matrix. + +::: warning +Note the matrix may have irregularities around larger keys, around the edges of +the board, and around thumb clusters. You may find it helpful to use [this +debugging example](faq_debug#which-matrix-position-is-this-keypress) to +correspond physical keys to matrix positions. +::: + +::: tip If you define both `chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS]` and +`chordal_hold_handedness(keypos_t key)` for handedness, the latter takes +precedence. +::: + + +### Per-chord customization + +Beyond the per-key configuration possible through handedness, Chordal Hold may +be configured at a *per-chord* granularity for detailed tuning. In keymap.c, +define `get_chordal_hold()`. Returning `true` allows the chord to be held, while +returning `false` settles as tapped. + +For example: + +```c +bool get_chordal_hold(uint16_t tap_hold_keycode, keyrecord_t* tap_hold_record, + uint16_t other_keycode, keyrecord_t* other_record) { + // Exceptionally allow some one-handed chords for hotkeys. + switch (tap_hold_keycode) { + case LCTL_T(KC_Z): + if (other_keycode == KC_C || other_keycode == KC_V) { + return true; + } + break; + + case RCTL_T(KC_SLSH): + if (other_keycode == KC_N) { + return true; + } + break; + } + // Otherwise defer to the opposite hands rule. + return get_chordal_hold_default(tap_hold_record, other_record); +} +``` + +As shown in the last line above, you may use +`get_chordal_hold_default(tap_hold_record, other_record)` to get the default tap +vs. hold decision according to the opposite hands rule. + + ## Retro Tapping To enable `retro tapping`, add the following to your `config.h`: -- cgit v1.2.3