Firngrod/key chords

doc-dev/reference-manual.md

@@ -183,6 +183,10 @@ COMMAND = set oneShotTimeout <time in ms (INT)>
 COMMAND = set macroEngine.batchSize <number of commands to execute per one update cycle INT>
 COMMAND = set navigationModeAction.NAVIGATION_MODE_CUSTOM.DIRECTION ACTION
 COMMAND = set keymapAction.LAYERID.KEYID ACTION
+COMMAND = set chord[.LAYERID_BASIC] KEYID KEYID [KEYID]* ACTION
+COMMAND = set chordTimeout <ms, 0-255 (INT)> sets the chord activation window size
+COMMAND = set chordPriorIdleTime <ms, 0-65535 (INT)> sets the minimum dead time before a chord can trigger
+COMMAND = set chordLifetime { leadingKey | allKeys } sets how long a chord activation lasts
 COMMAND = set backlight.strategy { functional | constantRgb | perKeyRgb | off }
 COMMAND = set backlight.constantRgb.rgb <number 0-255 (INT)> <number 0-255 (INT)> <number 0-255 (INT)><number 0-255 (INT)>
 COMMAND = set backlight.keyRgb.LAYERID.KEYID <number 0-255 (INT)> <number 0-255 (INT)> <number 0-255 (INT)>
@@ -722,6 +726,16 @@ Key actions can be parametrized with macro arguments. These arguments can be exp
   - `set navigationModeAction.{caret|media}.{DIRECTION|none} ACTION` can be used to customize the caret or media mode behaviour by binding directions to macros. This action is global and reversible only by powercycling.
   - `set keymapAction.LAYERID.KEYID ACTION` can be used to remap any action that lives in a keymap. Most remappable ids can be retrieved with `resolveNextKeyId`. Keyid can also be constructed manually - see `KEYID`. Binding applies only until the next keymap switch. E.g., `set keymapAction.base.64 keystroke escape` (maps `~` key to escape), or `set keymapAction.fn.193 macro TouchpadAction` (maps touchpad two-finger gesture to a macro named `TouchpadAction`).
 
+- Chords
+  Chords is a concept where a number of keys can be linked together such that if they are pressed together all at once, like a chord on a piano, a specific action is taken, different from what each of the keys do on their own.  Anywhere between 2 and 5 keys can be chorded together and associated with an `ACTION`
+
+  - `set chord[.LAYERID_BASIC] ACTION` Configures a chord with an action.  If a layer is specified, the chord will be available when that layer is active, if not, it will be available on any layer.  The same chord can be defined for different actions for different layers, including the `any` layer.  If action is `none`, the chord is removed and the keys will work as individual keys if the chord is pressed, not as an empty action.
+  - `set chordTimeout <ms, 0-255 (INT)>` sets the interval within which all keys of a chord must be pressed in order for the chord to be activated.
+  - `set chordPriorIdleTime <ms, 0-65535 (INT)>` sets a limit to how soon a chord can be activated after a key has been pressed.  This helps prevent accidental activations while typing rapidly.  Chords do not prevent chord activations, so chords can still be doubletapped.
+  - `set chordLifetime { leadingKey | allKeys }` sets how long a chord activation lasts.  With `leadingKey`, the chord is considered released when earliest key pressed in the activation is released, with `allKeys`, the chord is considered released when all keys in the chord is released.
+
+  Chords are reset every time the keymap is changed, so they are best set using the `$onKeymapChange` macro event.  A maximum of 64 chords can be defined at a time.
+
 - Secondary roles section configures the resolution strategy used for controlling both the native (agent-mapped) secondary roles and the`ifPrimary` and `ifSecondary` conditions.
 
   - `set secondaryRole.defaultStrategy [ simple | advanced ]` sets the default resolution strategy to be used. Furthermore, `ifPrimary/ifSecondary` can specify explicitly which strategy to use (e.g., `ifPrimary advancedStrategy final tapKey a`).

doc-dev/user-guide.md

@@ -543,6 +543,24 @@ set keymapAction.base.192 macro TouchpadLeft
 set keymapAction.base.193 macro TouchpadRight
 ```
 
+### Key Chords
+
+A different kind of gestures exists: Chords.  A chord is when a set of keys are associated with each other such that if they are pressed all at once, like a chord on a piano, they do something different from the functionality of each key on it's own.
+
+In order to define a macro, you can use the command `set chord[.LAYERID_BASIC] KEYID KEYID [KEYID]* ACTION`.  Up to five keys can be used for each chord.
+
+An example could be to use it for the Vim user's eternal quest for an ergonomical Esc button.  But on the mod layer, we want that chord to perform another action, in this case a macro.  Also, to spare the right pinky, we can put an Enter key near the home row on the right hand, but only on the base layer.
+
+```
+set chord q w keystroke escape
+set chord.mod q w macro DetachScreen
+set chord.base u i keystroke enter
+```
+
+All defined chords are cleared/undefined on keymap change, so chords are most sensibly set using the `$onKeymapChange` macro triggers.
+
+The behavior of chords can be fine-tuned using `set chordTimeout`, `set chordPriorIdleTime` and `set chordLifetime`
+
 ### Macro recorder
 
 Runtime macro recorder allows capturing and replaying sequences of scancodes. Each such macro is identified by a number or a character (or `$thisKeyId` which resolves to the `KEYID` of the current key, therefore allowing generic key-associated macros). (Runtime macros are unrelated to the macros that can be created via Agent.)

right/src/CMakeLists.txt

@@ -21,6 +21,7 @@ endif()
 
 target_sources(${PROJECT_NAME} PRIVATE
     caret_config.c
+    chords.c
     config_manager.c
     debug.c
     eeprom.c