alpha
/
Kaleidoscope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Remove deprecated event handler hooks

Browse Source 
This removes the pre-`KeyEvent` handler hooks for `onKeyswitchEvent()` and
`beforeReportingState()`.  Any third-party plugins that still use either should
be updated to use the new handlers instead.

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>
pull/1115/head
Michael Richters 3 years ago
parent f2d8e91332
commit 2c40e908d5
No known key found for this signature in database
GPG Key ID: 1288FD13E4EEF0C0
3 changed files with 14 additions and 52 deletions
Show Stats Download Patch File Download Diff File

8
docs/UPGRADING.md
Unescape View File

@ -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.

40
src/kaleidoscope/event_handlers.h
Unescape View File

@ -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__ \
@ -239,16 +223,6 @@ class SignatureCheckDummy {};
OPERATION(beforeSyncingLeds, __NL__ \
1, __NL__ \
_CURRENT_IMPLEMENTATION, __NL__ \
_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__ \
@ -257,7 +231,7 @@ class SignatureCheckDummy {};
/* 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__ \

18
src/kaleidoscope_internal/deprecations.h
Unescape View File

@ -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."

Write Preview
Loading…
Cancel
Save