Merge pull request #362 from keyboardio/f/focus-in-core

Introduce the onFocusEvent hook

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__ \