Add NEWS and UPGRADING entries for OneShotMetaKeys

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

docs/NEWS.md

@@ -12,6 +12,29 @@ See [UPGRADING.md](UPGRADING.md) for more detailed instructions about upgrading
 
 ## New features
 
+### OneShot public functions
+
+The OneShot plugin now allows other plugins to control the OneShot state of
+individual keys, by calling one of the following:
+
+- `OneShot.setPending(key_addr)`: Put the key at `key_addr` in the "pending"
+  OneShot state.  This will make that key act like any other OneShot key until
+  it is cancelled by a subsequent keypress.  Once a key is in this state,
+  OneShot will manage it from that point on, including making the key "sticky"
+  if it is double-tapped.
+- `OneShot.setSticky(key_addr)`: Put the key at `key_addr` in the "sticky"
+  OneShot state.  The key will be released by OneShot when it is tapped again.
+- `OneShot.setOneShot(key_addr)`: Put the key at `key_addr` in the "one-shot"
+  state.  This is normally the state OneShot key will be in after it has been
+  tapped.  Calling `setPending()` is more likely to be useful.
+- `OneShot.clear(key_addr)`: Clear the OneShot state of the key at `key_addr`.
+
+Note: Any plugin that calls one of these OneShot methods must either be
+registered in `KALEIDOSCOPE_INIT_PLUGINS()` after OneShot, or it must add the
+`INJECTED` bit to the keyswitch state of the event (i.e. `event.state |=
+INJECTED`) to prevent OneShot from prematurely advancing keys to the next
+OneShot state.
+
 ### SpaceCadet "no-delay" mode
 
 SpaceCadet can now be enabled in "no-delay" mode, wherein the primary (modifier)

docs/UPGRADING.md

@@ -16,6 +16,7 @@ If any of this does not make sense to you, or you have trouble updating your .in
     - [Bidirectional communication for plugins](#bidirectional-communication-for-plugins)
     - [Consistent timing](#consistent-timing)
   + [Breaking changes](#breaking-changes)
+    - [OneShot meta keys](#oneshot-meta-keys)
     - [git checkouts aren't compatible with Arduino IDE (GUI)]([#repository-rearchitecture)
     - [Layer system switched to activation-order](#layer-system-switched-to-activation-order)
     - [The `RxCy` macros and peeking into the keyswitch state](#the-rxcy-macros-and-peeking-into-the-keyswitch-state)
@@ -434,6 +435,10 @@ As a developer, one can continue using `millis()`, but migrating to `Kaleidoscop
 
 ## Breaking changes
 
+### OneShot meta keys
+
+The special OneShot keys `OneShot_MetaStickyKey` & `OneShot_ActiveStickyKey` are no longer handled by the OneShot plugin directly, but instead by a separate OneShotMetaKeys plugin. If you use these keys in your sketch, you will need to add the new plugin, and register it after OneShot in `KALEIDOSCOPE_INIT_PLUGINS()` for those keys to work properly.
+
 ### Repository rearchitecture
 
 To improve build times and to better highlight Kaleidoscope's many plugins, plugins have been move into directories inside the Kaleidoscope directory.