Deprecate old OneShot functions and public member variables

Deprecates OneShot direct-access configuration variables, and replaces them with
setter functions:

- `time_out` => `setTimeout()`
- `hold_time_out` => `setHoldTimeout()`
- `double_tap_time_out` => `setDoubleTapTimeout()`

Deprecating public member variables is tricky, but possible. I've created new,
private member variables, and added code to keep them in sync with the
deprecated public ones for now.

Also of note: The old `OneShot.inject()` function should now be unnecessary for
most purposes. It still works, but has a potential undesirable side effect. It
now needs to pick a physical keyswitch address to use for the injected OneShot
key, and that key will not be usable for its normal value until that OneShot key
is deactivated. Because of this, use of `inject()` is not strongly discouraged.

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>

plugins/Kaleidoscope-OneShot/src/kaleidoscope/plugin/OneShot.cpp

@@ -27,6 +27,11 @@ namespace plugin {
 // ----------------------------------------------------------------------------
 // Configuration variables
 
+uint16_t OneShot::timeout_ = 2500;
+uint16_t OneShot::hold_timeout_ = 250;
+int16_t OneShot::double_tap_timeout_ = -1;
+
+// Deprecated
 uint16_t OneShot::time_out = 2500;
 uint16_t OneShot::hold_time_out = 250;
 int16_t OneShot::double_tap_time_out = -1;
@@ -215,7 +220,7 @@ EventHandlerResult OneShot::onKeyswitchEvent(
         temp_addrs_.clear(key_addr);
 
         // Derive the true double-tap timeout value if we're using the default.
-        uint16_t dtto = (double_tap_time_out < 0) ? time_out : double_tap_time_out;
+        uint16_t dtto = (double_tap_timeout_ < 0) ? timeout_ : double_tap_timeout_;
 
         // If the key is not stickable, or the double-tap timeout has
         // expired, clear the `glue` state, as well; this OneShot key
@@ -271,7 +276,7 @@ EventHandlerResult OneShot::onKeyswitchEvent(
       // This key is in the "pending" OneShot state. We need to check
       // its hold timeout, and turn it back into a normal key if it
       // has timed out.
-      if (hasTimedOut(hold_time_out)) {
+      if (hasTimedOut(hold_timeout_)) {
         temp_addrs_.clear(key_addr);
       }
     }
@@ -305,7 +310,7 @@ EventHandlerResult OneShot::afterEachCycle() {
   // gets set to 2 on the press of a normal key when there are any
   // active OneShot keys; that way, the OneShot keys will stay active
   // long enough to apply to the newly-pressed key.
-  if ((release_countdown_ == 1) || hasTimedOut(time_out)) {
+  if ((release_countdown_ == 1) || hasTimedOut(timeout_)) {
     for (KeyAddr key_addr : temp_addrs_) {
       if (glue_addrs_.read(key_addr)) {
         releaseKey(key_addr);
@@ -319,6 +324,14 @@ EventHandlerResult OneShot::afterEachCycle() {
   // for zero to avoid underflow.
   release_countdown_ >>= 1;
 
+  // Temporary fix for deprecated variables
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+  timeout_ = time_out;
+  hold_timeout_ = hold_time_out;
+  double_tap_timeout_ = double_tap_time_out;
+#pragma GCC diagnostic pop
+
   return EventHandlerResult::OK;
 }
 
@@ -387,6 +400,69 @@ void OneShot::releaseKey(KeyAddr key_addr) {
   handleKeyswitchEvent(Key_NoKey, key_addr, WAS_PRESSED | INJECTED);
 }
 
+// ------------------------------------------------------------------------------
+// Deprecated functions
+
+void OneShot::inject(Key key, uint8_t key_state) {
+  if (! isOneShotKey(key)) {
+    return;
+  }
+  // Find an idle keyswitch to use for the injected OneShot key and activate
+  // it. This is an ugly hack, but it will work. It does mean that whatever key
+  // is used will be unavailable for its normal function until the injected
+  // OneShot key is deactivated, so use of `inject()` is strongly discouraged.
+  for (KeyAddr key_addr : KeyAddr::all()) {
+    if (live_keys[key_addr] == Key_Transparent) {
+      pressKey(key_addr, key);
+      glue_addrs_.set(key_addr);
+      break;
+    }
+  }
+}
+
+bool OneShot::isModifierActive(Key key) {
+  // This actually works for any `Key` value, not just modifiers. Because we're
+  // just searching the keymap cache, it's also possible to return a false
+  // positive (a plugin might have altered the cache for an idle `KeyAddr`), or
+  // a false negative (a plugin might be inserting a modifier without a valid
+  // `KeyAddr`), but as this is a deprecated function, I think this is good
+  // enough.
+  for (KeyAddr key_addr : KeyAddr::all()) {
+    if (live_keys[key_addr] == key) {
+      return true;
+    }
+  }
+  return false;
+}
+
+bool OneShot::isActive(Key oneshot_key) {
+  if (! isOneShotKey(oneshot_key)) {
+    return false;
+  }
+  Key key = decodeOneShotKey(oneshot_key);
+  for (KeyAddr key_addr : glue_addrs_) {
+    if (live_keys[key_addr] == key) {
+      return true;
+    }
+  }
+  return false;
+}
+
+bool OneShot::isSticky(Key oneshot_key) {
+  if (! isOneShotKey(oneshot_key)) {
+    return false;
+  }
+  Key key = decodeOneShotKey(oneshot_key);
+  for (KeyAddr key_addr : glue_addrs_) {
+    if (live_keys[key_addr] == key &&
+        !temp_addrs_.read(key_addr)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+
 } // namespace plugin
 } // namespace kaleidoscope
 

plugins/Kaleidoscope-OneShot/src/kaleidoscope/plugin/OneShot.h

@@ -22,6 +22,38 @@
 #include "kaleidoscope/key_events.h"
 #include "kaleidoscope/KeyAddrBitfield.h"
 
+// ----------------------------------------------------------------------------
+// Deprecation warning messages
+#define _DEPRECATED_MESSAGE_ONESHOT_TIMEOUT                                     \
+  "The `OneShot.time_out` variable is deprecated. Please use the\n"             \
+  "`OneShot.setTimeout()` function instead."
+
+#define _DEPRECATED_MESSAGE_ONESHOT_HOLD_TIMEOUT                                \
+  "The `OneShot.hold_time_out` variable is deprecated. Please use the\n"        \
+  "`OneShot.setHoldTimeout()` function instead."
+
+#define _DEPRECATED_MESSAGE_ONESHOT_DOUBLE_TAP_TIMEOUT                          \
+  "The `OneShot.double_tap_time_out` variable is deprecated. Please use the\n"  \
+  "`OneShot.setDoubleTapTimeout()` function instead."
+
+#define _DEPRECATED_MESSAGE_ONESHOT_INJECT                                      \
+  "The `OneShot.inject(key, key_state)` function has been deprecated."
+
+#define _DEPRECATED_MESSAGE_ONESHOT_ISACTIVE_KEY                                \
+  "The `OneShot.isActive(key)` function is deprecated. Please use\n"            \
+  "`OneShot.isActive(key_addr)` instead, if possible."
+
+#define _DEPRECATED_MESSAGE_ONESHOT_ISSTICKY_KEY                                \
+  "The `OneShot.isSticky(key)` function is deprecated. Please use\n"            \
+  "`OneShot.isSticky(key_addr)` instead, if possible."
+
+#define _DEPRECATED_MESSAGE_ONESHOT_ISPRESSED                                   \
+  "The `OneShot.isPressed()` function is deprecated. This function now\n"       \
+  "always returns false."
+
+#define _DEPRECATED_MESSAGE_ONESHOT_ISMODIFIERACTIVE                            \
+  "The `OneShot.isModifierActive()` function is deprecated."
+
 // ----------------------------------------------------------------------------
 // Keymap macros
 
@@ -82,16 +114,55 @@ class OneShot : public kaleidoscope::Plugin {
   static void cancel(bool with_stickies = false);
 
   // --------------------------------------------------------------------------
-  // Vestigial functions?
+  // Deprecated functions
-  void inject(Key key, uint8_t key_state) {}
+  DEPRECATED(ONESHOT_INJECT)
-  static bool isModifierActive(Key key) {
+  void inject(Key key, uint8_t key_state);
+
+  DEPRECATED(ONESHOT_ISMODIFIERACTIVE)
+  static bool isModifierActive(Key key);
+
+  DEPRECATED(ONESHOT_ISACTIVE_KEY)
+  static bool isActive(Key oneshot_key);
+
+  DEPRECATED(ONESHOT_ISSTICKY_KEY)
+  static bool isSticky(Key oneshot_key);
+
+  DEPRECATED(ONESHOT_ISPRESSED)
+  static bool isPressed() {
     return false;
   }
 
+  // --------------------------------------------------------------------------
+  // Timeout onfiguration functions
+  static void setTimeout(uint16_t ttl) {
+    timeout_ = ttl;
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    time_out = ttl;
+#pragma GCC diagnostic pop
+  }
+  static void setHoldTimeout(uint16_t ttl) {
+    hold_timeout_ = ttl;
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    hold_time_out = ttl;
+#pragma GCC diagnostic pop
+  }
+  static void setDoubleTapTimeout(int16_t ttl) {
+    double_tap_timeout_ = ttl;
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    double_tap_time_out = ttl;
+#pragma GCC diagnostic pop
+  }
+
   // --------------------------------------------------------------------------
   // Configuration variables (should probably be private)
+  DEPRECATED(ONESHOT_TIMEOUT)
   static uint16_t time_out;
+  DEPRECATED(ONESHOT_HOLD_TIMEOUT)
   static uint16_t hold_time_out;
+  DEPRECATED(ONESHOT_DOUBLE_TAP_TIMEOUT)
   static int16_t double_tap_time_out;
 
   // --------------------------------------------------------------------------
@@ -113,6 +184,12 @@ class OneShot : public kaleidoscope::Plugin {
   static constexpr uint16_t stickable_layers_mask = uint16_t(uint16_t(-1) << oneshot_mod_count);
   static constexpr KeyAddr invalid_key_addr = KeyAddr(KeyAddr::invalid_state);
 
+  // --------------------------------------------------------------------------
+  // Configuration variables
+  static uint16_t timeout_;
+  static uint16_t hold_timeout_;
+  static int16_t double_tap_timeout_;
+
   // --------------------------------------------------------------------------
   // State variables
   static uint16_t stickable_keys_;