Process combos earlier & overlapping combos (#8591)
* Combo processing improvements.
Now it is possible to use ModTap and LayerTap keys as part of combos.
Overlapping combos also don't trigger all the combos, just exactly the
one that you press.
New settings:
- COMBO_MUST_HOLD_MODS
- COMBO_MOD_TERM
- COMBO_TERM_PER_COMBO
- COMBO_MUST_HOLD_PER_COMBO
- COMBO_STRICT_TIMER
- COMBO_NO_TIMER
* Remove the size flags from combo_t struct boolean members.
This in the end actually saves space as the members are accessed so many
times. The amount of operations needed to access the bits uses more
memory than setting the size saves.
* Fix `process_combo_key_release` not called correctly with tap-only combos
* Fix not passing a pointer when NO_ACTION_TAPPING is defined.
* Docs for `COMBO_ONLY_FROM_LAYER`
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Update quantum/process_keycode/process_combo.c
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Add `EXTRA_SHORT_COMBOS` option.
Stuff combo's `disabled` and `active` flags into `state`. Possibly can
save some space.
* Add more examples and clarify things with dict management system.
- Simple examples now has a combo that has modifiers included.
- The slightly more advanced examples now are actually more advanced
instead of just `tap_code16(<modded-keycode>)`.
- Added a note that `COMBO_ACTION`s are not needed anymore as you can
just use custom keycodes.
- Added a note that the `g/keymap_combo.h` macros use the
`process_combo_event` function and that it is not usable in one's
keymap afterwards.
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Change "the" combo action example to "email" example.
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Fix sneaky infinite loop with `combo_disable()`
No need to call `dump_key_buffer` when disabling combos because the
buffer is either being dumped if a combo-key was pressed, or the buffer is empty
if a non-combo-key is pressed.
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
* Update docs/feature_combo.md
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
Co-authored-by: precondition <57645186+precondition@users.noreply.github.com>
Co-authored-by: Drashna Jaelre <drashna@live.com>
@ -188,9 +188,21 @@ If you define these options you will enable the associated feature, which may in
few ms of delay from this. But if you're doing chording on something with 3-4ms
scan times? You probably want this.
* `#define COMBO_COUNT 2`
* Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
* Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature. Or leave it undefined and programmatically set the count.
* `#define COMBO_TERM 200`
* how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
* `#define COMBO_MUST_HOLD_MODS`
* Flag for enabling extending timeout on Combos containing modifers
* `#define COMBO_MOD_TERM 200`
* Allows for extending COMBO_TERM for mod keys while mid-combo.
* `#define COMBO_MUST_HOLD_PER_COMBO`
* Flag to enable per-combo COMBO_TERM extension and `get_combo_must_hold()` function
* `#define COMBO_TERM_PER_COMBO`
* Flag to enable per-combo COMBO_TERM extension and `get_combo_term()` function
* `#define COMBO_STRICT_TIMER`
* Only start the combo timer on the first key press instead of on all key presses.
* `#define COMBO_NO_TIMER`
* Disable the combo timer completely for relaxed combos.
* `#define TAP_CODE_DELAY 100`
* Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
The Combo feature is a chording type solution for adding custom actions. It lets you hit multiple keys at once and produce a different effect. For instance, hitting `A` and `S` within the tapping term would hit `ESC` instead, or have it perform even more complex tasks.
The Combo feature is a chording type solution for adding custom actions. It lets you hit multiple keys at once and produce a different effect. For instance, hitting `A` and `S` within the combo term would hit `ESC` instead, or have it perform even more complex tasks.
To enable this feature, you need to add `COMBO_ENABLE = yes` to your `rules.mk`.
Additionally, in your `config.h`, you'll need to specify the number of combos that you'll be using, by adding `#define COMBO_COUNT 1` (replacing 1 with the number that you're using).
<!-- At this time, this is necessary -->
Additionally, in your `config.h`, you'll need to specify the number of combos that you'll be using, by adding `#define COMBO_COUNT 1` (replacing 1 with the number that you're using). It is also possible to not define this and instead set the variable `COMBO_LEN` yourself. There's a trick where we don't need to think about this variable at all. More on this later.
Also, by default, the tapping term for the Combos is set to the same value as `TAPPING_TERM` (200 by default on most boards). But you can specify a different value by defining it in your `config.h`. For instance: `#define COMBO_TERM 300` would set the time out period for combos to 300ms.
Then, your `keymap.c` file, you'll need to define a sequence of keys, terminated with `COMBO_END`, and a structure to list the combination of keys, and it's resulting action.
Then, in your `keymap.c` file, you'll need to define a sequence of keys, terminated with `COMBO_END`, and a structure to list the combination of keys, and its resulting action.
COMBO(test_combo2, LCTL(KC_Z)), // keycodes with modifiers are possible too!
};
```
This will send "Escape" if you hit the A and B keys.
This will send "Escape" if you hit the A and B keys, and Ctrl+Z when you hit the C and D keys.
As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to fire combos from ModTap keys and LayerTap keys. So in the above example you could have keys `LSFT_T(KC_A)` and `LT(_LAYER, KC_B)` and it would work. So Home Row Mods and Home Row Combos at same time is now a thing!
!> This method only supports [basic keycodes](keycodes_basic.md). See the examples for more control.
It is also now possible to overlap combos. Before, with the example below both combos would activate when all three keys were pressed. Now only the three key combo will activate.
This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit X and V. But you could change this to do stuff like change layers, play sounds, or change settings.
## Additional Configuration
This will send "john.doe@example.com" if you chord E and M together, and clear the current line with Backspace and Left-Shift. You could change this to do stuff like play sounds or change settings.
If you're using long combos, or even longer combos, you may run into issues with this, as the structure may not be large enough to accommodate what you're doing.
It is worth noting that `COMBO_ACTION`s are not needed anymore. As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to run your own custom keycodes from combos. Just define the custom keycode, program its functionality in `process_record_user`, and define a combo with `COMBO(<key_array>, <your_custom_keycode>)`.
In this case, you can add either `#define EXTRA_LONG_COMBOS` or `#define EXTRA_EXTRA_LONG_COMBOS` in your `config.h` file.
You may also be able to enable action keys by defining `COMBO_ALLOW_ACTION_KEYS`.
## Keycodes
You can enable, disable and toggle the Combo feature on the fly. This is useful if you need to disable them temporarily, such as for a game.
## Keycodes
You can enable, disable and toggle the Combo feature on the fly. This is useful if you need to disable them temporarily, such as for a game. The following keycodes are available for use in your `keymap.c`
|Keycode |Description |
|----------|---------------------------------|
@ -91,6 +111,187 @@ You can enable, disable and toggle the Combo feature on the fly. This is useful
|`CMB_OFF` |Turns off Combo feature |
|`CMB_TOG` |Toggles Combo feature on and off |
# Advanced Configuration
These configuration settings can be set in your `config.h` file.
## Combo Term
By default, the timeout for the Combos to be recognized is set to 50ms. This can be changed if accidental combo misfires are happening or if you're having difficulties pressing keys at the same time. For instance, `#define COMBO_TERM 40` would set the timeout period for combos to 40ms.
## Buffer and state sizes
If you're using long combos, or you have a lot of overlapping combos, you may run into issues with this, as the buffers may not be large enough to accommodate what you're doing. In this case, you can configure the sizes of the buffers used. Be aware, larger combo sizes and larger buffers will increase memory usage!
To configure the amount of keys a combo can be composed of, change the following:
| Keys | Define to be set |
|------|-----------------------------------|
| 6 | `#define EXTRA_SHORT_COMBOS` |
| 8 | QMK Default |
| 16 | `#define EXTRA_LONG_COMBOS` |
| 32 | `#define EXTRA_EXTRA_LONG_COMBOS` |
Defining `EXTRA_SHORT_COMBOS` combines a combo's internal state into just one byte. This can, in some cases, save some memory. If it doesn't, no point using it. If you do, you also have to make sure you don't define combos with more than 6 keys.
Processing combos has two buffers, one for the key presses, another for the combos being activated. Use the following options to configure the sizes of these buffers:
If a combo resolves to a Modifier, the window for processing the combo can be extended independently from normal combos. By default, this is disabled but can be enabled with `#define COMBO_MUST_HOLD_MODS`, and the time window can be configured with `#define COMBO_HOLD_TERM 150` (default: `TAPPING_TERM`). With `COMBO_MUST_HOLD_MODS`, you cannot tap the combo any more which makes the combo less prone to misfires.
## Per Combo Timing, Holding and Tapping
For each combo, it is possible to configure the time window it has to pressed in, if it needs to be held down, or if it needs to be tapped.
For example, tap-only combos are useful if any (or all) of the underlying keys is a Mod-Tap or a Layer-Tap key. When you tap the combo, you get the combo result. When you press the combo and hold it down, the combo doesn't actually activate. Instead the keys are processed separately as if the combo wasn't even there.
In order to use these features, the following configuration options and functions need to be defined. Coming up with useful timings and configuration is left as an exercise for the reader.
| `COMBO_MUST_HOLD_PER_COMBO` | bool get_combo_must_hold(uint16_t index, combo_t \*combo) | Controls if a given combo should fire immediately on tap or if it needs to be held. (default: `false`) |
| `COMBO_MUST_TAP_PER_COMBO` | bool get_combo_must_tap(uint16_t index, combo_t \*combo) | Controls if a given combo should fire only if tapped within `COMBO_HOLD_TERM`. (default: `false`) |
// If you want all combos to be tap-only, just uncomment the next line
// return true
// If you want *all* combos, that have Mod-Tap/Layer-Tap/Momentary keys in its chord, to be tap-only, this is for you:
uint16_t key;
uint8_t idx = 0;
while ((key = pgm_read_word(&combo->keys[idx])) != COMBO_END) {
switch (key) {
case QK_MOD_TAP...QK_MOD_TAP_MAX:
case QK_LAYER_TAP...QK_LAYER_TAP_MAX:
case QK_MOMENTARY...QK_MOMENTARY_MAX:
return true;
}
idx += 1;
}
return false;
}
```
## Variable Length Combos
If you leave `COMBO_COUNT` undefined in `config.h`, it allows you to programmatically declare the size of the Combo data structure and avoid updating `COMBO_COUNT`. Instead a variable called `COMBO_LEN` has to be set. It can be set with something similar to the following in `keymap.c`: `uint16_t COMBO_LEN = sizeof(key_combos) / sizeof(key_combos[0]);` or by adding `COMBO_LENGTH` as the *last* entry in the combo enum and then `uint16_t COMBO_LEN = COMBO_LENGTH;` as such:
```c
enum myCombos {
...,
COMBO_LENGTH
};
uint16_t COMBO_LEN = COMBO_LENGTH;
```
Regardless of the method used to declare `COMBO_LEN`, this also requires to convert the `combo_t key_combos[COMBO_COUNT] = {...};` line to `combo_t key_combos[] = {...};`.
## Combo timer
Normally, the timer is started on the first key press and then reset on every subsequent key press within the `COMBO_TERM`.
Inputting combos is relaxed like this, but also slightly more prone to accidental misfires.
The next two options alter the behaviour of the timer.
### `#define COMBO_STRICT_TIMER`
With `COMBO_STRICT_TIMER`, the timer is started only on the first key press.
Inputting combos is now less relaxed; you need to make sure the full chord is pressed within the `COMBO_TERM`.
Misfires are less common but if you type multiple combos fast, there is a
chance that the latter ones might not activate properly.
### `#define COMBO_NO_TIMER`
By defining `COMBO_NO_TIMER`, the timer is disabled completely and combos are activated on the first key release.
This also disables the "must hold" functionalities as they just wouldn't work at all.
## Customizable key releases
By defining `COMBO_PROCESS_KEY_RELEASE` and implementing the function `bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode)`, you can run your custom code on each key release after a combo was activated. For example you could change the RGB colors, activate haptics, or alter the modifiers.
You can also release a combo early by returning `true` from the function.
Here's an example where a combo resolves to two modifiers, and on key releases the modifiers are unregistered one by one, depending on which key was released.
If you, for example, use multiple base layers for different key layouts, one for QWERTY, and another one for Colemak, you might want your combos to work from the same key positions on all layers. Defining the same combos again for another layout is redundant and takes more memory. The solution is to just check the keycodes from one layer.
With `#define COMBO_ONLY_FROM_LAYER _LAYER_A` the combos' keys are always checked from layer `_LAYER_A` even though the active layer would be `_LAYER_B`.
## User callbacks
In addition to the keycodes, there are a few functions that you can use to set the status, or check it:
@ -101,3 +302,28 @@ In addition to the keycodes, there are a few functions that you can use to set t
| `combo_disable()` | Disables the combo feature, and clears the combo buffer |
| `combo_toggle()` | Toggles the state of the combo feature |
| `is_combo_enabled()` | Returns the status of the combo feature state (true or false) |
# Dictionary Management
Having 3 places to update when adding new combos or altering old ones does become cumbersome when you have a lot of combos. We can alleviate this with some magic! ... If you consider C macros magic.
First, you need to add `VPATH += keyboards/gboards` to your `rules.mk`. Next, include the file `g/keymap_combo.h` in your `keymap.c`.
!> This functionality uses the same `process_combo_event` function as `COMBO_ACTION` macros do, so you cannot use the function yourself in your keymap. Instead, you have to define the `case`s of the `switch` statement by themselves within `inject.h`, which `g/keymap_combo.h` will then include into the function.
Then, write your combos in `combos.def` file in the following manner:
```c
// name result chord keys
COMB(AB_ESC, KC_ESC, KC_A, KC_B)
COMB(JK_TAB, KC_TAB, KC_J, KC_K)
COMB(JKL_SPC, KC_SPC, KC_J, KC_K, KC_L)
COMB(BSSL_CLR, KC_NO, KC_BSPC, KC_LSFT) // using KC_NO as the resulting keycode is the same as COMBO_ACTION before.
COMB(QW_UNDO, C(KC_Z), KC_Q, KC_W)
SUBS(TH_THE, "the", KC_T, KC_H) // SUBS uses SEND_STRING to output the given string.
...
```
Now, you can update only one place to add or alter combos. You don't even need to remember to update the `COMBO_COUNT` or the `COMBO_LEN` variables at all. Everything is taken care of. Magic!
For small to huge ready made dictionaries of combos, you can check out http://combos.gboards.ca/.
Pete Sevander
2 years ago
GitHub