Add HOLD_ON_OTHER_KEY_PRESS option for dual-role keys (#9404)

* Add HOLD_ON_OTHER_KEY_PRESS option for dual-role keys

Implement an additional option for dual-role keys which converts the
dual-role key press into a hold action immediately when another key is
pressed (this is different from the existing PERMISSIVE_HOLD option,
which selects the hold action when another key is tapped (pressed and
then released) while the dual-role key is pressed).  The Mod-Tap keys
already behave in a similar way, unless the IGNORE_MOD_TAP_INTERRUPT
option is enabled (but with some additional delays); the added option
makes this behavior available for all other kinds of dual-role keys.

* [Docs] Update tap-hold docs for HOLD_ON_OTHER_KEY_PRESS

Document the newly added HOLD_ON_OTHER_KEY_PRESS option and update the
documentation for closely related options (PERMISSIVE_HOLD and
IGNORE_MOD_TAP_INTERRUPT).

Use Layer Tap instead of Mod Tap in examples for PERMISSIVE_HOLD and
HOLD_ON_OTHER_KEY_PRESS, because the effect of using these options with
Mod Tap keys is mostly invisible without IGNORE_MOD_TAP_INTERRUPT.

Add comments before return statements in sample implementations of
`get_ignore_mod_tap_interrupt()`, `get_hold_on_other_key_press()` and
`get_permissive_hold()`.

Thanks to @Erovia and @precondition for comments and suggestions to
improve the documentation.

1 files changed, 17 insertions, 0 deletions

diff --git a/tmk_core/common/action_tapping.c b/tmk_core/common/action_tapping.c
index 1701ae471..36839f9fa 100644
--- a/tmk_core/common/action_tapping.c
+++ b/tmk_core/common/action_tapping.c
@@ -40,6 +40,10 @@ __attribute__((weak)) bool get_tapping_force_hold(uint16_t keycode, keyrecord_t
 __attribute__((weak)) bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) { return false; }
 #    endif
 
+#    ifdef HOLD_ON_OTHER_KEY_PRESS_PER_KEY
+__attribute__((weak)) bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) { return false; }
+#    endif
+
 static keyrecord_t tapping_key                         = {};
 static keyrecord_t waiting_buffer[WAITING_BUFFER_SIZE] = {};
 static uint8_t     waiting_buffer_head                 = 0;
@@ -175,6 +179,19 @@ bool process_tapping(keyrecord_t *keyp) {
                     // set interrupted flag when other key preesed during tapping
                     if (event.pressed) {
                         tapping_key.tap.interrupted = true;
+#    if defined(HOLD_ON_OTHER_KEY_PRESS) || defined(HOLD_ON_OTHER_KEY_PRESS_PER_KEY)
+#        if defined(HOLD_ON_OTHER_KEY_PRESS_PER_KEY)
+                        if (get_hold_on_other_key_press(get_record_keycode(&tapping_key, false), keyp))
+#        endif
+                        {
+                            debug("Tapping: End. No tap. Interfered by pressed key\n");
+                            process_record(&tapping_key);
+                            tapping_key = (keyrecord_t){};
+                            debug_tapping_key();
+                            // enqueue
+                            return false;
+                        }
+#    endif
                     }
                     // enqueue
                     return false;