diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index a3aa5d03..c047ae5a 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -1052,6 +1052,14 @@ The following headers and names have changed: # Removed APIs +### Removed on 2022-03-03 + +#### Pre-`KeyEvent` event handler hooks + +The old event handler `onKeyswitchEvent(Key &key, KeyAddr addr, uint8_t state)` was removed on **2022-03-03**. It has been replaced with the new `onKeyEvent(KeyEvent &event)` handler (and, in some special cases the `onKeyswitchEvent(KeyEvent &event)` handler). Plugins using the deprecated handler will need to be rewritten to use the new one(s). + +The old event handler `beforeReportingState()` was removed on **2022-03-03**. It has been replaced with the new `beforeReportingState(KeyEvent &event)` handler. However, the new handler will be called only when a report is being sent (generally in response to a key event), not every cycle, like the old one. It was common practice in the past for plugins to rely on `beforeReportingState()` being called every cycle, so when adapting to the `KeyEvent` API, it's important to check for code that should be moved to `afterEachCycle()` instead. + #### `::handleKeyswitchEvent(Key key, KeyAddr key_addr, uint8_t state)` The old master function for processing key "events" was removed on **2022-03-03**. Functions that were calling this function should be rewritten to call `kaleidoscope::Runtime.handleKeyEvent(KeyEvent event)` instead. diff --git a/src/kaleidoscope/event_handlers.h b/src/kaleidoscope/event_handlers.h index 11ca03e9..806f89d2 100644 --- a/src/kaleidoscope/event_handlers.h +++ b/src/kaleidoscope/event_handlers.h @@ -139,22 +139,6 @@ class SignatureCheckDummy {}; (),(),(), /* non template */ __NL__ \ (), (), ##__VA_ARGS__) __NL__ \ __NL__ \ - /* DEPRECATED */ __NL__ \ - /* Function called for every non-idle key, every cycle, so it */ __NL__ \ - /* can decide what to do with it. It can modify the key (which is */ __NL__ \ - /* passed by reference for this reason), and decide whether */ __NL__ \ - /* further handles should be tried. If it returns */ __NL__ \ - /* EventHandlerResult::OK, other handlers will also get a chance */ __NL__ \ - /* to react to the event. If it returns anything else, Kaleidoscope */ __NL__ \ - /* will stop processing there. */ __NL__ \ - OPERATION(onKeyswitchEvent, __NL__ \ - 1, __NL__ \ - DEPRECATED(ON_KEYSWITCH_EVENT_V1), __NL__ \ - _ABORTABLE, __NL__ \ - (),(),(), /* non template */ __NL__ \ - (Key &mappedKey, KeyAddr key_addr, uint8_t keyState), __NL__ \ - (mappedKey, key_addr, keyState), ##__VA_ARGS__) __NL__ \ - __NL__ \ /* Function called for every physical keyswitch event (toggle on or */ __NL__ \ /* off). The `event` parameter is passed by reference so its key */ __NL__ \ /* value can be modified. If it returns EventHandlerResult::OK, the */ __NL__ \ @@ -166,7 +150,7 @@ class SignatureCheckDummy {}; /* plugin that does so must release events in ascending order, */ __NL__ \ /* counting by ones. */ __NL__ \ OPERATION(onKeyswitchEvent, __NL__ \ - 2, __NL__ \ + 1, __NL__ \ _CURRENT_IMPLEMENTATION, __NL__ \ _ABORTABLE, __NL__ \ (),(),(), /* non template */ __NL__ \ @@ -242,22 +226,12 @@ class SignatureCheckDummy {}; _NOT_ABORTABLE, __NL__ \ (),(),(), /* non template */ __NL__ \ (), (), ##__VA_ARGS__) __NL__ \ - /* DEPRECATED */ __NL__ \ - /* Called before reporting our state to the host. This is the */ __NL__ \ - /* last point in a cycle where a plugin can alter what gets */ __NL__ \ - /* reported to the host. */ __NL__ \ - OPERATION(beforeReportingState, __NL__ \ - 1, __NL__ \ - DEPRECATED(BEFORE_REPORTING_STATE_V1), __NL__ \ - _NOT_ABORTABLE, __NL__ \ - (),(),(), /* non template */ __NL__ \ - (),(),##__VA_ARGS__) __NL__ \ __NL__ \ /* Called before reporting our state to the host. This is the */ __NL__ \ /* last point in a cycle where a plugin can alter what gets */ __NL__ \ /* reported to the host. */ __NL__ \ OPERATION(beforeReportingState, __NL__ \ - 2, __NL__ \ + 1, __NL__ \ _CURRENT_IMPLEMENTATION, __NL__ \ _ABORTABLE, __NL__ \ (),(),(), /* non template */ __NL__ \ @@ -330,10 +304,9 @@ class SignatureCheckDummy {}; OP(beforeEachCycle, 1) __NL__ \ END(beforeEachCycle, 1) __NL__ \ __NL__ \ - START(onKeyswitchEvent, 1, 2) __NL__ \ + START(onKeyswitchEvent, 1) __NL__ \ OP(onKeyswitchEvent, 1) __NL__ \ - OP(onKeyswitchEvent, 2) __NL__ \ - END(onKeyswitchEvent, 1, 2) __NL__ \ + END(onKeyswitchEvent, 1) __NL__ \ __NL__ \ START(onKeyEvent, 1) __NL__ \ OP(onKeyEvent, 1) __NL__ \ @@ -359,10 +332,9 @@ class SignatureCheckDummy {}; OP(beforeSyncingLeds, 1) __NL__ \ END(beforeSyncingLeds, 1) __NL__ \ __NL__ \ - START(beforeReportingState, 1, 2) __NL__ \ + START(beforeReportingState, 1) __NL__ \ OP(beforeReportingState, 1) __NL__ \ - OP(beforeReportingState, 2) __NL__ \ - END(beforeReportingState, 1, 2) __NL__ \ + END(beforeReportingState, 1) __NL__ \ __NL__ \ START(afterReportingState, 1) __NL__ \ OP(afterReportingState, 1) __NL__ \ diff --git a/src/kaleidoscope_internal/deprecations.h b/src/kaleidoscope_internal/deprecations.h index 6024f206..5cedea76 100644 --- a/src/kaleidoscope_internal/deprecations.h +++ b/src/kaleidoscope_internal/deprecations.h @@ -28,21 +28,3 @@ "------------------------------------------------------------------------\n" \ /* Messages */ - -#define _DEPRECATED_MESSAGE_ON_KEYSWITCH_EVENT_V1 __NL__ \ - "The `onKeyswitchEvent()` event handler is deprecated.\n" __NL__ \ - "Please replace it with an `onKeyEvent()` handler. See the documentation\n" __NL__ \ - "in UPGRADING.md and docs/api-reference/event-handler-hooks.md for more\n" __NL__ \ - "information on what changes are needed to adapt old plugins to the new\n" __NL__ \ - "event handler API.\n" __NL__ \ - "This function will be removed after 2021-08-01." - -#define _DEPRECATED_MESSAGE_BEFORE_REPORTING_STATE_V1 __NL__ \ - "This `beforeReportingState()` event handler version is deprecated.\n" __NL__ \ - "There is a new `beforeReportingState(KeyEvent)` handler that can be used\n" __NL__ \ - "instead, for plugins that need to execute code before each new HID\n" __NL__ \ - "report is sent. However, the new handler does not run every cycle, but\n" __NL__ \ - "only in response to key events. If you have code that is intended to run\n" __NL__ \ - "every scan cycle, it should be moved to the `afterEachCycle()` event\n" __NL__ \ - "handler instead.\n" __NL__ \ - "This function will be removed after 2021-08-01."