diff --git a/modules/getreuer/tap_flow/README.md b/modules/getreuer/tap_flow/README.md index 41d65ac..cbd0217 100644 --- a/modules/getreuer/tap_flow/README.md +++ b/modules/getreuer/tap_flow/README.md @@ -2,7 +2,7 @@ - +
Modulegetreuer/tap_flow
Version2025-03-19
Version2025-04-08
MaintainerPascal Getreuer (@getreuer)
LicenseApache 2.0
Documentation @@ -39,8 +39,9 @@ Tap Flow's default behavior is: * Filtering is done only when both the tap-hold key and the previous key are among Space, letters A–Z, and - punctuations , . ; /. Define the - `get_tap_flow()` callback to customize this logic. + punctuations , . ; /. + +Define the `is_tap_flow_key()` or `get_tap_flow_term()` callbacks to customize. Tap Flow modifies the tap-hold decision such that when a tap-hold key is pressed within a short timeout of the preceding key, the tapping function is used. The @@ -49,9 +50,10 @@ desired (though perhaps with an exception for Shift or AltGr, noted below), whereas the hold functions (mods and layers) are used in isolation, or at least with a brief pause preceding the tap-hold key press. -Optionally, the feature can be customized with the `get_tap_flow()` callback. In -this way, exceptions may be made for Shift and AltGr (or whatever you wish) to -use a shorter time or to disable filtering for those keys entirely. +Optionally, the feature can be customized with the `is_tap_flow_key()` and +`get_tap_flow_term()` callbacks. In this way, exceptions may be made for Shift +and AltGr (or whatever you wish) to use a shorter time or to disable filtering +for those keys entirely. For full documentation, see diff --git a/modules/getreuer/tap_flow/tap_flow.c b/modules/getreuer/tap_flow/tap_flow.c index b7ca577..cbef9b6 100644 --- a/modules/getreuer/tap_flow/tap_flow.c +++ b/modules/getreuer/tap_flow/tap_flow.c @@ -183,8 +183,8 @@ bool process_record_tap_flow(uint16_t keycode, keyrecord_t* record) { return true; } -// Keycode is a "typing" key: Space, A-Z, or main alphas area punctuation. -static bool is_typing(uint16_t keycode) { +// By default, enable Tap Flow for Space, A-Z, or main alphas area punctuation. +__attribute__((weak)) bool is_tap_flow_key(uint16_t keycode) { switch (get_tap_keycode(keycode)) { case KC_SPC: case KC_A ... KC_Z: @@ -197,15 +197,19 @@ static bool is_typing(uint16_t keycode) { return false; } -// By default, enable filtering when both the tap-hold key and previous key are -// typing keys, and use the quick tap term. +__attribute__((weak)) uint16_t get_tap_flow_term( + uint16_t keycode, keyrecord_t* record, uint16_t prev_keycode) { + return get_tap_flow(keycode, record, prev_keycode); +} + +// By default, enable filtering when both the tap-hold key and previous key +// return true for `is_tap_flow_key()`. __attribute__((weak)) uint16_t get_tap_flow( uint16_t keycode, keyrecord_t* record, uint16_t prev_keycode) { - if (!is_typing(keycode) || !is_typing(prev_keycode)) { - return 0; + if (is_tap_flow_key(keycode) && is_tap_flow_key(prev_keycode)) { + return g_tap_flow_term; } - - return g_tap_flow_term; + return 0; // Disable Tap Flow. } #endif // !defined(COMBO_ENABLE) && !defined(REPEAT_KEY_ENABLE) diff --git a/modules/getreuer/tap_flow/tap_flow.h b/modules/getreuer/tap_flow/tap_flow.h index 0a5606a..2a2ddfe 100644 --- a/modules/getreuer/tap_flow/tap_flow.h +++ b/modules/getreuer/tap_flow/tap_flow.h @@ -48,6 +48,41 @@ extern "C" { # define TAP_FLOW_TERM 150 #endif // TAP_FLOW_TERM +/** + * Optional callback to customize where Tap Flow is enabled. + * + * Tap Flow is constrained to certain keys by the following rule: this callback + * is called for both the tap-hold key *and* the key press immediately preceding + * it. If the callback returns true for both keycodes, Tap Flow may apply. + * + * The default implementation of this callback corresponds to + * + * bool is_tap_flow_key(uint16_t keycode) { + * switch (keycode) { + * case QK_MOD_TAP ... QK_MOD_TAP_MAX: + * keycode = QK_MOD_TAP_GET_TAP_KEYCODE(keycode); + * break; + * case QK_LAYER_TAP ... QK_LAYER_TAP_MAX: + * keycode = QK_LAYER_TAP_GET_TAP_KEYCODE(keycode); + * break; + * } + * switch (keycode) { + * case KC_SPC: + * case KC_A ... KC_Z: + * case KC_DOT: + * case KC_COMM: + * case KC_SCLN: + * case KC_SLSH: + * return true; + * } + * return false; + * } + * + * @param keycode Keycode of the key. + * @return Whether to enable Tap Flow for this key. + */ +bool is_tap_flow_key(uint16_t keycode); + /** * Optional callback to customize filtering. * @@ -56,11 +91,28 @@ extern "C" { * Return a time of 0 to disable filtering. In this way, Tap Flow may be * disabled for certain tap-hold keys, or when following certain previous keys. * + * The default implementation of this callback is + * + * uint16_t get_tap_flow_term(uint16_t keycode, keyrecord_t* record, + * uint16_t prev_keycode) { + * if (is_tap_flow_key(keycode) && is_tap_flow_key(prev_keycode)) { + * return g_tap_flow_term; + * } + * return 0; + * } + * + * NOTE: If both `is_tap_flow_key()` and `get_tap_flow_term()` are defined, then + * `get_tap_flow_term()` takes precedence. + * * @param keycode Keycode of the tap-hold key. * @param record keyrecord_t of the tap-hold event. * @param prev_keycode Keycode of the previously pressed key. - * @return Time in milliseconds. + * @return Timeout in milliseconds. */ +uint16_t get_tap_flow_term(uint16_t keycode, keyrecord_t* record, + uint16_t prev_keycode); + +/** @deprecated Use `get_tap_flow_term()` instead. */ uint16_t get_tap_flow(uint16_t keycode, keyrecord_t* record, uint16_t prev_keycode);