Add One Shot Key callbacks (#4697)0.6.269

* Added callbacks to one shot modifier changes

* Altered signature of callback functions

* Reordered the callback methods, shortened brief documentation

* Added One Shot Modifier callback documentation

* First attempt at unit tests

* Revert "First attempt at unit tests"

This reverts commit 5ec21a782202c0d74cf21cb852bd319f0c8b4842.

* Simplified oneshot function implementations

* Made clear_oneshot_locked_mods to be conform action_util.h, adhering to the (void) signature

* Made used datatypes for oneshot mods consistently unsigned integers

* Corrected callback to call clear callback when clear_oneshot_locked_mods is invoked

* Simplified oneshot equals statements

* Corrected return type and signature of get and set oneshot locked mods

* Consolidated one shot callbacks, added initial layer callback version

* Fixed non-updating one shot layer variable after timeout or other clear, added code comments

* Added better one shot key docs

3 files changed, 159 insertions, 15 deletions

diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md
index 37a3d43fc3..d23cb31d9a 100644
--- a/docs/feature_advanced_keycodes.md
+++ b/docs/feature_advanced_keycodes.md
@@ -161,6 +161,81 @@ For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear
 
 !> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
 
+## Callbacks
+
+When you'd like to perform custom logic when pressing a one shot key, there are several callbacks you can choose to implement. You could indicate changes in one shot keys by flashing an LED or making a sound, for example.
+
+There is a callback for `OSM(mod)`. It is called whenever the state of any one shot modifier key is changed: when it toggles on, but also when it is toggled off. You can use it like this:
+
+```c
+void oneshot_mods_changed_user(uint8_t mods) {
+  if (mods & MOD_MASK_SHIFT) {
+    println("Oneshot mods SHIFT");
+  }
+  if (mods & MOD_MASK_CTRL) {
+    println("Oneshot mods CTRL");
+  }
+  if (mods & MOD_MASK_ALT) {
+    println("Oneshot mods ALT");
+  }
+  if (mods & MOD_MASK_GUI) {
+    println("Oneshot mods GUI");
+  }
+  if (!mods) {
+    println("Oneshot mods off");
+  }
+}
+```
+
+The `mods` argument contains the active mods after the change, so it reflects the current state.
+
+When you use One Shot Tap Toggle (by adding `#define ONESHOT_TAP_TOGGLE 2` in your `config.h` file), you may lock a modifier key by pressing it the specified amount of times. There's a callback for that, too:
+
+```c
+void oneshot_locked_mods_changed_user(uint8_t mods) {
+  if (mods & MOD_MASK_SHIFT) {
+    println("Oneshot locked mods SHIFT");
+  }
+  if (mods & MOD_MASK_CTRL) {
+    println("Oneshot locked mods CTRL");
+  }
+  if (mods & MOD_MASK_ALT) {
+    println("Oneshot locked mods ALT");
+  }
+  if (mods & MOD_MASK_GUI) {
+    println("Oneshot locked mods GUI");
+  }
+  if (!mods) {
+    println("Oneshot locked mods off");
+  }
+}
+```
+
+Last, there is also a callback for the `OSL(layer)` one shot key:
+
+```c
+void oneshot_layer_changed_user(uint8_t layer) {
+  if (layer == 1) {
+    println("Oneshot layer 1 on");
+  }
+  if (!layer) {
+    println("Oneshot layer off");
+  }
+}
+```
+
+If any one shot layer is switched off, `layer` will be zero. When you're looking to do something on any layer change instead of one shot layer changes, `layer_state_set_user` is a better callback to use.
+
+If you are making your own keyboard, there are also `_kb` equivalent functions:
+
+```c
+void oneshot_locked_mods_changed_kb(uint8_t mods);
+void oneshot_mods_changed_kb(uint8_t mods);
+void oneshot_layer_changed_kb(uint8_t layer);
+```
+
+As with any callback, be sure to call the `_user` variant to allow for further customizability.
+
 # Tap-Hold Configuration Options
 
 While Tap-Hold options are fantastic, they are not without their issues.  We have tried to configure them with reasonal defaults, but that may still cause issues for some people. 
diff --git a/tmk_core/common/action_util.c b/tmk_core/common/action_util.c
index 58401ace55..365ed6a1dd 100644
--- a/tmk_core/common/action_util.c
+++ b/tmk_core/common/action_util.c
@@ -48,11 +48,21 @@ extern inline void del_key(uint8_t key);
 extern inline void clear_keys(void);
 
 #ifndef NO_ACTION_ONESHOT
-static int8_t oneshot_mods = 0;
-static int8_t oneshot_locked_mods = 0;
-int8_t get_oneshot_locked_mods(void) { return oneshot_locked_mods; }
-void set_oneshot_locked_mods(int8_t mods) { oneshot_locked_mods = mods; }
-void clear_oneshot_locked_mods(void) { oneshot_locked_mods = 0; }
+static uint8_t oneshot_mods = 0;
+static uint8_t oneshot_locked_mods = 0;
+uint8_t get_oneshot_locked_mods(void) { return oneshot_locked_mods; }
+void set_oneshot_locked_mods(uint8_t mods) {
+    if (mods != oneshot_locked_mods) {
+        oneshot_locked_mods = mods;
+        oneshot_locked_mods_changed_kb(oneshot_locked_mods);
+    }
+}
+void clear_oneshot_locked_mods(void) {
+    if (oneshot_locked_mods) {
+        oneshot_locked_mods = 0;
+        oneshot_locked_mods_changed_kb(oneshot_locked_mods);
+    }
+}
 #if (defined(ONESHOT_TIMEOUT) && (ONESHOT_TIMEOUT > 0))
 static uint16_t oneshot_time = 0;
 bool has_oneshot_mods_timed_out(void) {
@@ -97,6 +107,7 @@ void set_oneshot_layer(uint8_t layer, uint8_t state)
 #if (defined(ONESHOT_TIMEOUT) && (ONESHOT_TIMEOUT > 0))
     oneshot_layer_time = timer_read();
 #endif
+    oneshot_layer_changed_kb(get_oneshot_layer());
 }
 /** \brief Reset oneshot layer 
  *
@@ -107,6 +118,7 @@ void reset_oneshot_layer(void) {
 #if (defined(ONESHOT_TIMEOUT) && (ONESHOT_TIMEOUT > 0))
     oneshot_layer_time = 0;
 #endif
+    oneshot_layer_changed_kb(get_oneshot_layer());
 }
 /** \brief Clear oneshot layer 
  *
@@ -118,9 +130,7 @@ void clear_oneshot_layer_state(oneshot_fullfillment_t state)
     oneshot_layer_data &= ~state;
     if (!get_oneshot_layer_state() && start_state != oneshot_layer_data) {
         layer_off(get_oneshot_layer());
-#if (defined(ONESHOT_TIMEOUT) && (ONESHOT_TIMEOUT > 0))
-    oneshot_layer_time = 0;
-#endif
+        reset_oneshot_layer();
     }
 }
 /** \brief Is oneshot layer active
@@ -243,23 +253,27 @@ void clear_macro_mods(void) { macro_mods = 0; }
  *
  * FIXME: needs doc
  */
-void set_oneshot_mods(uint8_t mods)
-{
-    oneshot_mods = mods;
+void set_oneshot_mods(uint8_t mods) {
+  if (oneshot_mods != mods) {
 #if (defined(ONESHOT_TIMEOUT) && (ONESHOT_TIMEOUT > 0))
     oneshot_time = timer_read();
 #endif
+    oneshot_mods = mods;
+    oneshot_mods_changed_kb(mods);
+  }
 }
 /** \brief clear oneshot mods
  *
  * FIXME: needs doc
  */
-void clear_oneshot_mods(void)
-{
+void clear_oneshot_mods(void) {
+  if (oneshot_mods) {
     oneshot_mods = 0;
 #if (defined(ONESHOT_TIMEOUT) && (ONESHOT_TIMEOUT > 0))
     oneshot_time = 0;
 #endif
+    oneshot_mods_changed_kb(oneshot_mods);
+  }
 }
 /** \brief get oneshot mods
  *
@@ -271,6 +285,54 @@ uint8_t get_oneshot_mods(void)
 }
 #endif
 
+/** \brief Called when the one shot modifiers have been changed.
+ * 
+ * \param mods Contains the active modifiers active after the change. 
+ */
+__attribute__((weak))
+void oneshot_locked_mods_changed_user(uint8_t mods) { }
+
+/** \brief Called when the locked one shot modifiers have been changed.
+ * 
+ * \param mods Contains the active modifiers active after the change. 
+ */
+__attribute__((weak))
+void oneshot_locked_mods_changed_kb(uint8_t mods) {
+    oneshot_locked_mods_changed_user(mods);
+}
+
+/** \brief Called when the one shot modifiers have been changed.
+ * 
+ * \param mods Contains the active modifiers active after the change.
+ */
+__attribute__((weak))
+void oneshot_mods_changed_user(uint8_t mods) { }
+
+/** \brief Called when the one shot modifiers have been changed.
+ * 
+ * \param mods Contains the active modifiers active after the change.
+ */
+__attribute__((weak))
+void oneshot_mods_changed_kb(uint8_t mods) {
+    oneshot_mods_changed_user(mods);
+}
+
+/** \brief Called when the one shot layers have been changed.
+ * 
+ * \param layer Contains the layer that is toggled on, or zero when toggled off. 
+ */
+__attribute__((weak))
+void oneshot_layer_changed_user(uint8_t layer) { }
+
+/** \brief Called when the one shot layers have been changed.
+ * 
+ * \param layer Contains the layer that is toggled on, or zero when toggled off.
+ */
+__attribute__((weak))
+void oneshot_layer_changed_kb(uint8_t layer) {
+    oneshot_layer_changed_user(layer);
+}
+
 /** \brief inspect keyboard state
  *
  * FIXME: needs doc
diff --git a/tmk_core/common/action_util.h b/tmk_core/common/action_util.h
index 3458931514..d03f5682a3 100644
--- a/tmk_core/common/action_util.h
+++ b/tmk_core/common/action_util.h
@@ -71,8 +71,8 @@ void oneshot_enable(void);
 void oneshot_disable(void);
 bool has_oneshot_mods_timed_out(void);
 
-int8_t get_oneshot_locked_mods(void);
-void set_oneshot_locked_mods(int8_t mods);
+uint8_t get_oneshot_locked_mods(void);
+void set_oneshot_locked_mods(uint8_t mods);
 void clear_oneshot_locked_mods(void);
 
 typedef enum {
@@ -89,6 +89,13 @@ bool is_oneshot_layer_active(void);
 uint8_t get_oneshot_layer_state(void);
 bool has_oneshot_layer_timed_out(void);
 
+void oneshot_locked_mods_changed_user(uint8_t mods);
+void oneshot_locked_mods_changed_kb(uint8_t mods);
+void oneshot_mods_changed_user(uint8_t mods);
+void oneshot_mods_changed_kb(uint8_t mods);
+void oneshot_layer_changed_user(uint8_t layer);
+void oneshot_layer_changed_kb(uint8_t layer);
+
 /* inspect */
 uint8_t has_anymod(void);