Merge remote-tracking branch 'plugin/Syster/f/monorepo' into f/monorepo-stage2

6 years ago · 6dba0a7f68
parent 54044b58d2 f5a4116fc3
commit 6dba0a7f68
5 changed files with 386 additions and 0 deletions
--- a/doc/plugin/Syster.md
+++ b/doc/plugin/Syster.md
@ -0,0 +1,104 @@
+# Kaleidoscope-Syster
+
+Syster is a way to input symbols in a different way: instead of macros, Leader
+sequences or the like, we trigger the special input mode, and enter the symbol's
+name. Once finished, we hit `Space`, and this plugin will do the rest: delete
+everything we typed, look up an action for the entered symbol, and execute that.
+
+There are a number of ways this can be useful, but the easiest showcase is
+symbolic Unicode input: `SYSTER coffee SPACE` turns into `☕`, with just a
+little code.
+
+## Using the plugin
+
+To use the plugin, one needs to include the header and set up a function that
+will handle the symbol actions:
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+#include <Kaleidoscope-HostOS.h>
+#include <Kaleidoscope-Syster.h>
+#include <Kaleidoscope-Unicode.h>
+#include <kaleidoscope/hid.h>
+
+void systerAction(kaleidoscope::plugin::Syster::action_t action, const char *symbol) {
+  switch (action) {
+  case kaleidoscope::plugin::Syster::StartAction:
+    Unicode.type (0x2328);
+    break;
+  case kaleidoscope::plugin::Syster::EndAction:
+    handleKeyswitchEvent (Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, IS_PRESSED | INJECTED);
+    kaleidoscope::hid::sendKeyboardReport ();
+    handleKeyswitchEvent (Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, WAS_PRESSED | INJECTED);
+    kaleidoscope::hid::sendKeyboardReport ();
+    break;
+  case kaleidoscope::plugin::Syster::SymbolAction:
+    Serial.print ("systerAction: symbol=");
+    Serial.println (symbol);
+    if (strcmp (symbol, "coffee") == 0) {
+      Unicode.type (0x2615);
+    }
+    break;
+  }
+}
+
+KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, HostOS, Unicode, Syster);
+
+void setup() {
+  Serial.begin(9600);
+  Kaleidoscope.setup ();
+}
+```
+
+**Note** that we need to use the `Syster` object before any other that adds or
+changes key behaviour! Failing to do so may result in unpredictable behaviour.
+
+## Plugin methods
+
+The plugin provides the `Syster` object, with no public methods. There are two
+methods outside of the object, however, that can be overridden:
+
+### `systerAction(action, symbol)`
+
+> Called whenever an action needs to be taken, which can happen in three cases:
+
+> First, when the `Syster` key is pressed and the alternate processing starts.
+> In this case, `action` will be set to
+> `kaleidoscope::plugin::Syster::StartAction`, and `symbol` will be `NULL`. This
+> function can be used to do some setup to make it more obvious that the Syster
+> input mode is active, such as sending a Unicode symbol to the host, or
+> lighting up LEDs, or anything else we'd like.
+>
+> Second, when the sequence is finished with a `Space`. In this case, `action`
+> will be set to `kaleidoscope::plugin::Syster::EndAction` and `symbol` will be
+> `NULL`. This can be used to undo anything that the start action did, if need
+> be.
+>
+> Third, when the action for the symbol should be made. In this case, `action`
+> is set to `kaleidoscope::plugin::Syster::SymbolAction`, and `symbol` will be a
+> C string. It is up to us, what we do with this information, how we handle it.
+
+### `keyToChar(key)`
+
+> A function that turns a keycode into a character. If using QWERTY on the host,
+> the default implementation is sufficient. When using something else, you may
+> have to reimplement this function.
+
+## Dependencies
+
+* [Kaleidoscope-Ranges](Ranges.md)
+
+## Further reading
+
+Starting from the [example][plugin:example] is the recommended way of getting
+started with the plugin.
+
+ [plugin:example]: ../../examples/Syster/Syster.ino
+
+## Upgrading
+
+Previous versions of `Syster` used `kaleidoscope::Syster::action_t` as the type
+of Syster actions. In newer versions, this is
+`kaleidoscope::plugin::Syster::action_t`. The old name still works, but will be
+removed by 2019-01-14.
--- a/examples/Syster/Syster.ino
+++ b/examples/Syster/Syster.ino
@ -0,0 +1,79 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-Syster -- Symbolic input system
+ * Copyright (C) 2017, 2018  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+#include <Kaleidoscope-HostOS.h>
+#include <Kaleidoscope-Syster.h>
+#include <Kaleidoscope-Unicode.h>
+#include <kaleidoscope/hid.h>
+
+// *INDENT-OFF*
+const Key keymaps[][ROWS][COLS] PROGMEM = {
+  [0] = KEYMAP_STACKED
+  (
+    Key_NoKey,    Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey,
+    Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab,
+    Key_PageUp,   Key_A, Key_S, Key_D, Key_F, Key_G,
+    Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape,
+
+    Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift,
+    SYSTER,
+
+    Key_skip,  Key_6, Key_7, Key_8,     Key_9,      Key_0,         Key_skip,
+    Key_Enter, Key_Y, Key_U, Key_I,     Key_O,      Key_P,         Key_Equals,
+               Key_H, Key_J, Key_K,     Key_L,      Key_Semicolon, Key_Quote,
+    Key_skip,  Key_N, Key_M, Key_Comma, Key_Period, Key_Slash,     Key_Minus,
+
+    Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl,
+    SYSTER),
+};
+// *INDENT-ON*
+
+void systerAction(kaleidoscope::plugin::Syster::action_t action, const char *symbol) {
+  switch (action) {
+  case kaleidoscope::plugin::Syster::StartAction:
+    Unicode.type(0x2328);
+    break;
+  case kaleidoscope::plugin::Syster::EndAction:
+    handleKeyswitchEvent(Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, IS_PRESSED | INJECTED);
+    kaleidoscope::hid::sendKeyboardReport();
+    handleKeyswitchEvent(Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, WAS_PRESSED | INJECTED);
+    kaleidoscope::hid::sendKeyboardReport();
+    break;
+  case kaleidoscope::plugin::Syster::SymbolAction:
+    Serial.print("systerAction: symbol=");
+    Serial.println(symbol);
+    if (strcmp(symbol, "coffee") == 0) {
+      Unicode.type(0x2615);
+    }
+    break;
+  }
+}
+
+KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings,
+                          HostOS,
+                          Unicode,
+                          Syster);
+
+void setup() {
+  Kaleidoscope.setup();
+}
+
+void loop() {
+  Kaleidoscope.loop();
+}
--- a/src/Kaleidoscope-Syster.h
+++ b/src/Kaleidoscope-Syster.h
@ -0,0 +1,20 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-Syster -- Symbolic input system
+ * Copyright (C) 2016, 2017  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <kaleidoscope/plugin/Syster.h>
--- a/src/kaleidoscope/plugin/Syster.cpp
+++ b/src/kaleidoscope/plugin/Syster.cpp
@ -0,0 +1,122 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-Syster -- Symbolic input system
+ * Copyright (C) 2017, 2018  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <Kaleidoscope-Syster.h>
+#include <kaleidoscope/hid.h>
+
+#undef SYSTER
+
+namespace kaleidoscope {
+namespace plugin {
+
+// --- state ---
+char Syster::symbol_[SYSTER_MAX_SYMBOL_LENGTH + 1];
+uint8_t Syster::symbol_pos_;
+bool Syster::is_active_;
+
+// --- helpers ---
+#define isSyster(k) (k == kaleidoscope::ranges::SYSTER)
+
+// --- api ---
+void Syster::reset(void) {
+  symbol_pos_ = 0;
+  symbol_[0] = 0;
+  is_active_ = false;
+}
+
+bool Syster::is_active(void) {
+  return is_active_;
+}
+
+// --- hooks ---
+EventHandlerResult Syster::onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t keyState) {
+  if (!is_active_) {
+    if (!isSyster(mapped_key))
+      return EventHandlerResult::OK;
+
+    if (keyToggledOn(keyState)) {
+      is_active_ = true;
+      systerAction(StartAction, NULL);
+    }
+    return EventHandlerResult::EVENT_CONSUMED;
+  }
+
+  if (keyState & INJECTED)
+    return EventHandlerResult::OK;
+
+  if (isSyster(mapped_key)) {
+    return EventHandlerResult::EVENT_CONSUMED;
+  }
+
+  if (mapped_key == Key_Backspace && symbol_pos_ == 0) {
+    return EventHandlerResult::EVENT_CONSUMED;
+  }
+
+  if (keyToggledOff(keyState)) {
+    if (mapped_key == Key_Spacebar) {
+      for (uint8_t i = 0; i <= symbol_pos_; i++) {
+        handleKeyswitchEvent(Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, IS_PRESSED | INJECTED);
+        hid::sendKeyboardReport();
+        handleKeyswitchEvent(Key_Backspace, UNKNOWN_KEYSWITCH_LOCATION, WAS_PRESSED | INJECTED);
+        hid::sendKeyboardReport();
+      }
+
+      systerAction(EndAction, NULL);
+
+      symbol_[symbol_pos_] = 0;
+      systerAction(SymbolAction, symbol_);
+      reset();
+
+      return EventHandlerResult::EVENT_CONSUMED;
+    }
+  }
+
+  if (keyToggledOn(keyState)) {
+    if (mapped_key == Key_Backspace) {
+      if (symbol_pos_ > 0)
+        symbol_pos_--;
+    } else {
+      const char c = keyToChar(mapped_key);
+      if (c)
+        symbol_[symbol_pos_++] = c;
+    }
+  }
+
+  return EventHandlerResult::OK;
+}
+
+}
+}
+
+__attribute__((weak)) const char keyToChar(Key key) {
+  if (key.flags != 0)
+    return 0;
+
+  switch (key.keyCode) {
+  case Key_A.keyCode ... Key_Z.keyCode:
+    return 'a' + (key.keyCode - Key_A.keyCode);
+  case Key_1.keyCode ... Key_0.keyCode:
+    return '1' + (key.keyCode - Key_1.keyCode);
+  }
+
+  return 0;
+}
+
+__attribute__((weak)) void systerAction(kaleidoscope::Syster::action_t action, const char *symbol) {
+}
+
+kaleidoscope::plugin::Syster Syster;
--- a/src/kaleidoscope/plugin/Syster.h
+++ b/src/kaleidoscope/plugin/Syster.h
@ -0,0 +1,61 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-Syster -- Symbolic input system
+ * Copyright (C) 2017, 2018  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-Ranges.h>
+
+#define SYSTER_MAX_SYMBOL_LENGTH 32
+
+#define SYSTER ((Key) { .raw = kaleidoscope::ranges::SYSTER })
+
+namespace kaleidoscope {
+namespace plugin {
+
+class Syster : public kaleidoscope::Plugin {
+ public:
+  typedef enum {
+    StartAction,
+    EndAction,
+    SymbolAction
+  } action_t;
+
+  Syster(void) {}
+
+  static void reset(void);
+
+  bool is_active(void);
+
+  EventHandlerResult onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t keyState);
+
+ private:
+  static char symbol_[SYSTER_MAX_SYMBOL_LENGTH + 1];
+  static uint8_t symbol_pos_;
+  static bool is_active_;
+};
+}
+
+// Backwards compatibility
+typedef plugin::Syster Syster;
+
+}
+
+const char keyToChar(Key key);
+void systerAction(kaleidoscope::plugin::Syster::action_t action, const char *symbol);
+
+extern kaleidoscope::plugin::Syster Syster;