-
Notifications
You must be signed in to change notification settings - Fork 257
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to extend with new hook points, provides a better interface, uses less memory, less program space, and is a tiny bit faster too. It all begins with `kaleidoscope::Plugin` being the base class, which provides the hook methods plugins can implement. Plugins should be declared with `KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro is a bit of magic (see the in-code documentation) that allows us to unroll the hook method calls, avoid vtables, and so on. It creates an override for `kaleidoscope::Hooks::*` methods, each of which will call the respective methods of each initialized plugin. With the new API come new names: all of the methods plugins can implement received new, more descriptive names that all follow a similar pattern. The old (dubbed V1) API still remains in place, although deprecated. One can turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero, while compiling the firmware. This work is based on #276, written by @noseglasses. @obra and @algernon did some cleaning up and applied a little naming treatment. Signed-off-by: noseglasses <shinynoseglasses@gmail.com> Signed-off-by: Jesse Vincent <jesse@keyboard.io> Signed-off-by: Gergely Nagy <algernon@keyboard.io>
- Loading branch information
1 parent
bc76032
commit 8130dfd
Showing
18 changed files
with
1,284 additions
and
158 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,114 @@ | ||
Deprecated APIs and their replacements | ||
====================================== | ||
|
||
As the firmware evolves, there are - and will be - APIs that we deprecate, and | ||
eventually remove. This document is a short guide that lists the deprecations - | ||
along with when it happened, and when the functionality will be removed -, | ||
suggested upgrade paths, and any other information that may be useful. | ||
|
||
If any of this does not make sense to you, or you have trouble updating your | ||
.ino sketch, do not hesitate to write us at help@keyboard.io, we can help you | ||
fix it. | ||
|
||
## Sheduled for removal by 2018-05-26 | ||
|
||
These APIs and functions have been deprecated for a long time, and as far as we | ||
can tell, aren't used by any third party or user code anymore. | ||
|
||
### Kaleidoscope.setup(KEYMAP_SIZE) | ||
|
||
The `Kaleidoscope.setup()` method is still around, and is **not** deprecated, | ||
but the variant of it that takes a keymap size is, and has been since October | ||
2017. | ||
|
||
Instead, one should use the argument-less `Kaleidoscope.setup()`, and the new | ||
`KEYMAP()` macros to define a keymap. | ||
|
||
### event_handler_hook_use, loop_hook_use, and USE_PLUGINS | ||
|
||
Deprecated in October 2017, these are old aliases that should no longer be in | ||
use. They were replaced by `Kaleidoscope.useEventHandlerHook`, | ||
`Kaleidoscope.useLoopHook`, and `Kaleidoscope.use`, respectively. | ||
|
||
The replacements themselves are also deprecated - see below -, but their removal | ||
will come at a later date. | ||
|
||
### MOMENTARY_OFFSET | ||
|
||
Deprecated in October 2017, replaced by `LAYER_SHIFT_OFFSET`. | ||
|
||
This symbol was meant to be used by plugins, not user code, and as far as we | ||
know, no third party plugin ever used it. | ||
|
||
### key_was_pressed, key_is_pressed, key_toggled_on, key_toggled_off | ||
|
||
Deprecated in July 2017, replaced by `keyWasPressed`, `keyIsPressed`, | ||
`keyToggledOn`, and `keyToggledOff`, respectively. | ||
|
||
## Sheduled for removal by 2018-07-12 | ||
|
||
We aim at making a new release by mid-July, and APIs we deprecate now, will be | ||
removed shortly before the major release. We may deprecate further APIs during | ||
the next month (until mid-June), and those deprecations will share the same | ||
removal date. We will try our best to minimize deprecations, and do them as soon | ||
as possible, to give everyone at least a month to prepare and update. | ||
|
||
### Kaleidoscope.use() | ||
|
||
Deprecated in May 2018, this method is part of the old plugin API, replaced by | ||
`KALEIDOSCOPE_INIT_PLUGINS`. To upgrade, you need to modify your .ino sketch | ||
file, and replace the text `Kaleidoscope.use` with `KALEIDOSCOPE_INIT_PLUGINS`, | ||
then remove the `&` from all of the plugins inside it, and finally, move it | ||
outside of `setup()`. | ||
|
||
If your current sketch looks like this: | ||
|
||
```c++ | ||
void setup() { | ||
Kaleidoscope.use(&Plugin1, &Plugin2); | ||
Kaleidoscope.setup(); | ||
} | ||
``` | ||
|
||
You should change it so that it looks like this instead: | ||
|
||
```c++ | ||
KALEIDOSCOPE_INIT_PLUGINS(Plugin1, Plugin2); | ||
|
||
void setup() { | ||
Kaleidoscope.setup(); | ||
} | ||
``` | ||
### The old-style (v1) plugin API | ||
This includes using `KaleidoscopePlugin`, `Kaleidoscope.useEventHandlerHook`, | ||
`Kaleidoscope.replaceEventHandlerHook`, `Kaleidoscope.appendEventHandlerHook`, | ||
`Kaleidoscope.useLoopHook`, `Kaleidoscope.replaceLoopHook`, | ||
`Kaleidoscope.appendLoopHook`. They were deprecated in May 2017. | ||
Their replacement is the new plugin API: | ||
```c++ | ||
namespace kaleidoscope { | ||
enum class EventHandlerResult { | ||
OK, | ||
EVENT_CONSUMED, | ||
ERROR, | ||
}; | ||
class Plugin { | ||
public: | ||
EventHandlerResult onSetup(); | ||
EventHandlerResult beforeEachCycle(); | ||
EventHandlerResult onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state); | ||
EventHandlerResult beforeReportingState(); | ||
EventHandlerResult afterEachCycle(); | ||
}; | ||
} | ||
``` | ||
|
||
Plugins are supposed to implement this new API, and then be initialised via | ||
`KALEIDOSCOPE_INIT_PLUGINS`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
# Glossary | ||
|
||
This document is intended to name and describe the concepts, functions and data structures inside Kaleidoscope. | ||
|
||
It is, as yet, incredibly incomplete. | ||
|
||
Entries should be included in dictionary order. When describing an identifier of any kind from the codebase, it should be | ||
written using identical capitalization to its use in the code and surrounded by backticks: `identifierName` | ||
|
||
|
||
Event handler | ||
|
||
: A function, usually provided by a `Plugin` that is run by a `Hook` |
Oops, something went wrong.