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>pull/316/head
noseglasses
6 years ago
committed by
Gergely Nagy
parent
bc76032d37
commit
8130dfdf1d
@ -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`.
|
||||
@ -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`
|
||||
@ -0,0 +1,342 @@
|
||||
# Kaleidoscope Plugin API Internals
|
||||
|
||||
This document attempts to explain how the plugin system works internally, behind
|
||||
the scenes. We feel this is necessary, because there are some unorthodox
|
||||
solutions in play, which make the code incredibly hard to untangle. This is an
|
||||
unavoidable side-effect of employing a system that lets us use non-virtual
|
||||
functions, and save large amounts of RAM thereby. It would be a lot simpler
|
||||
without this feature, but alas, saving hundreds of bytes of RAM is something we
|
||||
felt is worth the complexity.
|
||||
|
||||
Lets start at the top:
|
||||
|
||||
## `KALEIDOSCOPE_INIT_PLUGINS`
|
||||
|
||||
```c++
|
||||
#define KALEIDOSCOPE_INIT_PLUGINS(...) _KALEIDOSCOPE_INIT_PLUGINS(__VA_ARGS__)
|
||||
```
|
||||
|
||||
So far so good, this is pretty simple. The reason we use an indirection here is
|
||||
because this is in `Kaleidoscope.h`, and we do not want the complexity of the
|
||||
`_KALEIDOSCOPE_INIT_PLUGINS` macro here, nor do we want to move the macro to
|
||||
another header, because it belongs to `Kaleidoscope.h`.
|
||||
|
||||
## `_KALEIDOSCOPE_INIT_PLUGINS`
|
||||
|
||||
```c++
|
||||
#define _KALEIDOSCOPE_INIT_PLUGINS(...) \
|
||||
namespace kaleidoscope_internal { \
|
||||
struct EventDispatcher { \
|
||||
\
|
||||
template<typename EventHandler__, typename... Args__ > \
|
||||
static kaleidoscope::EventHandlerResult apply(Args__&&... hook_args) { \
|
||||
\
|
||||
kaleidoscope::EventHandlerResult result; \
|
||||
MAP(_INLINE_EVENT_HANDLER_FOR_PLUGIN, __VA_ARGS__) \
|
||||
\
|
||||
return result; \
|
||||
} \
|
||||
}; \
|
||||
\
|
||||
} \
|
||||
_FOR_EACH_EVENT_HANDLER(_REGISTER_EVENT_HANDLER)
|
||||
```
|
||||
|
||||
This is where things get interesting. This macro does two things:
|
||||
|
||||
- It creates `kaleidoscope_internal::EventDispatcher`, a class with a single
|
||||
method, `apply`. This is a templated method, the template argument is the
|
||||
method `apply` will call. Thus, `EventDispatcher::template apply<foo>` will
|
||||
resolve to a function that calls the `foo` method of each plugin we listed
|
||||
for `KALEIDOSCOPE_INIT_PLUGINS`. We'll see in a bit how this happens.
|
||||
|
||||
- The other part creates overrides for the `Kaleidoscope::Hooks::` family of
|
||||
functions. These are wrappers around `EventDispatcher::template apply<foo>`.
|
||||
We have these so higher level code would not need to care about the
|
||||
implementation details, so that it can invoke the hooks as if they were
|
||||
ordinary functions.
|
||||
|
||||
## `_FOR_EACH_EVENT_HANDLER(_REGISTER_EVENT_HANDLER)`
|
||||
|
||||
Lets look at `_FOR_EACH_EVENT_HANDLER` and `_REGISTER_EVENT_HANDLER` first,
|
||||
because that's easier to explain, and does not lead down another rabbit hole.
|
||||
|
||||
### `_REGISTER_EVENT_HANDLER`
|
||||
|
||||
```c++
|
||||
#define _REGISTER_EVENT_HANDLER( \
|
||||
HOOK_NAME, SHOULD_ABORT_ON_CONSUMED_EVENT, SIGNATURE, ARGS_LIST) \
|
||||
\
|
||||
namespace kaleidoscope_internal { \
|
||||
\
|
||||
struct EventHandler_##HOOK_NAME { \
|
||||
\
|
||||
static bool shouldAbortOnConsumedEvent() { \
|
||||
return SHOULD_ABORT_ON_CONSUMED_EVENT; \
|
||||
} \
|
||||
\
|
||||
template<typename Plugin__, typename... Args__> \
|
||||
static kaleidoscope::EventHandlerResult \
|
||||
call(Plugin__ &plugin, Args__&&... hook_args) { \
|
||||
_VALIDATE_EVENT_HANDLER_SIGNATURE(HOOK_NAME, Plugin__) \
|
||||
return plugin.HOOK_NAME(hook_args...); \
|
||||
} \
|
||||
}; \
|
||||
\
|
||||
} \
|
||||
\
|
||||
namespace kaleidoscope { \
|
||||
\
|
||||
EventHandlerResult Hooks::HOOK_NAME SIGNATURE { \
|
||||
return kaleidoscope_internal::EventDispatcher::template \
|
||||
apply<kaleidoscope_internal::EventHandler_ ## HOOK_NAME> \
|
||||
ARGS_LIST; \
|
||||
} \
|
||||
\
|
||||
}
|
||||
```
|
||||
|
||||
This looks big and scary, but in practice, it isn't all that bad. Nevertheless,
|
||||
this is where the magic happens!
|
||||
|
||||
We create two things: `EventHandler_SomeThing` and `Hooks::SomeThing`, the
|
||||
latter being a wrapper around the first, that uses `EventDispatcher::template
|
||||
apply<>` discussed above.
|
||||
|
||||
Lets take `onSetup` as an example! For that, the above expands to:
|
||||
|
||||
```c++
|
||||
namespace kaleidoscope_internal {
|
||||
|
||||
struct EventHandler_onSetup {
|
||||
static bool shouldAbortOnConsumedEvent() {
|
||||
return false;
|
||||
}
|
||||
|
||||
template<typename Plugin__, typename... Args__>
|
||||
static kaleidoscope::EventHandlerResult
|
||||
call(Plugin__ &plugin, Args__&&... hook_args) {
|
||||
return plugin.onSetup(hook_args...);
|
||||
}
|
||||
};
|
||||
|
||||
}
|
||||
|
||||
namespace kaleidoscope {
|
||||
|
||||
EventHandlerResult Hooks::onSetup() {
|
||||
return kaleidoscope_internal::EventDispatcher::template
|
||||
apply<kaleidoscope_internal::EventHandler_onSetup>();
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
This still looks scary... but please read a bit further, and it will all make
|
||||
sense!
|
||||
|
||||
### `_FOR_EACH_EVENT_HANDLER`
|
||||
|
||||
This just evaluates its argument for each event handler supported by
|
||||
Kaleidoscope core. Very simple macro expansion, which we will not expand here,
|
||||
because that would take up a lot of space, and they all look the same (see
|
||||
above).
|
||||
|
||||
## `EventDispatcher`
|
||||
|
||||
```c++
|
||||
namespace kaleidoscope_internal {
|
||||
struct EventDispatcher {
|
||||
template<typename EventHandler__, typename... Args__ >
|
||||
static kaleidoscope::EventHandlerResult apply(Args__&&... hook_args) {
|
||||
|
||||
kaleidoscope::EventHandlerResult result;
|
||||
MAP(_INLINE_EVENT_HANDLER_FOR_PLUGIN, __VA_ARGS__)
|
||||
|
||||
return result;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
This is where the other part of the magic happens, and we need to understand
|
||||
this to be able to make sense of `_REGISTER_EVENT_HANDLER` above.
|
||||
|
||||
### `_INLINE_EVENT_HANDLER_FOR_PLUGIN`
|
||||
|
||||
This in isolation, is not very interesting, and is closely tied to
|
||||
`EventDispatcher`. The definition is here so we can look at it while we learn
|
||||
the details of `EventDispatcher` below.
|
||||
|
||||
```c++
|
||||
#define _INLINE_EVENT_HANDLER_FOR_PLUGIN(PLUGIN) \
|
||||
\
|
||||
result = EventHandler__::call(PLUGIN, hook_args...); \
|
||||
\
|
||||
if (EventHandler__::shouldAbortOnConsumedEvent() && \
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) { \
|
||||
return result; \
|
||||
}
|
||||
```
|
||||
|
||||
### Back to `EventDispatcher`...
|
||||
|
||||
The `EventDispatcher` structure has a single method: `apply<>`, which needs an
|
||||
event handler as its template argument. What the macro does, is call the event
|
||||
handler given in the template argument for each and every initialised plugin.
|
||||
It's best explained with an example! Lets use two plugins, `SomePlugin` and
|
||||
`ExampleEffect`:
|
||||
|
||||
```c++
|
||||
namespace kaleidoscope_internal {
|
||||
struct EventDispatcher {
|
||||
template<typename EventHandler__, typename... Args__ >
|
||||
static kaleidoscope::EventHandlerResult apply(Args__&&... hook_args) {
|
||||
|
||||
kaleidoscope::EventHandlerResult result;
|
||||
|
||||
result = EventHandler__::call(SomePlugin);
|
||||
if (EventHandler__::shouldAbortOnConsumedEvent() &&
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) {
|
||||
return result;
|
||||
}
|
||||
|
||||
result = EventHandler__::call(ExampleEffect);
|
||||
if (EventHandler__::shouldAbortOnConsumedEvent() &&
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) {
|
||||
return result;
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
See? It's unrolled! But how do we get from here to - say - calling the
|
||||
`onSetup()` method of the plugins? Why, by way of `EventDispatcher::template
|
||||
apply<EventHandler_onSetup>`! Lets see what happens when we do a call like that:
|
||||
|
||||
```c++
|
||||
namespace kaleidoscope_internal {
|
||||
struct EventDispatcher {
|
||||
template<typename EventHandler_onSetup, typename... Args__ >
|
||||
static kaleidoscope::EventHandlerResult apply(Args__&&... hook_args) {
|
||||
|
||||
kaleidoscope::EventHandlerResult result;
|
||||
|
||||
result = EventHandler_onSetup::call(SomePlugin);
|
||||
if (EventHandler_onSetup::shouldAbortOnConsumedEvent() &&
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) {
|
||||
return result;
|
||||
}
|
||||
|
||||
result = EventHandler_onSetup::call(ExampleEffect);
|
||||
if (EventHandler_onSetup::shouldAbortOnConsumedEvent() &&
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) {
|
||||
return result;
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
Because we call `EventHandler_onSetup::call` with the plugin as the first
|
||||
argument, and because `call` is also a templated function, where the first
|
||||
argument is templated, we get a method that is polimorphic on its first
|
||||
argument. Meaning, for each and every plugin, we'll have a matching
|
||||
`EventHandler_onSetup::call`, that is tied to that plugin. *This* is the magic
|
||||
that lets us use non-virtual methods!
|
||||
|
||||
## Exploring what the compiler does
|
||||
|
||||
Because all hooks are called via `kaleidoscope::Hooks::NAME`, lets explore how
|
||||
the compiler will optimize the code for `onSetup`, assuming we use two plugins,
|
||||
`SomePlugin` and `ExampleEffect`.
|
||||
|
||||
Our entry point is this:
|
||||
|
||||
```c++
|
||||
return kaleidoscope::Hooks::onSetup();
|
||||
```
|
||||
|
||||
`_REGISTER_EVENT_HANDLER` created `Hooks::onSetup()` for us:
|
||||
|
||||
```c++
|
||||
EventHandlerResult kaleidoscope::Hooks::onSetup() {
|
||||
return kaleidoscope_internal::EventDispatcher::template
|
||||
apply<kaleidoscope_internal::EventHandler_onSetup>();
|
||||
}
|
||||
```
|
||||
|
||||
If we inline the call to `EventDispatcher::template apply<>`, we end up with the
|
||||
following:
|
||||
|
||||
```c++
|
||||
EventHandlerResult kaleidoscope::Hooks::onSetup() {
|
||||
kaleidoscope::EventHandlerResult result;
|
||||
|
||||
result = EventHandler_onSetup::call(SomePlugin);
|
||||
if (EventHandler_onSetup::shouldAbortOnConsumedEvent() &&
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) {
|
||||
return result;
|
||||
}
|
||||
|
||||
result = EventHandler_onSetup::call(ExampleEffect);
|
||||
if (EventHandler_onSetup::shouldAbortOnConsumedEvent() &&
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) {
|
||||
return result;
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
This is starting to look human readable, doesn't it? But we can go further,
|
||||
because `EventHandler::onSetup::call` and
|
||||
`EventHandler_onSetup::shouldAbortOnConsumedEvent` are evaluated at compile-time
|
||||
too!
|
||||
|
||||
```c++
|
||||
EventHandlerResult kaleidoscope::Hooks::onSetup() {
|
||||
kaleidoscope::EventHandlerResult result;
|
||||
|
||||
result = SomePlugin.onSetup();
|
||||
if (false &&
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) {
|
||||
return result;
|
||||
}
|
||||
|
||||
result = ExampleEffect.onSetup();
|
||||
if (false &&
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) {
|
||||
return result;
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
Which in turn, may be optimized further to something like the following:
|
||||
|
||||
```c++
|
||||
EventHandlerResult kaleidoscope::Hooks::onSetup() {
|
||||
kaleidoscope::EventHandlerResult result;
|
||||
|
||||
result = SomePlugin.onSetup();
|
||||
result = ExampleEffect.onSetup();
|
||||
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
And this, is the end of the magic. This is roughly how much the code gets
|
||||
transformed *at compile time*, so that at run-time, none of this indirection is
|
||||
present.
|
||||
|
||||
## Summary
|
||||
|
||||
As we can see, there is a lot going on behind the scenes, and a combination of
|
||||
template meta programming and pre-processor macros is used to accomplish our
|
||||
goal. But following the code path like we did above allows us to see what the
|
||||
compiler sees (more or less), and inlining all the things that are done
|
||||
compile-time gives us the final code, which is pretty simple by that point.
|
||||
@ -0,0 +1,57 @@
|
||||
#pragma once
|
||||
|
||||
// This file defines the names and argument signatures for all event handlers
|
||||
// in the Kaleidoscope core.
|
||||
//
|
||||
// When adding a new hook or event handler to Kaleidoscope, it needs only
|
||||
// to be added here and to the place in the codebase where it should be called.
|
||||
//
|
||||
// _FOR_EACH_EVENT_HANDLER is what's called an "X Macro". Its first argument,
|
||||
// OPERATION, is the name of another macro. When called, it will execute
|
||||
// OPERATION once for each event handler defined herein with the following
|
||||
// parameters:
|
||||
//
|
||||
// HOOK_NAME, SHOULD_ABORT_ON_CONSUMED_EVENT, SIGNATURE, ARGS_LIST, ...
|
||||
//
|
||||
// Any additional parameters that are added to an invokation
|
||||
// of _FOR_EACH_EVENT_HANDLER are passed through to OP.
|
||||
|
||||
#define _ABORTABLE true
|
||||
#define _NOT_ABORTABLE false
|
||||
|
||||
#define _FOR_EACH_EVENT_HANDLER(OPERATION, ...) __NL__ \
|
||||
__NL__ \
|
||||
OPERATION(onSetup, __NL__ \
|
||||
_NOT_ABORTABLE, __NL__ \
|
||||
(),(), ##__VA_ARGS__) __NL__ \
|
||||
__NL__ \
|
||||
/* Called at the very start of each cycle, before gathering */ __NL__ \
|
||||
/* events, before doing anything else. */ __NL__ \
|
||||
OPERATION(beforeEachCycle, __NL__ \
|
||||
_NOT_ABORTABLE, __NL__ \
|
||||
(), (), ##__VA_ARGS__) __NL__ \
|
||||
__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__ \
|
||||
_ABORTABLE, __NL__ \
|
||||
(Key &mappedKey, byte row, byte col, uint8_t keyState), __NL__ \
|
||||
(mappedKey, row, col, keyState), ##__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__ \
|
||||
_NOT_ABORTABLE, __NL__ \
|
||||
(),(),##__VA_ARGS__) __NL__ \
|
||||
__NL__ \
|
||||
/* Called at the very end of a cycle, after everything's */ __NL__ \
|
||||
/* said and done. */ __NL__ \
|
||||
OPERATION(afterEachCycle, __NL__ \
|
||||
_NOT_ABORTABLE, __NL__ \
|
||||
(),(),##__VA_ARGS__)
|
||||
@ -0,0 +1,11 @@
|
||||
#pragma once
|
||||
|
||||
namespace kaleidoscope {
|
||||
|
||||
enum class EventHandlerResult {
|
||||
OK,
|
||||
EVENT_CONSUMED,
|
||||
ERROR,
|
||||
};
|
||||
|
||||
}
|
||||
@ -0,0 +1,27 @@
|
||||
#include "kaleidoscope/hooks.h"
|
||||
|
||||
namespace kaleidoscope {
|
||||
|
||||
// The following weak symbols are overwritten by
|
||||
// using the KALEIDOSCOPE_INIT_PLUGINS(...) macro
|
||||
// in the the firmware sketch. Their only purpose is
|
||||
// to provide backwards compatibility during the transition
|
||||
// from the old implementation of the hooking/plugin system
|
||||
// to the new one. The weak symbols ensure that there
|
||||
// are no undefined symbols if KALEIDOSCOPE_INIT_PLUGINS(...)
|
||||
// is not used. This allows legacy sketches to be used
|
||||
// during the transition phase.
|
||||
|
||||
#define INSTANTIATE_WEAK_HOOK_FUNCTION( \
|
||||
HOOK_NAME, SHOULD_ABORT_ON_CONSUMED_EVENT, SIGNATURE, ARGS_LIST) __NL__ \
|
||||
__NL__ \
|
||||
__attribute__((weak)) __NL__ \
|
||||
EventHandlerResult Hooks::HOOK_NAME SIGNATURE { __NL__ \
|
||||
return EventHandlerResult::OK; __NL__ \
|
||||
}
|
||||
|
||||
_FOR_EACH_EVENT_HANDLER(INSTANTIATE_WEAK_HOOK_FUNCTION)
|
||||
|
||||
#undef INSTANTIATE_WEAK_HOOK_FUNCTION
|
||||
|
||||
} // namespace kaleidoscope
|
||||
@ -0,0 +1,56 @@
|
||||
#pragma once
|
||||
|
||||
#include <Arduino.h>
|
||||
|
||||
namespace kaleidoscope {
|
||||
union Key;
|
||||
}
|
||||
|
||||
#include "plugin.h"
|
||||
#include "event_handlers.h"
|
||||
|
||||
// Forward declaration required to enable friend declarations
|
||||
// in class Hooks.
|
||||
class kaleidoscope_;
|
||||
extern void handleKeyswitchEvent(kaleidoscope::Key mappedKey, byte row, byte col, uint8_t keyState);
|
||||
|
||||
namespace kaleidoscope {
|
||||
|
||||
// The reason why the hook routing entry point functions live within
|
||||
// class Hooks and not directly within a namespace is, that we want
|
||||
// to restrict who is allowed to trigger hooks, mainly to prevent
|
||||
// user code from calling hook methods.
|
||||
//
|
||||
// A note to maintainers: When you add new hooks that are supposed to
|
||||
// be called from other places than the friend classes and functions listed
|
||||
// below, just add a suitable friend declaration.
|
||||
|
||||
class Hooks {
|
||||
|
||||
// The following friend declarations restrict access to
|
||||
// the hook routing system.
|
||||
|
||||
// Kaleidoscope_ calls Hooks::onSetup, Hooks::beforeReportingState
|
||||
// and Hooks::afterEachCycle.
|
||||
friend class Kaleidoscope_;
|
||||
|
||||
// ::handleKeyswitchEvent(...) calls Hooks::onKeyswitchEvent.
|
||||
friend void ::handleKeyswitchEvent(kaleidoscope::Key mappedKey,
|
||||
byte row, byte col, uint8_t keyState);
|
||||
|
||||
private:
|
||||
|
||||
// The following private functions are just to be called by classes
|
||||
// and functions that are declared as friends above.
|
||||
|
||||
#define DEFINE_WEAK_HOOK_FUNCTION( \
|
||||
HOOK_NAME, SHOULD_ABORT_ON_CONSUMED_EVENT, SIGNATURE, ARGS_LIST) __NL__ \
|
||||
__NL__ \
|
||||
static EventHandlerResult HOOK_NAME SIGNATURE;
|
||||
|
||||
_FOR_EACH_EVENT_HANDLER(DEFINE_WEAK_HOOK_FUNCTION)
|
||||
|
||||
#undef DEFINE_WEAK_HOOK_FUNCTION
|
||||
};
|
||||
|
||||
}
|
||||
@ -0,0 +1,133 @@
|
||||
/*
|
||||
* This file contains pre-processor macros, which are not namespaced, the
|
||||
* vast majority of code these macros generate will live under the
|
||||
* kaleidoscope_internal namespace. That is why this header is here.
|
||||
*
|
||||
* The only exception to this is the _KALEIDOSCOPE_INIT_PLUGINS macro, which
|
||||
* also places a few symbols under the kaleidoscope namespace. But that code is
|
||||
* tightly coupled with the other parts, which are in kaleidoscope_internal.
|
||||
*
|
||||
* The reason we use an entirely separate namespace is that
|
||||
* Some plugins' classes are in the kaleidoscope namespace, and the instances
|
||||
* of those classes have the same names as the classes, but in the global
|
||||
* namespace. In these cases, the macros herein would resolve to the classes,
|
||||
* when we want them to resolve to instances. To avoid this, we put the
|
||||
* generated code in an entirely different namespace.
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "macro_helpers.h"
|
||||
#include "plugin.h"
|
||||
#include "kaleidoscope/hooks.h"
|
||||
#include "eventhandler_signature_check.h"
|
||||
#include "event_handlers.h"
|
||||
|
||||
// Some words about the design of hook routing:
|
||||
//
|
||||
// The EventDispatcher class implements a compile-time loop over all plugins, which
|
||||
// calls an event handler on each plugin.
|
||||
//
|
||||
// Each hook called by the firmware core compiles down to only a single
|
||||
// static function call (in class Hooks), rather than one for each plugin.
|
||||
//
|
||||
// This approach is better than using virtual event handlers in classes
|
||||
// derived from kaleidoscope::Plugin because it results in significantly fewer
|
||||
// virtual function calls and virtual function tables (vtables).
|
||||
//
|
||||
// The call to event handlers through kaleidoscope::Hooks and
|
||||
// kaleidoscope_internal::EventDispatcher is templated to allow for compile time
|
||||
// static polymorphisms (plugins' EventHandlers aren't virtual).
|
||||
//
|
||||
// Technically, plugins don't need to be derived from kaleidoscope::Plugin, but
|
||||
// only need to implement a set of event handlers whose call signature match the
|
||||
// API definition. This approach is similar to duck typing in scripting languages:
|
||||
// The compiler only cares that a method's signature matches, not that the plugin
|
||||
// is derived from kaleidoscope::Plugin.
|
||||
//
|
||||
// Static hook functions inside the Hooks class each use the EventDispatcher
|
||||
// helper class to cast an associated EventHandler on each plugin instance.
|
||||
|
||||
|
||||
// This defines an auxiliary class 'EventHandler_Foo' for each hook 'Foo'.
|
||||
// Kaleidoscope::Hooks calls the EventDispatcher class, which in turn invokes
|
||||
// the event handler method 'Foo' of each registered plugin with a given
|
||||
// set of arguments.
|
||||
|
||||
#define _REGISTER_EVENT_HANDLER( \
|
||||
HOOK_NAME, SHOULD_ABORT_ON_CONSUMED_EVENT, SIGNATURE, ARGS_LIST) __NL__ \
|
||||
__NL__ \
|
||||
namespace kaleidoscope_internal { __NL__ \
|
||||
__NL__ \
|
||||
struct EventHandler_##HOOK_NAME { __NL__ \
|
||||
__NL__ \
|
||||
static bool shouldAbortOnConsumedEvent() { __NL__ \
|
||||
return SHOULD_ABORT_ON_CONSUMED_EVENT; __NL__ \
|
||||
} __NL__ \
|
||||
__NL__ \
|
||||
template<typename Plugin__, typename... Args__> __NL__ \
|
||||
static kaleidoscope::EventHandlerResult __NL__ \
|
||||
call(Plugin__ &plugin, Args__&&... hook_args) { __NL__ \
|
||||
_VALIDATE_EVENT_HANDLER_SIGNATURE(HOOK_NAME, Plugin__) __NL__ \
|
||||
return plugin.HOOK_NAME(hook_args...); __NL__ \
|
||||
} __NL__ \
|
||||
}; __NL__ \
|
||||
__NL__ \
|
||||
} __NL__ \
|
||||
__NL__ \
|
||||
namespace kaleidoscope { __NL__ \
|
||||
__NL__ \
|
||||
EventHandlerResult Hooks::HOOK_NAME SIGNATURE { __NL__ \
|
||||
return kaleidoscope_internal::EventDispatcher::template __NL__ \
|
||||
apply<kaleidoscope_internal::EventHandler_ ## HOOK_NAME> __NL__ \
|
||||
ARGS_LIST; __NL__ \
|
||||
} __NL__ \
|
||||
__NL__ \
|
||||
}
|
||||
|
||||
#define _INLINE_EVENT_HANDLER_FOR_PLUGIN(PLUGIN) \
|
||||
__NL__ \
|
||||
result = EventHandler__::call(PLUGIN, hook_args...); __NL__ \
|
||||
__NL__ \
|
||||
if (EventHandler__::shouldAbortOnConsumedEvent() && __NL__ \
|
||||
result == kaleidoscope::EventHandlerResult::EVENT_CONSUMED) { __NL__ \
|
||||
return result; __NL__ \
|
||||
} __NL__
|
||||
|
||||
// _KALEIDOSCOPE_INIT_PLUGINS builds the loops that execute the plugins'
|
||||
// implementations of the various event handlers.
|
||||
//
|
||||
// Its arguments are a list of references to plugin instances that have been
|
||||
// instantiated in the global scope.
|
||||
|
||||
// EventDispatcher::apply() implements a compile time for-each loop over all
|
||||
// plugins. The compiler automatically optimizes away calls to any plugin that
|
||||
// doesn't implement an EventHandler for a given hook.
|
||||
|
||||
#define _KALEIDOSCOPE_INIT_PLUGINS(...) __NL__ \
|
||||
namespace kaleidoscope_internal { __NL__ \
|
||||
struct EventDispatcher { __NL__ \
|
||||
__NL__ \
|
||||
/* Iterate through plugins, calling each one's event handler with */ __NL__ \
|
||||
/* the arguments passed to the hook */ __NL__ \
|
||||
template<typename EventHandler__, typename... Args__ > __NL__ \
|
||||
static kaleidoscope::EventHandlerResult apply(Args__&&... hook_args) { __NL__ \
|
||||
__NL__ \
|
||||
kaleidoscope::EventHandlerResult result; __NL__ \
|
||||
MAP(_INLINE_EVENT_HANDLER_FOR_PLUGIN, __VA_ARGS__) __NL__ \
|
||||
__NL__ \
|
||||
return result; __NL__ \
|
||||
} __NL__ \
|
||||
}; __NL__ \
|
||||
__NL__ \
|
||||
} __NL__ \
|
||||
/* We register event handlers here - which is not technically related */ __NL__ \
|
||||
/* to initialization, nor is it in the same namespace - to support the */ __NL__ \
|
||||
/* transition from the old APIs. When the user sketch does not use */ __NL__ \
|
||||
/* KALEIDOSCOPE_INIT_PLUGINS(), the event handlers will not exist */ __NL__ \
|
||||
/* either, thus wrapping them would produce a compile error. For this */ __NL__ \
|
||||
/* reason, we do the wrapping here, tied to _KALEIDOSCOPE_INIT_PLUGINS. */ __NL__ \
|
||||
/* */ __NL__ \
|
||||
/* TODO(anyone): Move this somewhere else, outside of _internal, once */ __NL__ \
|
||||
/* the V1 API is removed. */ __NL__ \
|
||||
_FOR_EACH_EVENT_HANDLER(_REGISTER_EVENT_HANDLER)
|
||||
@ -0,0 +1,124 @@
|
||||
#pragma once
|
||||
|
||||
#include "macro_helpers.h"
|
||||
#include "plugin.h"
|
||||
|
||||
|
||||
// *************************************************************************
|
||||
// *************************************************************************
|
||||
// NOTHING IN THIS HEADER WILL RESULT IN ANY CODE COMPILED INTO KALEIDOSCOPE
|
||||
//
|
||||
// YOU DO NOT NEED TO LOOK INSIDE THIS FILE IF YOU'RE TRYING TO UNDERSTAND
|
||||
// HOW KALEIDOSCOPE WORKS.
|
||||
// *************************************************************************
|
||||
// *************************************************************************
|
||||
|
||||
// This header file implements compile-time method signature verification for
|
||||
// plugins' event handlers as the _VALIDATE_EVENT_HANDLER_SIGNATURE macro.
|
||||
|
||||
// If the method signatures don't match the API definitions, compilation
|
||||
// should fail with a helpful error message.
|
||||
|
||||
// *************************************************************************
|
||||
// *************************************************************************
|
||||
|
||||
// We use non-virtual methods for event handlers. This reduces RAM (and to a
|
||||
// smaller extent, PROGMEM) consumption, runtime call overhead, and allows the
|
||||
// compiler to a better job removing dead code.
|
||||
//
|
||||
// The downside is that event handler methods in derived plugins are hidden,
|
||||
// rather than overridden. Because only virtual methods can be overridden, we
|
||||
// can't apply C++'s `override` keyword to hook methods.
|
||||
//
|
||||
// To make it easier to debug issues with plugins' event handler method
|
||||
// signatures, the _VALIDATE_EVENT_HANDLER_SIGNATURE macro compares a plugin's
|
||||
// event handler signatures with those of the kaleidoscope::Plugin baseclass. If
|
||||
// any differences are detected, it outputs a compile-time error message.
|
||||
//
|
||||
// Ideally, we'd be able to use this (much simpler) code.
|
||||
//
|
||||
// decltype(&::kaleidoscope::Plugin::fooEventHandler)
|
||||
// == decltype(&childPlugin::fooEventHandler)
|
||||
//
|
||||
// Unfortunately, this is not possible with C++-11, as it does not allow
|
||||
// comparing function-types for equality. As a workaround, we can use the trait
|
||||
// class EventHandlerSignaturesMatch to perform the comparison.
|
||||
//
|
||||
// It defines the bool constant 'value' as true if both signatures match.
|
||||
// It checks the return value, argument types and const specification.
|
||||
// (As of this writing, we don't have any const hook method.)
|
||||
|
||||
template<typename T1, typename T2>
|
||||
struct EventHandlerSignaturesMatch {
|
||||
static constexpr bool value = false;
|
||||
};
|
||||
|
||||
// R: The return value,
|
||||
// T1: Type of the first class (plugin),
|
||||
// T2: Type of the second class (plugin),
|
||||
// EventHandlerArgs: Variadic types of plugin event handler arguments.
|
||||
|
||||
template<typename R, typename T1, typename T2, typename... EventHandlerArgs>
|
||||
struct EventHandlerSignaturesMatch<R(T1::*)(EventHandlerArgs...), R(T2::*)(EventHandlerArgs...)> {
|
||||
static constexpr bool value = true;
|
||||
};
|
||||
|
||||
// Equivalent to allow for const-eventhandlers, e.g. bool getFooEventHandler() const
|
||||
template<typename R, typename T1, typename T2, typename... EventHandlerArgs> struct
|
||||
EventHandlerSignaturesMatch<R(T1::*)(EventHandlerArgs...) const, R(T2::*)(EventHandlerArgs...) const> {
|
||||
static constexpr bool value = true;
|
||||
};
|
||||
|
||||
// This template is instantiated when something goes wrong.
|
||||
// Because it does not define a constant 'value', it triggers a compiler error.
|
||||
|
||||
template<typename Plugin__, bool result> struct
|
||||
___________Culprit_Plugin___________ { };
|
||||
|
||||
// This specialization is instantiated when everything is ok.
|
||||
template<typename Plugin__> struct
|
||||
___________Culprit_Plugin___________ <Plugin__, true> {
|
||||
static constexpr bool value = true;
|
||||
};
|
||||
|
||||
// If the pointer types are the same, the signatures match, causing
|
||||
// the first or second specialization to be instantiated. This makes
|
||||
// the causes the compile time constant `value` to be defined as `true`.
|
||||
// Otherwise, the unspecialized version of the template class is instantiated
|
||||
// and `value` is defined as `false`
|
||||
|
||||
#define _VALIDATE_EVENT_HANDLER_SIGNATURE(EVENTHANDLER, PLUGIN) \
|
||||
{ __NL__ \
|
||||
/* Check if the signatures match. If not, the plugin has implemented */ __NL__ \
|
||||
/* a method with a hook's name, but a different signature. */ __NL__ \
|
||||
typedef EventHandlerSignaturesMatch< __NL__ \
|
||||
decltype(&::kaleidoscope::Plugin::EVENTHANDLER), __NL__ \
|
||||
decltype(&PLUGIN::EVENTHANDLER) __NL__ \
|
||||
> Check; __NL__ \
|
||||
__NL__ \
|
||||
static_assert(Check::value, __NL__ \
|
||||
VERBOSE_STATIC_ASSERT_HEADER __NL__ \
|
||||
"\nOne of your plugins implemented the \"" #EVENTHANDLER "\"" __NL__ \
|
||||
"\nevent handler, but its signature didn't match the base class." __NL__ \
|
||||
"\n" __NL__ \
|
||||
"\nThe plugin with this issue will be marked in the compiler" __NL__ \
|
||||
"\noutput with the string:" __NL__ \
|
||||
"\n" __NL__ \
|
||||
"\n ___________Culprit_Plugin___________." __NL__ \
|
||||
"\n" __NL__ \
|
||||
"\nYou should compare the event handlers implemented in this plugin" __NL__ \
|
||||
"\nto those in \"kaleidoscope::Plugin\"." __NL__ \
|
||||
"\n" __NL__ \
|
||||
"\nAll of the event handler's argument types, return values and" __NL__ \
|
||||
"\nconst qualifiers need to match." __NL__ \
|
||||
"\n" __NL__ \
|
||||
VERBOSE_STATIC_ASSERT_FOOTER __NL__ \
|
||||
); __NL__ \
|
||||
__NL__ \
|
||||
/* The following construct is necessary enable reporting of the */ __NL__ \
|
||||
/* type of a plugin that implements an event handler with an */ __NL__ \
|
||||
/* incorrect signature, because it's not possible to include any */ __NL__ \
|
||||
/* non-literal string constant in a static_assert error message. */ __NL__ \
|
||||
constexpr bool dummy = ___________Culprit_Plugin___________ __NL__ \
|
||||
<PLUGIN, Check::value>::value; __NL__ \
|
||||
}
|
||||
@ -0,0 +1,67 @@
|
||||
/*
|
||||
* Copyright (C) 2012 William Swanson
|
||||
*
|
||||
* Permission is hereby granted, free of charge, to any person
|
||||
* obtaining a copy of this software and associated documentation
|
||||
* files (the "Software"), to deal in the Software without
|
||||
* restriction, including without limitation the rights to use, copy,
|
||||
* modify, merge, publish, distribute, sublicense, and/or sell copies
|
||||
* of the Software, and to permit persons to whom the Software is
|
||||
* furnished to do so, subject to the following conditions:
|
||||
*
|
||||
* The above copyright notice and this permission notice shall be
|
||||
* included in all copies or substantial portions of the Software.
|
||||
*
|
||||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
|
||||
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
|
||||
* CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
*
|
||||
* Except as contained in this notice, the names of the authors or
|
||||
* their institutions shall not be used in advertising or otherwise to
|
||||
* promote the sale, use or other dealings in this Software without
|
||||
* prior written authorization from the authors.
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#define EVAL0(...) __VA_ARGS__
|
||||
#define EVAL1(...) EVAL0(EVAL0(EVAL0(__VA_ARGS__)))
|
||||
#define EVAL2(...) EVAL1(EVAL1(EVAL1(__VA_ARGS__)))
|
||||
#define EVAL3(...) EVAL2(EVAL2(EVAL2(__VA_ARGS__)))
|
||||
#define EVAL4(...) EVAL3(EVAL3(EVAL3(__VA_ARGS__)))
|
||||
#define EVAL(...) EVAL4(EVAL4(EVAL4(__VA_ARGS__)))
|
||||
|
||||
#define MAP_END(...)
|
||||
#define MAP_OUT
|
||||
#define MAP_COMMA ,
|
||||
|
||||
#define MAP_GET_END2() 0, MAP_END
|
||||
#define MAP_GET_END1(...) MAP_GET_END2
|
||||
#define MAP_GET_END(...) MAP_GET_END1
|
||||
#define MAP_NEXT0(test, next, ...) next MAP_OUT
|
||||
#define MAP_NEXT1(test, next) MAP_NEXT0(test, next, 0)
|
||||
#define MAP_NEXT(test, next) MAP_NEXT1(MAP_GET_END test, next)
|
||||
|
||||
#define MAP0(f, x, peek, ...) f(x) MAP_NEXT(peek, MAP1)(f, peek, __VA_ARGS__)
|
||||
#define MAP1(f, x, peek, ...) f(x) MAP_NEXT(peek, MAP0)(f, peek, __VA_ARGS__)
|
||||
|
||||
#define MAP_LIST_NEXT1(test, next) MAP_NEXT0(test, MAP_COMMA next, 0)
|
||||
#define MAP_LIST_NEXT(test, next) MAP_LIST_NEXT1(MAP_GET_END test, next)
|
||||
|
||||
#define MAP_LIST0(f, x, peek, ...) f(x) MAP_LIST_NEXT(peek, MAP_LIST1)(f, peek, __VA_ARGS__)
|
||||
#define MAP_LIST1(f, x, peek, ...) f(x) MAP_LIST_NEXT(peek, MAP_LIST0)(f, peek, __VA_ARGS__)
|
||||
|
||||
/**
|
||||
* Applies the function macro `f` to each of the remaining parameters.
|
||||
*/
|
||||
#define MAP(f, ...) EVAL(MAP1(f, __VA_ARGS__, ()()(), ()()(), ()()(), 0))
|
||||
|
||||
/**
|
||||
* Applies the function macro `f` to each of the remaining parameters and
|
||||
* inserts commas between the results.
|
||||
*/
|
||||
#define MAP_LIST(f, ...) EVAL(MAP_LIST1(f, __VA_ARGS__, ()()(), ()()(), ()()(), 0))
|
||||
@ -0,0 +1,94 @@
|
||||
#pragma once
|
||||
|
||||
#include "kaleidoscope/event_handler_result.h"
|
||||
#include "kaleidoscope_internal/event_dispatch.h"
|
||||
#include "event_handlers.h"
|
||||
|
||||
#ifndef KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
|
||||
#define KALEIDOSCOPE_ENABLE_V1_PLUGIN_API 1
|
||||
#endif
|
||||
|
||||
namespace kaleidoscope {
|
||||
|
||||
class Kaleidoscope_;
|
||||
|
||||
// A base class that implements default noop versions of all event
|
||||
// handler methods.
|
||||
//
|
||||
// A note to developers:
|
||||
//
|
||||
// The only purpose of class EventHandlerBasePlugin
|
||||
// is to enable the use of _FOR_EACH_EVENT_HANDLER
|
||||
// to define default event handlers. This is currently not possible
|
||||
// inside class Plugin directly as it would collide with
|
||||
// the separate definition of onSetup(). This additional
|
||||
// definition is, however, necessary to support the V1 plugin API.
|
||||
//
|
||||
// TODO(anyone): As soon as the V1 plugin API is removed from Kaleidoscope,
|
||||
// class EventHandlerBasePlugin can be removed and its content be moved to
|
||||
// class Plugin.
|
||||
//
|
||||
class EventHandlerBasePlugin {
|
||||
|
||||
public:
|
||||
|
||||
#define DEFINE_AND_IMPLEMENT_EVENT_HANDLER_METHOD( \
|
||||
HOOK_NAME, SHOULD_ABORT_ON_CONSUMED_EVENT, SIGNATURE, ARGS_LIST) __NL__ \
|
||||
__NL__ \
|
||||
EventHandlerResult HOOK_NAME SIGNATURE { __NL__ \
|
||||
return EventHandlerResult::OK; __NL__ \
|
||||
}
|
||||
|
||||
_FOR_EACH_EVENT_HANDLER(DEFINE_AND_IMPLEMENT_EVENT_HANDLER_METHOD)
|
||||
|
||||
#undef DEFINE_AND_IMPLEMENT_EVENT_HANDLER_METHOD
|
||||
};
|
||||
|
||||
class Plugin : public EventHandlerBasePlugin {
|
||||
|
||||
friend class Kaleidoscope_;
|
||||
|
||||
protected:
|
||||
|
||||
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
|
||||
/** Legacy plugin setup hook.
|
||||
|
||||
* In version one of the plugin API, `plugin->begin()` was called at
|
||||
* `Kaleidoscope.use()` time, to perform boot-time initialization. We needed
|
||||
* this because plugins are supposed to provide a singleton object, statically
|
||||
* initialized at compile-time (with few exceptions). Because of this, the
|
||||
* order in which they are instantiated is unspecified, and cannot be relied
|
||||
* upon. For this reason, one's expected to explicitly initialize, "use" the
|
||||
* plugins one wishes to, by calling `Kaleidoscope.use()` with a list of
|
||||
* plugin object pointers.
|
||||
*
|
||||
* This is the only time this function will be called. It is intentionally
|
||||
* protected, and accessible by the `Kaleidoscope` class only.
|
||||
*
|
||||
* Also, this method is deprecated in favour of the V2 API, which you can read
|
||||
* about below.
|
||||
*/
|
||||
virtual void begin() {}
|
||||
#endif
|
||||
|
||||
public:
|
||||
// Please see "event_handlers.h" for a list of supported event handlers and
|
||||
// their documentation!
|
||||
|
||||
EventHandlerResult onSetup() {
|
||||
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
|
||||
// By letting the new `onSetup()` method call the legacy begin() method, we
|
||||
// make sure that the old hooking interface is supported even if
|
||||
// KALEIDOSCOPE_INIT_PLUGINS() is used to register a plugin that relies on
|
||||
// the legacy `begin()` method to initialize itself and register hooks.
|
||||
//
|
||||
this->begin();
|
||||
#endif
|
||||
return EventHandlerResult::OK;
|
||||
}
|
||||
|
||||
};
|
||||
|
||||
} // namespace kaleidoscope
|
||||
|
||||
typedef kaleidoscope::Plugin KaleidoscopePlugin __attribute__((deprecated("class KaleidoscopePlugin is deprecated. Please derive plugins from kaleidoscope::Plugin instead.")));
|
||||
Loading…
Reference in new issue