From 9254f8c612c891a6ee297a62db5f32f3603f4f45 Mon Sep 17 00:00:00 2001
From: Ryan <fauxpark@gmail.com>
Date: Wed, 17 Feb 2021 07:26:52 +1100
Subject: [PATCH] Add `tap_code_delay(code, delay)` (#11913)

Co-authored-by: Drashna Jaelre <drashna@live.com>
---
 docs/feature_macros.md   | 10 ++++++++--
 tmk_core/common/action.c | 21 +++++++++++++--------
 tmk_core/common/action.h |  1 +
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/docs/feature_macros.md b/docs/feature_macros.md
index aa1ebc337a0c..6e69ad642cf1 100644
--- a/docs/feature_macros.md
+++ b/docs/feature_macros.md
@@ -233,9 +233,15 @@ Parallel to `register_code` function, this sends the `<kc>` keyup event to the c
 
 ### `tap_code(<kc>);`
 
-This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
+Sends `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
 
-If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
+If `TAP_CODE_DELAY` is defined (default 0), this function waits that many milliseconds before calling `unregister_code(<kc>)`. This can be useful when you are having issues with taps (un)registering.
+
+If the keycode is `KC_CAPS`, it waits `TAP_HOLD_CAPS_DELAY` milliseconds instead (default 80), as macOS prevents accidental Caps Lock activation by waiting for the key to be held for a certain amount of time.
+
+### `tap_code_delay(<kc>, <delay>);`
+
+Like `tap_code(<kc>)`, but with a `delay` parameter for specifying arbitrary intervals before sending the unregister event.
 
 ### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
 
diff --git a/tmk_core/common/action.c b/tmk_core/common/action.c
index e4a97e0bc1ae..74bfc06264a5 100644
--- a/tmk_core/common/action.c
+++ b/tmk_core/common/action.c
@@ -940,20 +940,25 @@ void unregister_code(uint8_t code) {
 #endif
 }
 
-/** \brief Utilities for actions. (FIXME: Needs better description)
+/** \brief Tap a keycode with a delay.
  *
- * FIXME: Needs documentation.
+ * \param code The basic keycode to tap.
+ * \param delay The amount of time in milliseconds to leave the keycode registered, before unregistering it.
  */
-void tap_code(uint8_t code) {
+void tap_code_delay(uint8_t code, uint16_t delay) {
     register_code(code);
-    if (code == KC_CAPS) {
-        wait_ms(TAP_HOLD_CAPS_DELAY);
-    } else {
-        wait_ms(TAP_CODE_DELAY);
-    }
+    wait_ms(delay);
     unregister_code(code);
 }
 
+/** \brief Tap a keycode with the default delay.
+ *
+ * \param code The basic keycode to tap. If `code` is `KC_CAPS`, the delay will be `TAP_HOLD_CAPS_DELAY`, otherwise `TAP_CODE_DELAY`, if defined.
+ */
+void tap_code(uint8_t code) {
+    tap_code_delay(code, code == KC_CAPS ? TAP_HOLD_CAPS_DELAY : TAP_CODE_DELAY);
+}
+
 /** \brief Adds the given physically pressed modifiers and sends a keyboard report immediately.
  *
  * \param mods A bitfield of modifiers to register.
diff --git a/tmk_core/common/action.h b/tmk_core/common/action.h
index 81cd54369c0b..9a991de1c2ba 100644
--- a/tmk_core/common/action.h
+++ b/tmk_core/common/action.h
@@ -100,6 +100,7 @@ void process_action(keyrecord_t *record, action_t action);
 void register_code(uint8_t code);
 void unregister_code(uint8_t code);
 void tap_code(uint8_t code);
+void tap_code_delay(uint8_t code, uint16_t delay);
 void register_mods(uint8_t mods);
 void unregister_mods(uint8_t mods);
 void register_weak_mods(uint8_t mods);