diff --git a/doc/plugin/Syster.md b/doc/plugin/Syster.md new file mode 100644 index 00000000..5d23f93c --- /dev/null +++ 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 +#include +#include +#include +#include +#include + +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. diff --git a/examples/Syster/Syster.ino b/examples/Syster/Syster.ino new file mode 100644 index 00000000..51a5c025 --- /dev/null +++ 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 . + */ + +#include +#include +#include +#include +#include +#include + +// *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(); +} diff --git a/src/Kaleidoscope-Syster.h b/src/Kaleidoscope-Syster.h new file mode 100644 index 00000000..7780fab0 --- /dev/null +++ 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 . + */ + +#pragma once + +#include diff --git a/src/kaleidoscope/plugin/Syster.cpp b/src/kaleidoscope/plugin/Syster.cpp new file mode 100644 index 00000000..ff96d2fd --- /dev/null +++ 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 . + */ + +#include +#include + +#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; diff --git a/src/kaleidoscope/plugin/Syster.h b/src/kaleidoscope/plugin/Syster.h new file mode 100644 index 00000000..3b3dc736 --- /dev/null +++ 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 . + */ + +#pragma once + +#include +#include + +#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;