Merge pull request #927 from gedankenexperimenter/qukeys-deprecation-dates

Add deprecation dates for old Qukeys functions

docs/UPGRADING.md

@@ -16,6 +16,7 @@ If any of this does not make sense to you, or you have trouble updating your .in
     - [The `RxCy` macros and peeking into the keyswitch state](#the-rxcy-macros-and-peeking-into-the-keyswitch-state)
     - [HostOS](#hostos)
     - [MagicCombo](#magiccombo)
+    - [Qukeys](#qukeys)
     - [TypingBreaks](#typingbreaks)
     - [Redial](#redial)
     - [Key mapping has been deprecated](#key-mapping-has-been-deprecated)
@@ -497,6 +498,32 @@ If your actions made use of the `left_hand` or `right_hand` arguments of
 more involved to get to, out of scope for this simple migration guide. Please
 open an issue, or ask for help on the forums, and we'll help you.
 
+### Qukeys
+
+Older versions of the plugin used `row` and `col` indexing for defining `Qukey`
+objects. This has since been replaced with a single `KeyAddr` parameter in the
+constructor.
+
+Older versions of the plugin used a single timeout, configured via a
+`setTimeout()` method. For clarity, that method has been renamed to
+`setHoldTimeout()`.
+
+Older versions of the plugin used a configurable "release delay" value to give
+the user control over how Qukeys determined which value to assign to a qukey
+involved in rollover, via the `setReleaseDelay()` method. That release delay has
+been replaced with a better "overlap percentage" strategy, which makes the
+decision based on the percentage of the subsequent keypress's duration overlaps
+with the qukey's press. The configuration method is now `setOverlapThreshold()`,
+which accepts a value between 0 and 100 (interpreted as a percentage). User who
+used higher values for `setReleaseDelay()` will want a lower values for
+`setOverlapThreshold()`.
+
+These functions have been deprecated since 2019-08-22, and will be removed by **2020-12-31**:
+
+- `Qukeys.setTimeout(millis)`
+- `Qukeys.setReleaseDelay(millis)`
+- `Qukey(layer, row, col, alternate_key)`
+
 ### TypingBreaks
 
 Older versions of the plugin used to provide EEPROM storage for the settings only optionally, when it was explicitly enabled via the `TypingBreaks.enableEEPROM()` method. Similarly, the Focus hooks were optional too.

src/kaleidoscope/plugin/Qukeys.h

@@ -35,21 +35,24 @@
 
 #define LT(layer, key) Key(kaleidoscope::ranges::DUL_FIRST + (layer << 8) + (Key_ ## key).getKeyCode())
 
-#define _DEPRECATED_MESSAGE_QUKEY_ROW_COL_CONSTRUCTOR                        \
-  "The `Qukey(layer, row, col, alternate_key)` constructor using separate\n" \
-  "`row` & `col` parameters has been deprecated. Please replace this\n"      \
-  "constructor with the new `KeyAddr` version:\n"                            \
-  "    `Qukey(layer, KeyAddr(row, col), alternate_key)`"
-
-#define _DEPRECATED_MESSAGE_QUKEYS_TIMEOUT                                  \
-  "The Qukeys.setTimeout() function has been renamed to setHoldTimeout()\n" \
-  "in order to distinguish it from the other timeouts more clearly."
-
-#define _DEPRECATED_MESSAGE_QUKEYS_RELEASEDELAY                               \
-  "The Qukeys.setReleaseDelay() is now obsolete. The rollover grace period\n" \
-  "for qukey release has been replaced with an improved version based on\n"   \
-  "the percentage of overlap between the qukey and the subsequent\n"          \
-  "key. Please use the setOverlapThreshold() function instead."
+#define _DEPRECATED_MESSAGE_QUKEY_ROW_COL_CONSTRUCTOR                           \
+  "The `Qukey(layer, row, col, alternate_key)` constructor using separate\n"    \
+  "`row` & `col` parameters has been deprecated. Please replace this\n"         \
+  "constructor with the new `KeyAddr` version:\n"                               \
+  "    `Qukey(layer, KeyAddr(row, col), alternate_key)`"                        \
+  "The deprecated function will be removed after 2020-12-31"
+
+#define _DEPRECATED_MESSAGE_QUKEYS_TIMEOUT                                      \
+  "The Qukeys.setTimeout() function has been renamed to setHoldTimeout()\n"     \
+  "in order to distinguish it from the other timeouts more clearly."            \
+  "The deprecated function will be removed after 2020-12-31"
+
+#define _DEPRECATED_MESSAGE_QUKEYS_RELEASEDELAY                                 \
+  "The Qukeys.setReleaseDelay() is now obsolete. The rollover grace period\n"   \
+  "for qukey release has been replaced with an improved version based on\n"     \
+  "the percentage of overlap between the qukey and the subsequent\n"            \
+  "key. Please use the setOverlapThreshold() function instead."                 \
+  "The deprecated function will be removed after 2020-12-31"
 
 namespace kaleidoscope {
 namespace plugin {