Add One Shot Key callbacks (#4697)

* 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

2 files changed, 84 insertions, 15 deletions

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);