diff --git a/README.md b/README.md index d043ca97..111cb0c9 100644 --- a/README.md +++ b/README.md @@ -5,96 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-Syster.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/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::Syster::action_t action, const char *symbol) { - switch (action) { - case kaleidoscope::Syster::StartAction: - Unicode.type (0x2328); - break; - case kaleidoscope::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::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::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::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::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](https://github.com/keyboardio/Kaleidoscope-Ranges) - -## Further reading - -Starting from the [example][plugin:example] is the recommended way of getting -started with the plugin. - - [plugin:example]: https://github.com/keyboardio/Kaleidoscope-Syster/blob/master/examples/Syster/Syster.ino +See [doc/plugin/Syster.md](doc/plugin/Syster.md) for documentation. diff --git a/doc/plugin/Syster.md b/doc/plugin/Syster.md new file mode 100644 index 00000000..cae4932d --- /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](https://github.com/keyboardio/Kaleidoscope-Ranges) + +## Further reading + +Starting from the [example][plugin:example] is the recommended way of getting +started with the plugin. + + [plugin:example]: https://github.com/keyboardio/Kaleidoscope-Syster/blob/master/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 index e409942a..51a5c025 100644 --- a/examples/Syster/Syster.ino +++ b/examples/Syster/Syster.ino @@ -44,18 +44,18 @@ const Key keymaps[][ROWS][COLS] PROGMEM = { }; // *INDENT-ON* -void systerAction(kaleidoscope::Syster::action_t action, const char *symbol) { +void systerAction(kaleidoscope::plugin::Syster::action_t action, const char *symbol) { switch (action) { - case kaleidoscope::Syster::StartAction: + case kaleidoscope::plugin::Syster::StartAction: Unicode.type(0x2328); break; - case kaleidoscope::Syster::EndAction: + 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::Syster::SymbolAction: + case kaleidoscope::plugin::Syster::SymbolAction: Serial.print("systerAction: symbol="); Serial.println(symbol); if (strcmp(symbol, "coffee") == 0) { diff --git a/src/Kaleidoscope-Syster.h b/src/Kaleidoscope-Syster.h index 4e2589f3..7780fab0 100644 --- a/src/Kaleidoscope-Syster.h +++ b/src/Kaleidoscope-Syster.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/Syster.cpp b/src/kaleidoscope/plugin/Syster.cpp similarity index 98% rename from src/Kaleidoscope/Syster.cpp rename to src/kaleidoscope/plugin/Syster.cpp index 525510a2..ff96d2fd 100644 --- a/src/Kaleidoscope/Syster.cpp +++ b/src/kaleidoscope/plugin/Syster.cpp @@ -21,6 +21,7 @@ #undef SYSTER namespace kaleidoscope { +namespace plugin { // --- state --- char Syster::symbol_[SYSTER_MAX_SYMBOL_LENGTH + 1]; @@ -98,6 +99,7 @@ EventHandlerResult Syster::onKeyswitchEvent(Key &mapped_key, byte row, byte col, return EventHandlerResult::OK; } +} } __attribute__((weak)) const char keyToChar(Key key) { @@ -117,4 +119,4 @@ __attribute__((weak)) const char keyToChar(Key key) { __attribute__((weak)) void systerAction(kaleidoscope::Syster::action_t action, const char *symbol) { } -kaleidoscope::Syster Syster; +kaleidoscope::plugin::Syster Syster; diff --git a/src/Kaleidoscope/Syster.h b/src/kaleidoscope/plugin/Syster.h similarity index 86% rename from src/Kaleidoscope/Syster.h rename to src/kaleidoscope/plugin/Syster.h index 167b7e31..3b3dc736 100644 --- a/src/Kaleidoscope/Syster.h +++ b/src/kaleidoscope/plugin/Syster.h @@ -25,6 +25,7 @@ #define SYSTER ((Key) { .raw = kaleidoscope::ranges::SYSTER }) namespace kaleidoscope { +namespace plugin { class Syster : public kaleidoscope::Plugin { public: @@ -47,9 +48,14 @@ class Syster : public kaleidoscope::Plugin { static uint8_t symbol_pos_; static bool is_active_; }; -}; +} + +// Backwards compatibility +typedef plugin::Syster Syster; + +} const char keyToChar(Key key); -void systerAction(kaleidoscope::Syster::action_t action, const char *symbol); +void systerAction(kaleidoscope::plugin::Syster::action_t action, const char *symbol); -extern kaleidoscope::Syster Syster; +extern kaleidoscope::plugin::Syster Syster;