From 297dab5c7492410821159a3022fdc3c330c57d7f Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Mon, 20 Aug 2018 00:17:04 +0200 Subject: [PATCH] Drop the V1 Plugin API Scheduled for removal on 2018-08-20, this drops the V1 API and all deprecation messages. We only keep one message, that errors out in case `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` is set. Also drops `Consumer_SNapshot`, which was a typo'd name. `UPGRADING.md` updated accordingly. Signed-off-by: Gergely Nagy --- UPGRADING.md | 8 +-- src/Kaleidoscope.cpp | 79 ---------------------- src/Kaleidoscope.h | 77 --------------------- src/kaleidoscope_internal/deprecations.h | 56 --------------- src/key_defs_consumerctl.h | 1 - src/key_events.cpp | 11 --- src/plugin.h | 86 +++--------------------- 7 files changed, 15 insertions(+), 303 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index f25e5708..36b399c3 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -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 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 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 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) These APIs and functions have been deprecated for a long time, and as far as we diff --git a/src/Kaleidoscope.cpp b/src/Kaleidoscope.cpp index 83bb1774..f528c174 100644 --- a/src/Kaleidoscope.cpp +++ b/src/Kaleidoscope.cpp @@ -3,11 +3,6 @@ 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_; Kaleidoscope_::Kaleidoscope_(void) { @@ -47,23 +42,9 @@ Kaleidoscope_::loop(void) { 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::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(); } @@ -110,64 +91,4 @@ Kaleidoscope_::focusHook(const char *command) { 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 diff --git a/src/Kaleidoscope.h b/src/Kaleidoscope.h index ab5b1ed8..d4c3b379 100644 --- a/src/Kaleidoscope.h +++ b/src/Kaleidoscope.h @@ -26,7 +26,6 @@ void setup(); #include "layers.h" #include "macro_map.h" #include "kaleidoscope_internal/event_dispatch.h" -#include "kaleidoscope_internal/deprecations.h" #include "macro_helpers.h" #include "plugin.h" @@ -109,82 +108,6 @@ class Kaleidoscope_ { 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 - 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 - 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); private: diff --git a/src/kaleidoscope_internal/deprecations.h b/src/kaleidoscope_internal/deprecations.h index 4914a4d3..656489a4 100644 --- a/src/kaleidoscope_internal/deprecations.h +++ b/src/kaleidoscope_internal/deprecations.h @@ -10,59 +10,3 @@ "------------------------------------------------------------------------\n" \ /* 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." diff --git a/src/key_defs_consumerctl.h b/src/key_defs_consumerctl.h index 78cefe5d..c9c166b4 100644 --- a/src/key_defs_consumerctl.h +++ b/src/key_defs_consumerctl.h @@ -34,7 +34,6 @@ #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_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_Selection CONSUMER_KEY(HID_CONSUMER_SELECTION, KEY_FLAGS | HID_TYPE_NARY ) diff --git a/src/key_events.cpp b/src/key_events.cpp index 849916df..1b353cf7 100644 --- a/src/key_events.cpp +++ b/src/key_events.cpp @@ -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 - // 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 - // if (kaleidoscope::Hooks::onKeyswitchEvent(mappedKey, row, col, keyState) != kaleidoscope::EventHandlerResult::OK) return; diff --git a/src/plugin.h b/src/plugin.h index 8b491f74..5fd6f778 100644 --- a/src/plugin.h +++ b/src/plugin.h @@ -2,94 +2,30 @@ #include "kaleidoscope/event_handler_result.h" #include "kaleidoscope_internal/event_dispatch.h" -#include "kaleidoscope_internal/deprecations.h" #include "event_handlers.h" -#ifndef KALEIDOSCOPE_ENABLE_V1_PLUGIN_API -#define KALEIDOSCOPE_ENABLE_V1_PLUGIN_API 1 +#if KALEIDOSCOPE_ENABLE_V1_PLUGIN_API +#error The V1 plugin API has been removed, please see UPGRADING.md. #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 { +class Plugin { public: + // Please see "event_handlers.h" for a list of supported event handlers and + // their documentation! -#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__ \ - } +#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 DEPRECATED(KALEIDOSCOPEPLUGIN);