New feature: `DYNAMIC_TAPPING_TERM_ENABLE` (#11036)

* New feature: `DYNAMIC_TAPPING_TERM_ENABLE`

3 new quantum keys to configure the tapping term on the fly.

* Replace sprintf call in tapping_term_report by get_u16_str

* Replace tab with 4 spaces
master
precondition 2021-11-25 20:06:50 +00:00 committed by GitHub
parent 5e9c29da0d
commit 4bac5f53d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 191 additions and 4 deletions

View File

@ -36,6 +36,7 @@ GENERIC_FEATURES = \
TAP_DANCE \ TAP_DANCE \
VELOCIKEY \ VELOCIKEY \
WPM \ WPM \
DYNAMIC_TAPPING_TERM \
define HANDLE_GENERIC_FEATURE define HANDLE_GENERIC_FEATURE
# $$(info "Processing: $1_ENABLE $2.c") # $$(info "Processing: $1_ENABLE $2.c")

View File

@ -39,6 +39,7 @@ OTHER_OPTION_NAMES = \
UNICODE_COMMON \ UNICODE_COMMON \
AUTO_SHIFT_ENABLE \ AUTO_SHIFT_ENABLE \
AUTO_SHIFT_MODIFIERS \ AUTO_SHIFT_MODIFIERS \
DYNAMIC_TAPPING_TERM_ENABLE \
COMBO_ENABLE \ COMBO_ENABLE \
KEY_LOCK_ENABLE \ KEY_LOCK_ENABLE \
KEY_OVERRIDE_ENABLE \ KEY_OVERRIDE_ENABLE \

View File

@ -448,6 +448,8 @@ Use these to enable or disable building certain features. The more you have enab
* Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master. * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
* `DEFERRED_EXEC_ENABLE` * `DEFERRED_EXEC_ENABLE`
* Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information. * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information.
* `DYNAMIC_TAPPING_TERM_ENABLE`
* Allows to configure the global tapping term on the fly.
## USB Endpoint Limitations ## USB Endpoint Limitations

View File

@ -586,6 +586,16 @@ See also: [Mod-Tap](mod_tap.md)
|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped | |`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped |
|`HYPR_T(kc)` |`ALL_T(kc)` |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| |`HYPR_T(kc)` |`ALL_T(kc)` |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
## Tapping Term Keys :id=tapping-term-keys
See also: [Dynamic Tapping Term](tap_hold#dynamic-tapping-term)
| Key | Description |
|-------------|------------------------------------------------------------------------------------------------------------------------|
| `DT_PRNT` | "Dynamic Tapping Term Print": Types the current tapping term, in milliseconds |
| `DT_UP` | "Dynamic Tapping Term Up": Increases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) |
| `DT_DOWN` | "Dynamic Tapping Term Down": Decreases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) |
## RGB Lighting :id=rgb-lighting ## RGB Lighting :id=rgb-lighting
See also: [RGB Lighting](feature_rgblight.md) See also: [RGB Lighting](feature_rgblight.md)

View File

@ -6,7 +6,9 @@ These options let you modify the behavior of the Tap-Hold keys.
## Tapping Term ## Tapping Term
The crux of all of the following features is the tapping term setting. This determines what is a tap and what is a hold. And the exact timing for this to feel natural can vary from keyboard to keyboard, from switch to switch, and from key to key. The crux of all of the following features is the tapping term setting. This determines what is a tap and what is a hold. The exact timing for this to feel natural can vary from keyboard to keyboard, from switch to switch, and from key to key.
?> `DYNAMIC_TAPPING_TERM_ENABLE` enables three special keys that can help you quickly find a comfortable tapping term for you. See "Dynamic Tapping Term" for more details.
You can set the global time for this by adding the following setting to your `config.h`: You can set the global time for this by adding the following setting to your `config.h`:
@ -36,6 +38,82 @@ uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
} }
``` ```
### Dynamic Tapping Term :id=dynamic-tapping-term
`DYNAMIC_TAPPING_TERM_ENABLE` is a feature you can enable in `rules.mk` that lets you use three special keys in your keymap to configure the tapping term on the fly.
| Key | Description |
|-------------|------------------------------------------------------------------------------------------------------------------------|
| `DT_PRNT` | "Dynamic Tapping Term Print": Types the current tapping term, in milliseconds |
| `DT_UP` | "Dynamic Tapping Term Up": Increases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) |
| `DT_DOWN` | "Dynamic Tapping Term Down": Decreases the current tapping term by `DYNAMIC_TAPPING_TERM_INCREMENT`ms (5ms by default) |
Set the tapping term as usual with `#define TAPPING_TERM <value>` in `config.h` and add `DYNAMIC_TAPPING_TERM_ENABLE = yes` in `rules.mk`. Then, place the above three keys somewhere in your keymap and flash the new firmware onto your board.
Now, you can try using your dual-role keys, such as layer-taps and mod-taps, and use `DT_DOWN` and `DT_UP` to adjust the tapping term immediately. If you find that you frequently trigger the modifier of your mod-tap(s) by accident for example, that's a sign that your tapping term may be too low so tap `DT_UP` a few times to increase the tapping term until that no longer happens. On the flip side, if you get superfluous characters when you actually intended to momentarily activate a layer, tap `DT_DOWN` to lower the tapping term. Do note that these keys affect the *global* tapping term, you cannot change the tapping term of a specific key on the fly.
Once you're satisfied with the current tapping term value, open `config.h` and replace whatever value you first wrote for the tapping term by the output of the `DT_PRNT` key.
It's important to update `TAPPING_TERM` with the new value because the adjustments made using `DT_UP` and `DT_DOWN` are not persistent.
The value by which the tapping term increases or decreases when you tap `DT_UP` and `DT_DOWN` can be configured in `config.h` with `#define DYNAMIC_TAPPING_TERM_INCREMENT <new value>`. Note that the tapping term is *not* modified when holding down the tap term keys so if you need to, for example, decrease the current tapping term by 50ms, you cannot just press down and hold `DT_DOWN`; you will have to tap it 10 times in a row with the default increment of 5ms.
If you need more flexibility, nothing prevents you from defining your own custom keys to dynamically change the tapping term.
```c
enum custom_dynamic_tapping_term_keys = {
DT_UP_50 = SAFE_RANGE,
DT_DOWN_50,
DT_UP_X2,
DT_DOWN_X2,
}
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case DT_UP_50:
if (record->event.pressed) {
g_tapping_term += 50;
}
break;
case DT_DOWN_50:
if (record->event.pressed) {
g_tapping_term -= 50;
}
break;
case DT_UP_X2:
if (record->event.pressed) {
g_tapping_term *= 2;
}
break;
case DT_DOWN_X2:
if (record->event.pressed) {
g_tapping_term /= 2;
}
break;
}
return true;
};
```
In order for this feature to be effective if you use per-key tapping terms, you need to make a few changes to the syntax of the `get_tapping_term` function. All you need to do is replace every occurrence of `TAPPING_TERM` in the `get_tapping_term` function by lowercase `g_tapping_term`. If you don't do that, you will still see the value typed by `DT_PRNT` go up and down as you configure the tapping term on the fly but you won't feel those changes as they don't get applied. If you can go as low as 10ms and still easily trigger the tap function of a dual-role key, that's a sign that you forgot to make the necessary changes to your `get_tapping_term` function.
For instance, here's how the example `get_tapping_term` shown earlier should look like after the transformation:
```c
uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case SFT_T(KC_SPC):
return g_tapping_term + 1250;
case LT(1, KC_GRV):
return 130;
default:
return g_tapping_term;
}
}
```
The reason being that `TAPPING_TERM` is a macro that expands to a constant integer and thus cannot be changed at runtime whereas `g_tapping_term` is a variable whose value can be changed at runtime. If you want, you can temporarily enable `DYNAMIC_TAPPING_TERM_ENABLE` to find a suitable tapping term value and then disable that feature and revert back to using the classic syntax for per-key tapping term settings.
## Tap-Or-Hold Decision Modes ## Tap-Or-Hold Decision Modes
The code which decides between the tap and hold actions of dual-role keys supports three different modes, in increasing order of preference for the hold action: The code which decides between the tap and hold actions of dual-role keys supports three different modes, in increasing order of preference for the hold action:

View File

@ -157,6 +157,7 @@ The `process_record()` function itself is deceptively simple, but hidden within
* [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_combo.c#L115) * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_combo.c#L115)
* [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77) * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77)
* [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94) * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94)
* `bool process_dynamic_tapping_term(uint16_t keycode, keyrecord_t *record)`
* [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_terminal.c#L264) * [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_terminal.c#L264)
* [Identify and process Quantum-specific keycodes](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291) * [Identify and process Quantum-specific keycodes](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291)

View File

@ -24,12 +24,14 @@
# define IS_TAPPING_RECORD(r) (IS_TAPPING() && KEYEQ(tapping_key.event.key, (r->event.key)) && tapping_key.keycode == r->keycode) # define IS_TAPPING_RECORD(r) (IS_TAPPING() && KEYEQ(tapping_key.event.key, (r->event.key)) && tapping_key.keycode == r->keycode)
# endif # endif
__attribute__((weak)) uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { return TAPPING_TERM; } uint16_t g_tapping_term = TAPPING_TERM;
__attribute__((weak)) uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { return g_tapping_term; }
# ifdef TAPPING_TERM_PER_KEY # ifdef TAPPING_TERM_PER_KEY
# define WITHIN_TAPPING_TERM(e) (TIMER_DIFF_16(e.time, tapping_key.event.time) < get_tapping_term(get_record_keycode(&tapping_key, false), &tapping_key)) # define WITHIN_TAPPING_TERM(e) (TIMER_DIFF_16(e.time, tapping_key.event.time) < get_tapping_term(get_record_keycode(&tapping_key, false), &tapping_key))
# else # else
# define WITHIN_TAPPING_TERM(e) (TIMER_DIFF_16(e.time, tapping_key.event.time) < TAPPING_TERM) # define WITHIN_TAPPING_TERM(e) (TIMER_DIFF_16(e.time, tapping_key.event.time) < g_tapping_term)
# endif # endif
# ifdef TAPPING_FORCE_HOLD_PER_KEY # ifdef TAPPING_FORCE_HOLD_PER_KEY
@ -158,7 +160,7 @@ bool process_tapping(keyrecord_t *keyp) {
# ifdef TAPPING_TERM_PER_KEY # ifdef TAPPING_TERM_PER_KEY
get_tapping_term(tapping_keycode, keyp) get_tapping_term(tapping_keycode, keyp)
# else # else
TAPPING_TERM g_tapping_term
# endif # endif
>= 500 >= 500
) )

View File

@ -33,10 +33,14 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
uint16_t get_record_keycode(keyrecord_t *record, bool update_layer_cache); uint16_t get_record_keycode(keyrecord_t *record, bool update_layer_cache);
uint16_t get_event_keycode(keyevent_t event, bool update_layer_cache); uint16_t get_event_keycode(keyevent_t event, bool update_layer_cache);
void action_tapping_process(keyrecord_t record); void action_tapping_process(keyrecord_t record);
#endif
uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record); uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record);
bool get_permissive_hold(uint16_t keycode, keyrecord_t *record); bool get_permissive_hold(uint16_t keycode, keyrecord_t *record);
bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record); bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record);
bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record); bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record);
bool get_retro_tapping(uint16_t keycode, keyrecord_t *record); bool get_retro_tapping(uint16_t keycode, keyrecord_t *record);
#ifdef DYNAMIC_TAPPING_TERM_ENABLE
extern uint16_t g_tapping_term;
#endif #endif

View File

@ -0,0 +1,50 @@
/* Copyright 2020 Vladislav Kucheriavykh
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include "quantum.h"
#include "process_dynamic_tapping_term.h"
#ifndef DYNAMIC_TAPPING_TERM_INCREMENT
# define DYNAMIC_TAPPING_TERM_INCREMENT 5
#endif
static void tapping_term_report(void) {
const char *tapping_term_str = get_u16_str(g_tapping_term, ' ');
// Skip padding spaces
while (*tapping_term_str == ' ') {
tapping_term_str++;
}
send_string(tapping_term_str);
}
bool process_dynamic_tapping_term(uint16_t keycode, keyrecord_t *record) {
if (record->event.pressed) {
switch (keycode) {
case DT_PRNT:
tapping_term_report();
return false;
case DT_UP:
g_tapping_term += DYNAMIC_TAPPING_TERM_INCREMENT;
return false;
case DT_DOWN:
g_tapping_term -= DYNAMIC_TAPPING_TERM_INCREMENT;
return false;
}
}
return true;
}

View File

@ -0,0 +1,26 @@
/* Copyright 2020 Vladislav Kucheriavykh
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <stdbool.h>
#include "action.h"
#ifndef DYNAMIC_TAPPING_TERM_INCREMENT
# define DYNAMIC_TAPPING_TERM_INCREMENT 5
#endif
bool process_dynamic_tapping_term(uint16_t keycode, keyrecord_t *record);

View File

@ -275,6 +275,9 @@ bool process_record_quantum(keyrecord_t *record) {
#ifdef AUTO_SHIFT_ENABLE #ifdef AUTO_SHIFT_ENABLE
process_auto_shift(keycode, record) && process_auto_shift(keycode, record) &&
#endif #endif
#ifdef DYNAMIC_TAPPING_TERM_ENABLE
process_dynamic_tapping_term(keycode, record) &&
#endif
#ifdef TERMINAL_ENABLE #ifdef TERMINAL_ENABLE
process_terminal(keycode, record) && process_terminal(keycode, record) &&
#endif #endif

View File

@ -125,6 +125,10 @@ extern layer_state_t layer_state;
# include "process_auto_shift.h" # include "process_auto_shift.h"
#endif #endif
#ifdef DYNAMIC_TAPPING_TERM_ENABLE
# include "process_dynamic_tapping_term.h"
#endif
#ifdef COMBO_ENABLE #ifdef COMBO_ENABLE
# include "process_combo.h" # include "process_combo.h"
#endif #endif

View File

@ -524,6 +524,11 @@ enum quantum_keycodes {
// Additional magic key // Additional magic key
MAGIC_TOGGLE_GUI, MAGIC_TOGGLE_GUI,
// Adjust tapping term on the fly
DT_PRNT,
DT_UP,
DT_DOWN,
// Programmable Button // Programmable Button
PROGRAMMABLE_BUTTON_1, PROGRAMMABLE_BUTTON_1,
PROGRAMMABLE_BUTTON_2, PROGRAMMABLE_BUTTON_2,