aboutsummaryrefslogtreecommitdiff
path: root/quantum/action_tapping.h
diff options
context:
space:
mode:
Diffstat (limited to 'quantum/action_tapping.h')
-rw-r--r--quantum/action_tapping.h125
1 files changed, 125 insertions, 0 deletions
diff --git a/quantum/action_tapping.h b/quantum/action_tapping.h
index 6b518b8298..0cf4aa1200 100644
--- a/quantum/action_tapping.h
+++ b/quantum/action_tapping.h
@@ -46,6 +46,131 @@ bool get_permissive_hold(uint16_t keycode, keyrecord_t *record);
bool get_retro_tapping(uint16_t keycode, keyrecord_t *record);
bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record);
+#ifdef CHORDAL_HOLD
+/**
+ * Callback to say when a key chord before the tapping term may be held.
+ *
+ * In keymap.c, define the callback
+ *
+ * bool get_chordal_hold(uint16_t tap_hold_keycode,
+ * keyrecord_t* tap_hold_record,
+ * uint16_t other_keycode,
+ * keyrecord_t* other_record) {
+ * // Conditions...
+ * }
+ *
+ * This callback is called when:
+ *
+ * 1. `tap_hold_keycode` is pressed.
+ * 2. `other_keycode` is pressed while `tap_hold_keycode` is still held,
+ * provided `other_keycode` is *not* also a tap-hold key and it is pressed
+ * before the tapping term.
+ *
+ * If false is returned, this has the effect of immediately settling the
+ * tap-hold key as tapped. If true is returned, the tap-hold key is still
+ * unsettled, and may be settled as held depending on configuration and
+ * subsequent events.
+ *
+ * @param tap_hold_keycode Keycode of the tap-hold key.
+ * @param tap_hold_record Record from the tap-hold press event.
+ * @param other_keycode Keycode of the other key.
+ * @param other_record Record from the other key's press event.
+ * @return True if the tap-hold key may be considered held; false if tapped.
+ */
+bool get_chordal_hold(uint16_t tap_hold_keycode, keyrecord_t *tap_hold_record, uint16_t other_keycode, keyrecord_t *other_record);
+
+/**
+ * Default "opposite hands rule" for whether a key chord may settle as held.
+ *
+ * This function returns true when the tap-hold key and other key are on
+ * "opposite hands." In detail, handedness of the two keys are compared. If
+ * handedness values differ, or if either handedness is '*', the function
+ * returns true, indicating that it may be held. Otherwise, it returns false,
+ * in which case the tap-hold key is immediately settled at tapped.
+ *
+ * @param tap_hold_record Record of the active tap-hold key press.
+ * @param other_record Record of the other, interrupting key press.
+ * @return True if the tap-hold key may be considered held; false if tapped.
+ */
+bool get_chordal_hold_default(keyrecord_t *tap_hold_record, keyrecord_t *other_record);
+
+/**
+ * Gets the handedness of a key.
+ *
+ * This function returns:
+ * 'L' for keys pressed by the left hand,
+ * 'R' for keys on the right hand,
+ * '*' for keys exempt from the "opposite hands rule." This could be used
+ * perhaps on thumb keys or keys that might be pressed by either hand.
+ *
+ * @param key A key matrix position.
+ * @return Handedness value.
+ */
+char chordal_hold_handedness(keypos_t key);
+
+extern const char chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS] PROGMEM;
+#endif
+
+#ifdef FLOW_TAP_TERM
+/**
+ * Callback to specify the keys where Flow Tap is enabled.
+ *
+ * Flow Tap 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, Flow Tap is enabled.
+ *
+ * The default implementation of this callback corresponds to
+ *
+ * bool is_flow_tap_key(uint16_t keycode) {
+ * switch (get_tap_keycode(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 Flow Tap for this key.
+ */
+bool is_flow_tap_key(uint16_t keycode);
+
+/**
+ * Callback to customize Flow Tap filtering.
+ *
+ * Flow Tap acts only when key events are closer together than this time.
+ *
+ * Return a time of 0 to disable filtering. In this way, Flow Tap may be
+ * disabled for certain tap-hold keys, or when following certain previous keys.
+ *
+ * The default implementation of this callback is
+ *
+ * uint16_t get_flow_tap_term(uint16_t keycode, keyrecord_t* record,
+ * uint16_t prev_keycode) {
+ * if (is_flow_tap_key(keycode) && is_flow_tap_key(prev_keycode)) {
+ * return g_flow_tap_term;
+ * }
+ * return 0;
+ * }
+ *
+ * NOTE: If both `is_flow_tap_key()` and `get_flow_tap_term()` are defined, then
+ * `get_flow_tap_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.
+ */
+uint16_t get_flow_tap_term(uint16_t keycode, keyrecord_t *record, uint16_t prev_keycode);
+
+/** Updates the Flow Tap last key and timer. */
+void flow_tap_update_last_event(keyrecord_t *record);
+#endif // FLOW_TAP_TERM
+
#ifdef DYNAMIC_TAPPING_TERM_ENABLE
extern uint16_t g_tapping_term;
#endif