From 9182537fcfe3a78bd223e0510928bc863898e550 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Thu, 5 Oct 2017 12:37:36 +0200 Subject: [PATCH 1/2] Make KaleidoscopePlugin.begin protected by default Make `Kaleidoscope_` a friend class, so that it can access `.begin`. The reason behind this is that `.begin` is an interface towards `Kaleidoscope.use()`, and that function should be the only user. To discourage its use, make it protected. This does not break any existing - and valid - code, but allows us to slowly migrate the plugins to a protected `begin()` method. Fixes #177. Signed-off-by: Gergely Nagy --- src/Kaleidoscope.h | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/Kaleidoscope.h b/src/Kaleidoscope.h index 85ae047c..09fdbe3f 100644 --- a/src/Kaleidoscope.h +++ b/src/Kaleidoscope.h @@ -37,8 +37,11 @@ extern HARDWARE_IMPLEMENTATION KeyboardHardware; #define USE_PLUGINS(plugins...) Kaleidoscope.use(plugins) +class Kaleidoscope_; + class KaleidoscopePlugin { - public: + friend Kaleidoscope_; + protected: virtual void begin(void) = 0; }; From de487990c34bfb4668a1e8fe1f2a00e8247f869e Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Wed, 11 Oct 2017 23:30:41 +0200 Subject: [PATCH 2/2] Introduce KaleidoscopePlugin.initialSetup, and deprecate .begin As discussed in #196, if we are making `KaleidoscopePlugin.begin` protected, we might as well give it a better name. That name is `initialSetup`, and this change is the first step towards the migration. It introduces `initialSetup` which will call `begin` for now, and deprecate `begin`, which is no longer an abstract function. Once everyone migrated to the new name, we can remove `.begin`, and turn `.initialSetup` into an abstract function. Signed-off-by: Gergely Nagy --- src/Kaleidoscope.h | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/src/Kaleidoscope.h b/src/Kaleidoscope.h index 09fdbe3f..61b78e57 100644 --- a/src/Kaleidoscope.h +++ b/src/Kaleidoscope.h @@ -40,9 +40,34 @@ extern HARDWARE_IMPLEMENTATION KeyboardHardware; class Kaleidoscope_; class KaleidoscopePlugin { - friend Kaleidoscope_; + friend class Kaleidoscope_; + protected: - virtual void begin(void) = 0; + /** @deprecated Initial setup function. + * Use \ref initialSetup() instead, and see documentation there. + */ + virtual void begin(void) __attribute__((deprecated("Use initialSetup() instead"))) { }; + + /** Initial plugin setup hook. + * All 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 function will in turn call the `initialSetup` function of each plugin, + * so that they can perform any initial setup they wish, such as registering + * event handler or loop hooks. This is the only time this function will be + * called. It is intentionally protected, and accessible by the `Kaleidoscope` + * class only. + * + * @TODO: Once the deprecated \ref begin() method is removed, turn this into an + * abstract function. + */ + virtual void initialSetup(void) { + begin(); + } }; class Kaleidoscope_ { @@ -64,7 +89,7 @@ class Kaleidoscope_ { // Then, the one-argument version, that gives us type safety for a single // plugin. inline void use(KaleidoscopePlugin *p) { - p->begin(); + p->initialSetup(); } // We have a no-op with a int argument, as a temporary hack until we remove