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

Merge pull request #354 from keyboardio/f/v1-plugin-api-removal

Browse Source 
Drop the V1 Plugin API
pull/355/head
Gergely Nagy 6 years ago committed by GitHub
parent 526b0e430d 297dab5c74
commit 568355b8a5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 15 additions and 303 deletions
Show Stats Download Patch File Download Diff File

8
UPGRADING.md
Unescape View File

@ -71,7 +71,10 @@ 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 .ino sketch, do not hesitate to write us at help@keyboard.io, we can help you
fix it. fix it.
### Scheduled for removal by 2018-08-20 Deprecated and removed APIs
---------------------------
### Removed on 2018-08-20
We aim at making a new release by mid-July, and APIs we deprecate now, will be We aim at making a new release by mid-July, and APIs we deprecate now, will be
removed shortly after the major release, before the next point release. We may removed shortly after the major release, before the next point release. We may
@ -145,9 +148,6 @@ Plugins are supposed to implement this new API, and then be initialised via
A key with a typo in its name, which was left in place after fixing the typo, so A key with a typo in its name, which was left in place after fixing the typo, so
as to not break any code that may be using it already, however unlikely. as to not break any code that may be using it already, however unlikely.
Deprecated and removed APIs
---------------------------
### Removed on 2018-06-10 (originally scheduled for 2018-05-27) ### Removed on 2018-06-10 (originally scheduled for 2018-05-27)
These APIs and functions have been deprecated for a long time, and as far as we These APIs and functions have been deprecated for a long time, and as far as we

79
src/Kaleidoscope.cpp
Unescape View File

@ -3,11 +3,6 @@
namespace kaleidoscope { namespace kaleidoscope {
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
Kaleidoscope_::eventHandlerHook Kaleidoscope_::eventHandlers[HOOK_MAX];
Kaleidoscope_::loopHook Kaleidoscope_::loopHooks[HOOK_MAX];
#endif
uint32_t Kaleidoscope_::millis_at_cycle_start_; uint32_t Kaleidoscope_::millis_at_cycle_start_;
Kaleidoscope_::Kaleidoscope_(void) { Kaleidoscope_::Kaleidoscope_(void) {
@ -47,23 +42,9 @@ Kaleidoscope_::loop(void) {
kaleidoscope::Hooks::beforeReportingState(); kaleidoscope::Hooks::beforeReportingState();
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
for (byte i = 0; loopHooks[i] != NULL && i < HOOK_MAX; i++) {
loopHook hook = loopHooks[i];
(*hook)(false);
}
#endif
kaleidoscope::hid::sendKeyboardReport(); kaleidoscope::hid::sendKeyboardReport();
kaleidoscope::hid::releaseAllKeys(); kaleidoscope::hid::releaseAllKeys();
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
for (byte i = 0; loopHooks[i] != NULL && i < HOOK_MAX; i++) {
loopHook hook = loopHooks[i];
(*hook)(true);
}
#endif
kaleidoscope::Hooks::afterEachCycle(); kaleidoscope::Hooks::afterEachCycle();
} }
@ -110,64 +91,4 @@ Kaleidoscope_::focusHook(const char *command) {
Kaleidoscope_ Kaleidoscope; Kaleidoscope_ Kaleidoscope;
/* Deprecated functions */
/* Disable deprecation warnings for these, we only want to have those at
* non-internal call sites. */
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
void
Kaleidoscope_::replaceEventHandlerHook(eventHandlerHook oldHook, eventHandlerHook newHook) {
for (byte i = 0; i < HOOK_MAX; i++) {
if (eventHandlers[i] == oldHook) {
eventHandlers[i] = newHook;
return;
}
}
}
void
Kaleidoscope_::appendEventHandlerHook(eventHandlerHook hook) {
replaceEventHandlerHook((eventHandlerHook)NULL, hook);
}
void
Kaleidoscope_::useEventHandlerHook(eventHandlerHook hook) {
for (byte i = 0; i < HOOK_MAX; i++) {
if (eventHandlers[i] == hook)
return;
}
appendEventHandlerHook(hook);
}
void
Kaleidoscope_::replaceLoopHook(loopHook oldHook, loopHook newHook) {
for (byte i = 0; i < HOOK_MAX; i++) {
if (loopHooks[i] == oldHook) {
loopHooks[i] = newHook;
return;
}
}
}
void
Kaleidoscope_::appendLoopHook(loopHook hook) {
replaceLoopHook((loopHook)NULL, hook);
}
void
Kaleidoscope_::useLoopHook(loopHook hook) {
for (byte i = 0; i < HOOK_MAX; i++) {
if (loopHooks[i] == hook)
return;
}
appendLoopHook(hook);
}
#endif
#pragma GCC diagnostic pop // restore diagnostic options
} // namespace kaleidoscope } // namespace kaleidoscope

77
src/Kaleidoscope.h
Unescape View File

@ -26,7 +26,6 @@ void setup();
#include "layers.h" #include "layers.h"
#include "macro_map.h" #include "macro_map.h"
#include "kaleidoscope_internal/event_dispatch.h" #include "kaleidoscope_internal/event_dispatch.h"
#include "kaleidoscope_internal/deprecations.h"
#include "macro_helpers.h" #include "macro_helpers.h"
#include "plugin.h" #include "plugin.h"
@ -109,82 +108,6 @@ class Kaleidoscope_ {
return millis_at_cycle_start_; return millis_at_cycle_start_;
} }
// ---- Kaleidoscope.use() ----
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
// First, we have the zero-argument version, which will satisfy the tail case.
inline void use() {
}
// Then, the one-argument version, that gives us type safety for a single
// plugin.
inline void DEPRECATED(USE) use(kaleidoscope::Plugin *p) {
p->begin();
}
// We have a no-op with a int argument, as a temporary hack until we remove
// the last instance of a NULL-terminated Kaleidoscope.use() call.
inline void use(int) {
}
// And the magic is in the last one, a template. The first parameter is
// matched out by the compiler, and passed to one of the functions above. The
// rest of the parameter pack (which may be an empty set in a recursive case),
// are passed back to either ourselves, or the zero-argument version a few
// lines above.
template <typename... Plugins>
void DEPRECATED(USE) use(kaleidoscope::Plugin *first, Plugins&&... plugins) {
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
use(first);
use(plugins...);
#pragma GCC diagnostic pop
}
#else
// NOTE: Do **NOT** remove this when sunsetting the V1 API!
template <typename Plugin__>
inline void use(Plugin__ first, ...) {
static_assert(sizeof(Plugin__) < 0, _DEPRECATE(_DEPRECATED_MESSAGE_USE));
}
#endif
// ---- hooks ----
/*
* In most cases, one only wants a single copy of a hook. On the other hand,
* plugins that depend on other plugins, may want to make it easier for the
* end-user to use the plugin, and call the setup function of the dependent
* plugins too. In case the end-user calls the same setup function, we'd end up
* with hooks registered multiple times.
*
* To avoid this, protection against double-registration has been introduced.
* The `event_handler_hook_use` and `loop_hook_use` functions will only allow
* one copy of the hook. The `event_handler_hook_append` and `loop_hook_append`
* functions will, on the other hand, just append the hooks, and not care about
* protection.
*/
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
typedef Key(*eventHandlerHook)(Key mappedKey, byte row, byte col, uint8_t keyState);
typedef void (*loopHook)(bool postClear);
static eventHandlerHook eventHandlers[HOOK_MAX];
static loopHook loopHooks[HOOK_MAX];
static void replaceEventHandlerHook(eventHandlerHook oldHook, eventHandlerHook newHook)
DEPRECATED(EVENT_HANDLER_HOOK);
static void appendEventHandlerHook(eventHandlerHook hook)
DEPRECATED(EVENT_HANDLER_HOOK);
static void useEventHandlerHook(eventHandlerHook hook)
DEPRECATED(EVENT_HANDLER_HOOK);
static void replaceLoopHook(loopHook oldHook, loopHook newHook)
DEPRECATED(LOOP_HOOK);
static void appendLoopHook(loopHook hook)
DEPRECATED(LOOP_HOOK);
static void useLoopHook(loopHook hook)
DEPRECATED(LOOP_HOOK);
#endif
static bool focusHook(const char *command); static bool focusHook(const char *command);
private: private:

56
src/kaleidoscope_internal/deprecations.h
Unescape View File

@ -10,59 +10,3 @@
"------------------------------------------------------------------------\n" \ "------------------------------------------------------------------------\n" \
/* Messages */ /* Messages */
#define _DEPRECATED_MESSAGE_USE \
"Your sketch uses Kaleidoscope.use(), an old-style API to initialize\n" \
"plugins. To fix this, you need to modify your .ino sketch file, and\n" \
"replacing the text \"Kaleidoscope.use\" with \"KALEIDOSCOPE_INIT_PLUGINS\",\n" \
"then remove the & from all of the plugins inside it, and finally, move\n" \
"it outside of \"setup()\":\n" \
"\n" \
"If your current sketch looks like this: \n" \
" void setup() {\n" \
" Kaleidoscope.use(&Plugin1, &Plugin2);\n" \
" Kaleidoscope.setup();\n" \
" }\n" \
"\n" \
"You should change it so that it looks like this:\n" \
" KALEIDOSCOPE_INIT_PLUGINS(Plugin1, Plugin2);\n" \
" void setup() {\n" \
" Kaleidoscope.setup();\n" \
" }\n" \
"\n" \
"If this error doesn't make sense to you or you have any trouble, please\n" \
"send a copy of your .ino sketch file to help@keyboard.io and we can\n" \
"help fix it."
#define _DEPRECATED_MESSAGE_EVENT_HANDLER_HOOK \
"The legacy plugin API based on hook registration is deprecated.\n" \
"\n" \
"Consider upgrading your plugins, or implementing the new interface\n" \
"described by `kaleidoscope::Plugin`. In particular, instead of using\n" \
"`Kaleidoscope.useEventHandlerHook`, implement the\n" \
"`.onKeyswitchEvent()` method instead.\n" \
"\n" \
"If your plugins are up-to-date, and you are not a developer, it is\n" \
"usually safe to ignore this message. Especally if the full error\n" \
"points to a line containing `legacyLoopHook` or `legacyEventHandler`."
#define _DEPRECATED_MESSAGE_LOOP_HOOK \
"The legacy plugin API based on hook registration is deprecated.\n" \
"\n" \
"Consider upgrading your plugins, or implementing the new interface\n" \
"described by `kaleidoscope::Plugin`. In particular, instead of using\n" \
"`Kaleidoscope.useLoopHook`, implement `.beforeEachCycle`,\n" \
"`.beforeReportingState()`, or `.afterEachCycle()` instead.\n" \
"\n" \
"If your plugins are up-to-date, and you are not a developer, it is\n" \
"usually safe to ignore this message. Especally if the full error\n" \
"points to a line containing `legacyLoopHook` or `legacyEventHandler`."
#define _DEPRECATED_MESSAGE_USE_INSTEAD(new_method) \
"Please use `" new_method "` instead."
#define _DEPRECATED_MESSAGE_KALEIDOSCOPEPLUGIN \
"The `KaleidoscopePlugin` class is deprecated. Please derive plugins from\n" \
"`kaleidoscope::Plugin` instead."

1
src/key_defs_consumerctl.h
Unescape View File

@ -34,7 +34,6 @@
#define Consumer_VCRSlashTV CONSUMER_KEY(HID_CONSUMER_VCR_SLASH_TV, KEY_FLAGS | HID_TYPE_OOC ) #define Consumer_VCRSlashTV CONSUMER_KEY(HID_CONSUMER_VCR_SLASH_TV, KEY_FLAGS | HID_TYPE_OOC )
#define Consumer_BroadcastMode CONSUMER_KEY(HID_CONSUMER_BROADCAST_MODE, KEY_FLAGS | HID_TYPE_OSC ) #define Consumer_BroadcastMode CONSUMER_KEY(HID_CONSUMER_BROADCAST_MODE, KEY_FLAGS | HID_TYPE_OSC )
#define Consumer_Snapshot CONSUMER_KEY(HID_CONSUMER_SNAPSHOT, KEY_FLAGS | HID_TYPE_OSC ) #define Consumer_Snapshot CONSUMER_KEY(HID_CONSUMER_SNAPSHOT, KEY_FLAGS | HID_TYPE_OSC )
#define Consumer_SNapshot Consumer_Snapshot
#define Consumer_Still CONSUMER_KEY(HID_CONSUMER_STILL, KEY_FLAGS | HID_TYPE_OSC ) #define Consumer_Still CONSUMER_KEY(HID_CONSUMER_STILL, KEY_FLAGS | HID_TYPE_OSC )
#define Consumer_Selection CONSUMER_KEY(HID_CONSUMER_SELECTION, KEY_FLAGS | HID_TYPE_NARY ) #define Consumer_Selection CONSUMER_KEY(HID_CONSUMER_SELECTION, KEY_FLAGS | HID_TYPE_NARY )

11
src/key_events.cpp
Unescape View File

@ -95,18 +95,7 @@ void handleKeyswitchEvent(Key mappedKey, byte row, byte col, uint8_t keyState) {
// Keypresses with out-of-bounds (row,col) start here in the processing chain // Keypresses with out-of-bounds (row,col) start here in the processing chain
// Legacy event handlers
#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
for (byte i = 0; Kaleidoscope.eventHandlers[i] != NULL && i < HOOK_MAX; i++) {
Kaleidoscope_::eventHandlerHook handler = Kaleidoscope.eventHandlers[i];
mappedKey = (*handler)(mappedKey, row, col, keyState);
if (mappedKey.raw == Key_NoKey.raw)
return;
}
#endif
// New event handler interface // New event handler interface
//
if (kaleidoscope::Hooks::onKeyswitchEvent(mappedKey, row, col, keyState) != kaleidoscope::EventHandlerResult::OK) if (kaleidoscope::Hooks::onKeyswitchEvent(mappedKey, row, col, keyState) != kaleidoscope::EventHandlerResult::OK)
return; return;

74
src/plugin.h
Unescape View File

@ -2,36 +2,19 @@
#include "kaleidoscope/event_handler_result.h" #include "kaleidoscope/event_handler_result.h"
#include "kaleidoscope_internal/event_dispatch.h" #include "kaleidoscope_internal/event_dispatch.h"
#include "kaleidoscope_internal/deprecations.h"
#include "event_handlers.h" #include "event_handlers.h"
#ifndef KALEIDOSCOPE_ENABLE_V1_PLUGIN_API #if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API
#define KALEIDOSCOPE_ENABLE_V1_PLUGIN_API 1 #error The V1 plugin API has been removed, please see UPGRADING.md.
#endif #endif
namespace kaleidoscope { namespace kaleidoscope {
class Kaleidoscope_; class Plugin {
// 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: public:
// Please see "event_handlers.h" for a list of supported event handlers and
// their documentation!
#define DEFINE_AND_IMPLEMENT_EVENT_HANDLER_METHOD( \ #define DEFINE_AND_IMPLEMENT_EVENT_HANDLER_METHOD( \
HOOK_NAME, SHOULD_ABORT_ON_CONSUMED_EVENT, SIGNATURE, ARGS_LIST) __NL__ \ HOOK_NAME, SHOULD_ABORT_ON_CONSUMED_EVENT, SIGNATURE, ARGS_LIST) __NL__ \
@ -45,51 +28,4 @@ class EventHandlerBasePlugin {
#undef 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 } // namespace kaleidoscope
typedef kaleidoscope::Plugin KaleidoscopePlugin DEPRECATED(KALEIDOSCOPEPLUGIN);

Write Preview
Loading…
Cancel
Save