Introduce the onFocusEvent hook

This is not directly used by Kaleidoscope itself, but we provide the hook from
here, for the sake of convenience. It will be used by plugins such as
`Kaleidoscope-FocusSerial`, in much the same way as Focus hooks were used
previously.

This does change the architecture a bit, and the `FOCUS_HOOK_KALEIDOSCOPE` focus
hook previously provided by Kaleidoscope itself is something that no longer
belongs to core, but rather to a plugin. As such, the hook is removed as part of
this patch.

Signed-off-by: Gergely Nagy <algernon@keyboard.io>

UPGRADING.md

@@ -15,6 +15,18 @@ easier to use and develop for:
  - The new system has more hook points, and the method names are much more clear
    now.
 
+### Bidirectional communication for plugins
+
+Formerly the `Kaleidoscope-Focus` plugin implemented a way for plugins to
+register hooks that respond to commands sent from the host. A part of this has
+been pulled into Kaleidoscope itself, in the form of the new `onFocusEvent`
+hook. For most intents and purposes, this hook works similar to how focus hooks
+worked previously, but has the advantage of not having to explicitly register
+them: if you use a plugin that supports this feature, and you have the new
+`Kaleidoscope-FocusSerial` plugin enabled, the commands will be made available.
+
+This drastically simplifies both the plugins that wish to implement this, and the user sketches, which no longer need to explicitly register the focus hooks.
+
 ### Kaleidoscope.millisAtCycleStart()
 
 Many plugins use timers, and most of them will call `millis()`, which isn't

src/Kaleidoscope.cpp

@@ -64,47 +64,6 @@ Kaleidoscope_::loop(void) {
   kaleidoscope::Hooks::afterEachCycle();
 }
 
-bool
-Kaleidoscope_::focusHook(const char *command) {
-  enum {
-    ON,
-    OFF,
-    GETSTATE,
-  } subCommand;
-
-  if (strncmp_P(command, PSTR("layer."), 6) != 0)
-    return false;
-
-  if (strcmp_P(command + 6, PSTR("on")) == 0)
-    subCommand = ON;
-  else if (strcmp_P(command + 6, PSTR("off")) == 0)
-    subCommand = OFF;
-  else if (strcmp_P(command + 6, PSTR("getState")) == 0)
-    subCommand = GETSTATE;
-  else
-    return false;
-
-  switch (subCommand) {
-  case ON: {
-    uint8_t layer = Serial.parseInt();
-    Layer.on(layer);
-    break;
-  }
-
-  case OFF: {
-    uint8_t layer = Serial.parseInt();
-    Layer.off(layer);
-    break;
-  }
-
-  case GETSTATE:
-    Serial.println(Layer.getLayerState(), BIN);
-    break;
-  }
-
-  return true;
-}
-
 Kaleidoscope_ Kaleidoscope;
 
 } // namespace kaleidoscope

src/Kaleidoscope.h

@@ -124,7 +124,9 @@ class Kaleidoscope_ {
     return millis_at_cycle_start_;
   }
 
-  static bool focusHook(const char *command);
+  EventHandlerResult onFocusEvent(const char *command) {
+    return kaleidoscope::Hooks::onFocusEvent(command);
+  }
 
  private:
   static uint32_t millis_at_cycle_start_;
@@ -144,11 +146,6 @@ typedef kaleidoscope::Kaleidoscope_  Kaleidoscope_;
 //
 using kaleidoscope::Kaleidoscope;
 
-#define FOCUS_HOOK_KALEIDOSCOPE FOCUS_HOOK(Kaleidoscope.focusHook,  \
-                                           "layer.on\n"             \
-                                           "layer.off\n"            \
-                                           "layer.getState")
-
 // Use this function macro to register plugins with Kaleidoscope's
 // hooking system. The macro accepts a list of plugin instances that
 // must have been instantiated at global scope.

src/event_handlers.h

@@ -59,6 +59,18 @@
                (Key &mappedKey, byte row, byte col, uint8_t keyState),    __NL__ \
                (mappedKey, row, col, keyState), ##__VA_ARGS__)            __NL__ \
                                                                           __NL__ \
+   /* Called by an external plugin (such as Kaleidoscope-FocusSerial)  */ __NL__ \
+   /* via Kaleidoscope::onFocusEvent. This is where Focus events can   */ __NL__ \
+   /* be handled. The function can return EventHandlerResult::OK, and  */ __NL__ \
+   /* allow other plugins to handle the same command (with the caveat  */ __NL__ \
+   /* that arguments can only be parsed once), or                      */ __NL__ \
+   /* EventHandlerResult::EVENT_CONSUMED, in which case no other       */ __NL__ \
+   /* plugin will have a chance to react to the event.                 */ __NL__ \
+   OPERATION(onFocusEvent,                                                __NL__ \
+                _ABORTABLE,                                               __NL__ \
+                (const char *command),                                    __NL__ \
+                (command), ##__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__ \