Deprecate public member variables

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

examples/Keystrokes/SpaceCadet/SpaceCadet.ino

@@ -59,7 +59,7 @@ void setup() {
     SPACECADET_MAP_END,
   };
   //Set the map.
-  SpaceCadet.map = spacecadetmap;
+  SpaceCadet.setMap(spacecadetmap);
 }
 
 void loop() {

plugins/Kaleidoscope-MagicCombo/README.md

@@ -42,9 +42,9 @@ that are part of a combination.
 ## Plugin properties
 
 The extension provides a `MagicCombo` singleton object, with the following
-property:
+method:
 
-### `.min_interval`
+### `.setMinInterval(min_interval)`
 
 > Restrict the magic action to fire at most once every `min_interval`
 > milliseconds.

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

@@ -28,7 +28,9 @@
 namespace kaleidoscope {
 namespace plugin {
 
+#ifndef NDEPRECATED
 uint16_t MagicCombo::min_interval = 500;
+#endif
 
 EventHandlerResult MagicCombo::onNameQuery() {
   return ::Focus.sendName(F("MagicCombo"));
@@ -53,7 +55,7 @@ EventHandlerResult MagicCombo::afterEachCycle() {
     if (j != Runtime.device().pressedKeyswitchCount())
       match = false;
 
-    if (match && Runtime.hasTimeExpired(start_time_, min_interval)) {
+    if (match && Runtime.hasTimeExpired(start_time_, getMinInterval())) {
       ComboAction action = (ComboAction)pgm_read_ptr((void const **)&(magiccombo::combos[i].action));
 
       (*action)(i);

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

@@ -22,6 +22,15 @@
 
 #include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
 #include "kaleidoscope/plugin.h"                // for Plugin
+// -----------------------------------------------------------------------------
+// Deprecation warning messages
+#include "kaleidoscope_internal/deprecations.h"  // for DEPRECATED
+
+#define _DEPRECATED_MESSAGE_MAGICCOMBO_MIN_INTERVAL                        \
+  "The `MagicCombo.min_interval` variable is deprecated. Please use the\n" \
+  "`MagicCombo.setMinInterval()` function instead.\n"                      \
+  "This variable will be removed after 2022-09-01."
+// -----------------------------------------------------------------------------
 
 #define MAX_COMBO_LENGTH 5
 
@@ -48,13 +57,39 @@ class MagicCombo : public kaleidoscope::Plugin {
     int8_t keys[MAX_COMBO_LENGTH + 1];
   } Combo;
 
+#ifndef NDEPRECATED
+  DEPRECATED(MAGICCOMBO_MIN_INTERVAL)
   static uint16_t min_interval;
+#endif
+
+  void setMinInterval(uint16_t interval) {
+#ifndef NDEPRECATED
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    min_interval = interval;
+#pragma GCC diagnostic pop
+#else
+    min_interval_ = interval;
+#endif
+  }
+
+  uint16_t getMinInterval() {
+#ifndef NDEPRECATED
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    return min_interval;
+#pragma GCC diagnostic pop
+#else
+    return min_interval_;
+#endif
+  }
 
   EventHandlerResult onNameQuery();
   EventHandlerResult afterEachCycle();
 
  private:
   uint16_t start_time_ = 0;
+  uint16_t min_interval_ = 500;
 };
 
 namespace magiccombo {

plugins/Kaleidoscope-SpaceCadet/README.md

@@ -75,16 +75,15 @@ void setup() {
     , SPACECADET_MAP_END
   };
   //Set the map.
-  SpaceCadet.map = spacecadetmap;
+  SpaceCadet.setMap(spacecadetmap);
 }
 ```
 
 ##   Plugin methods
 
-The plugin provides the `SpaceCadet` object, with the following methods and
-properties:
+The plugin provides the `SpaceCadet` object, with the following methods:
 
-### `.map`
+### `.setMap(map)`
 
 > Set the key map. This takes an array of
 > `kaleidoscope::plugin::SpaceCadet::KeyBinding` objects with the special
@@ -103,9 +102,9 @@ properties:
 > optional and may be set per-key or left out entirely (or set to `0`) to use
 > the default timeout value.
 
-### `.time_out`
+### `.setTimeout(timeout)`
 
-> Set this property to the number of milliseconds to wait before considering a
+> Sets the number of milliseconds to wait before considering a
 > held key in isolation as its secondary role. That is, we'd have to hold a
 > `Shift` key this long, by itself, to trigger the `Shift` role in itself. This
 > timeout setting can be overridden by an individual key in the keymap, but if

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

@@ -48,8 +48,10 @@ SpaceCadet::KeyBinding::KeyBinding(Key input, Key output, uint16_t timeout)
 // -----------------------------------------------------------------------------
 // Plugin configuration variables
 
+#ifndef NDEPRECATED
 SpaceCadet::KeyBinding *SpaceCadet::map;
 uint16_t SpaceCadet::time_out = 200;
+#endif
 
 // =============================================================================
 // SpaceCadet functions
@@ -69,7 +71,7 @@ SpaceCadet::SpaceCadet() {
     */
     SPACECADET_MAP_END};
 
-  map = initialmap;
+  setMap(initialmap);
 }
 
 // =============================================================================
@@ -161,7 +163,14 @@ EventHandlerResult SpaceCadet::afterEachCycle() {
     return EventHandlerResult::OK;
 
   // Get timeout value for the pending key.
+#ifndef NDEPRECATED
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
   uint16_t pending_timeout = time_out;
+#pragma GCC diagnostic pop
+#else
+  uint16_t pending_timeout = timeout_;
+#endif
   if (map[pending_map_index_].timeout != 0)
     pending_timeout = map[pending_map_index_].timeout;
   uint16_t start_time = event_queue_.timestamp(0);

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

@@ -27,6 +27,15 @@
 #include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
 #include "kaleidoscope/key_defs.h"              // for Key, Key_NoKey
 #include "kaleidoscope/plugin.h"                // for Plugin
+// -----------------------------------------------------------------------------
+// Deprecation warning messages
+#include "kaleidoscope_internal/deprecations.h"  // for DEPRECATED
+
+#define _DEPRECATED_MESSAGE_SPACECADET_TIME_OUT                        \
+  "The `SpaceCadet.time_out` variable is deprecated. Please use the\n" \
+  "`SpaceCadet.setTimeout()` function instead.\n"                      \
+  "This variable will be removed after 2022-09-01."
+// -----------------------------------------------------------------------------
 
 #ifndef SPACECADET_MAP_END
 #define SPACECADET_MAP_END \
@@ -79,9 +88,27 @@ class SpaceCadet : public kaleidoscope::Plugin {
     return (mode_ == Mode::ON || mode_ == Mode::NO_DELAY);
   }
 
+#ifndef NDEPRECATED
   // Publically accessible variables
+  DEPRECATED(SPACECADET_TIME_OUT)
   static uint16_t time_out;            //  The global timeout in milliseconds
   static SpaceCadet::KeyBinding *map;  // The map of key bindings
+#endif
+
+  void setTimeout(uint16_t timeout) {
+#ifndef NDEPRECATED
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    time_out = timeout;
+#pragma GCC diagnostic pop
+#else
+    timeout_ = timeout;
+#endif
+  }
+
+  void setMap(KeyBinding *bindings) {
+    map = bindings;
+  }
 
   EventHandlerResult onNameQuery();
   EventHandlerResult onKeyswitchEvent(KeyEvent &event);
@@ -95,7 +122,17 @@ class SpaceCadet : public kaleidoscope::Plugin {
   };
   uint8_t mode_;
 
-  static KeyEventTracker event_tracker_;
+#ifdef NDEPRECATED
+  // Global timeout in milliseconds
+  uint16_t timeout_ = 200;
+
+  // The map of keybindings
+  KeyBinding *map = nullptr;
+  // When DEPRECATED public `map[]` variable is removed, this variable name
+  // should be given a trailing underscore to conform to code style guide.
+#endif
+
+  KeyEventTracker event_tracker_;
 
   // The maximum number of events in the queue at a time.
   static constexpr uint8_t queue_capacity_{4};

plugins/Kaleidoscope-TapDance/README.md

@@ -102,12 +102,12 @@ void setup() {
 The plugin provides a `TapDance` object, but to implement the actions, we need
 to define a function ([`tapDanceAction`][tdaction]) outside of the object. A
 handler, of sorts. Nevertheless, the plugin provides one macro that is
-particularly useful: `tapDanceActionKeys`. Apart from that, it provides one
-property only:
+particularly useful: `tapDanceActionKeys`. Apart from that, it provides only one
+configuration method:
 
-### `.time_out`
+### `.setTimeout(timeout)`
 
-> The number of loop iterations to wait before a tap-dance sequence times out.
+> Set the number of milliseconds to wait before a tap-dance sequence times out.
 > Once the sequence timed out, the action for it will trigger, even without an
 > interruptor. Defaults to 5, and the timer resets with every tap of the same
 

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

@@ -37,7 +37,9 @@ namespace plugin {
 
 // --- config ---
 
+#ifndef NDEPRECATED
 uint16_t TapDance::time_out  = 200;
+#endif
 
 // --- api ---
 void TapDance::actionKeys(uint8_t tap_count,
@@ -143,7 +145,20 @@ EventHandlerResult TapDance::afterEachCycle() {
 
   // Check for timeout
   uint16_t start_time = event_queue_.timestamp(0);
-  if (Runtime.hasTimeExpired(start_time, time_out)) {
+  // To avoid confusing editors with unmatched braces, we use a temporary
+  // boolean, until the deprecated code can be removed.
+  bool timed_out = false;
+#ifndef NDEPRECATED
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+  if (Runtime.hasTimeExpired(start_time, time_out))
+    timed_out = true;
+#pragma GCC diagnostic pop
+#else
+  if (Runtime.hasTimeExpired(start_time, timeout_))
+    timed_out = true;
+#endif
+  if (timed_out) {
     // We start with the assumption that the TapDance key is still being held.
     ActionType action = Hold;
     // Now we search for a release event for the TapDance key, starting from the

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

@@ -28,6 +28,15 @@
 #include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
 #include "kaleidoscope/key_defs.h"              // for Key
 #include "kaleidoscope/plugin.h"                // for Plugin
+// -----------------------------------------------------------------------------
+// Deprecation warning messages
+#include "kaleidoscope_internal/deprecations.h"  // for DEPRECATED
+
+#define _DEPRECATED_MESSAGE_TAPDANCE_TIME_OUT                        \
+  "The `TapDance.time_out` variable is deprecated. Please use the\n" \
+  "`TapDance.setTimeout()` function instead.\n"                      \
+  "This variable will be removed after 2022-09-01."
+// -----------------------------------------------------------------------------
 
 #define TD(n)                                                kaleidoscope::plugin::TapDanceKey(n)
 
@@ -53,7 +62,20 @@ class TapDance : public kaleidoscope::Plugin {
     Release,
   };
 
+#ifndef NDEPRECATED
+  DEPRECATED(TAPDANCE_TIME_OUT)
   static uint16_t time_out;
+#endif
+
+  void setTimeout(uint16_t timeout) {
+#ifndef NDEPRECATED
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+    time_out = timeout;
+#pragma GCC diagnostic pop
+#endif
+    timeout_ = timeout;
+  }
 
   void actionKeys(uint8_t tap_count, ActionType tap_dance_action, uint8_t max_keys, const Key tap_keys[]);
 
@@ -78,6 +100,9 @@ class TapDance : public kaleidoscope::Plugin {
   // The number of taps in the current TapDance sequence.
   uint8_t tap_count_ = 0;
 
+  // Time to wait for another input event before resolving a TapDance sequence.
+  uint16_t timeout_ = 200;
+
   void flushQueue(KeyAddr ignored_addr = KeyAddr::none());
 };