From 77546706a3e96347d6fca3fe63ef8e17c4266bb6 Mon Sep 17 00:00:00 2001 From: Michael Richters Date: Fri, 13 Nov 2020 22:47:21 -0600 Subject: [PATCH] Update documentation for active keys cache changes Signed-off-by: Michael Richters --- docs/UPGRADING.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index a45653fc..50a7d7c1 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -33,6 +33,35 @@ any API we've included in a release. Typically, this means that any code that us ## New features +### Keymap cache changes + +The keymap cache (`Layer_::live_composite_keymap_[]`) has been replaced by an "active keys" cache (`Runtime_::active_keys_[]`). The top-level function that handles keyswitch events has been updated to make the new cache a representation of the current state of the keyboard, with corresponding `Key` values for any keys that are active (physically held or activated by a plugin). + +#### For end-users + +There should be no user-visible changes for anyone who simply uses core plugins. A few functions have been deprecated (`Layer.eventHandler()` & `Layer.updateLiveCompositeKeymap()`), but there are straightforward replacements for both. + +#### For developers + +The major changes are to the `handleKeyswitchEvent()` function, which has been reorganized in order to update the new active keys cache with correct values at the appropriate times. In addition to that, two new facilities are available: + +##### `EventHandlerResult::ABORT` + +This is a new return value available to plugin event handlers, which is similar to `EVENT_CONSUMED` in that it causes the calling hook function to return early (stopping any subsequent handlers from seeing the event), but is treated differently by `handleKeyswitchEvent()`. If a handler returns `EVENT_CONSUMED`, the active keys cache will still be updated by `handleKeyswitchEvent()`, but if it returns `ABORT`, it will not. In both cases, no further event processing will be done by the built-in event handler. + +##### `Runtime.activeKey(key_addr)` + +This is a new function that can be used to check the value of an entry in the active keys cache. For example, it could be used in a range-based `for` loop to check for values of interest: + +```c++ +for (KeyAddr key_addr : KeyAddr::all()) { + Key key = Runtime.activeKey(key_addr); + if (key == Key_LeftShift || key == Key_RightShift) { + // do something special... + } +} +``` + ### New build system In this release, we replace kaleidoscope-builder with a new Makefile based build system that uses `arduino-cli` instead of of the full Arduino IDE. This means that you can now check out development copies of Kaliedoscope into any directory, using the `KALEIDOSCOPE_DIR` environment variable to point to your installation. @@ -570,6 +599,14 @@ The following headers and names have changed: - [Syster](plugins/Syster.md) had the `kaleidoscope::Syster::action_t` type replaced by `kaleidoscope::plugin::Syster::action_t`. - [TapDance](plugins/TapDance.md) had the `kaleidoscope::TapDance::ActionType` type replaced by `kaleidoscope::plugin::TapDance::ActionType`. +### Live Composite Keymap Cache + +The live composite keymap, which contained a lazily-updated version of the current keymap, has been replaced. The `Layer.updateLiveCompositeKeymap()` functions have been deprecated, and depending on the purpose of the caller, it might be appropriate to use `Runtime.updateActiveKey()` instead. + +When `handleKeyswitchEvent()` is looking up a `Key` value for an event, it first checks the value in the active keys cache before calling `Layer.lookup()` to get the value from the keymap. In the vast majority of cases, it won't be necessary to call `Runtime.updateActiveKey()` manually, however, because simply changing the value of the `Key` parameter of an `onKeyswitchEvent()` handler will have the same effect. + +Second, the `Layer.eventHandler()` function has been deprecated. There wasn't much need for this to be available to plugins, and it's possible to call `Layer.handleKeymapKeyswitchEvent()` directly instead. + # Removed APIs ### Removed on 2020-10-10