From e37669a623d221dbcc344e8bcdfc6a89087cf614 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 13 Oct 2018 12:40:35 +0200 Subject: [PATCH] Rearrange the file layout in preparation of becoming a monorepo Move the documentation to `doc/plugin/Leader.md`, sources under `src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of merging plugins into a single monorepo. Signed-off-by: Gergely Nagy --- README.md | 99 +--------------- doc/plugin/Leader.md | 107 ++++++++++++++++++ examples/Leader/Leader.ino | 2 +- src/Kaleidoscope-Leader.h | 2 +- .../plugin}/Leader.cpp | 4 +- .../plugin}/Leader.h | 6 +- 6 files changed, 118 insertions(+), 102 deletions(-) create mode 100644 doc/plugin/Leader.md rename src/{Kaleidoscope => kaleidoscope/plugin}/Leader.cpp (98%) rename src/{Kaleidoscope => kaleidoscope/plugin}/Leader.h (93%) diff --git a/README.md b/README.md index 9226862a..827d9be4 100644 --- a/README.md +++ b/README.md @@ -5,101 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-Leader.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-Leader -Leader keys are a kind of key where when they are tapped, all following keys are -swallowed, until the plugin finds a matching sequence in the dictionary, it -times out, or fails to find any possibilities. When a sequence is found, the -corresponding action is executed, but the processing still continues. If any key -is pressed that is not the continuation of the existing sequence, processing -aborts, and the key is handled normally. - -This behaviour is best described with an example. Suppose we want a behaviour -where `LEAD u` starts unicode input mode, and `LEAD u h e a r t` should result -in a heart symbol being input, and we want `LEAD u 0 0 e 9 SPC` to input `é`, -and any other hex code that follows `LEAD u`, should be handled as-is, and -passed to the host. Obviously, we can't have all of this in a dictionary. - -So we put `LEAD u` and `LEAD u h e a r t` in the dictionary only. The first will -start unicode input mode, the second will type in the magic sequence that -results in the symbol, and then aborts the leader sequence processing. With this -setup, if we type `LEAD u 0`, then `LEAD u` will be handled first, and start -unicode input mode. Then, at the `0`, the plugin notices it is not part of any -sequence, so aborts leader processing, and passes the key on as-is, and it ends -up being sent to the host. Thus, we covered all the cases of our scenario! - -## Using the plugin - -To use the plugin, one needs to include the header, implement some actions, -create a dictionary, and configure the provided `Leader` object to use the -dictionary: - -```c++ -#include -#include - -static void leaderA(uint8_t seq_index) { - Serial.println("leaderA"); -} - -static void leaderTX(uint8_t seq_index) { - Serial.println("leaderTX"); -} - -static const kaleidoscope::Leader::dictionary_t leader_dictionary[] PROGMEM = - LEADER_DICT({LEADER_SEQ(LEAD(0), Key_A), leaderA}, - {LEADER_SEQ(LEAD(0), Key_T, Key_X), leaderTX}); - -KALEIDOSCOPE_INIT_PLUGINS(Leader); - -void setup() { - Serial.begin(9600); - - Kaleidoscope.setup(); - - Leader.dictionary = leader_dictionary; -} -``` - -The dictionary is made up of a list of keys, and an action callback. Using the -`LEADER_DICT` and `LEADER_SEQ` helpers is recommended. The dictionary *must* be -marked `PROGMEM`! - -**Note** that we need to use the `Leader` 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 `Leader` object, with the following methods and properties: - -### `.dictionary` - -> Set this property to the dictionary `Leader` should use. The dictionary is an -> array of `kaleidoscope::Leader::dictionary_t` elements. Each element is made -> up of two elements, the first being a list of keys, the second an action to -> perform when the sequence is found.i -> -> The dictionary *MUST* reside in `PROGMEM`. - -### `.reset()` - -> Finishes the leader sequence processing. This is best called from actions that -> are final actions, where one does not wish to continue the leader sequence -> further in the hopes of finding a longer match. - -### `.time_out` - -> The number of milliseconds to wait before a sequence times out. Once the -> sequence timed out, if there is a partial match with an action, that will be -> performed, otherwise the Leader sequence will simply reset. -> -> Defaults to 1000. - -## 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-Leader/blob/master/examples/Leader/Leader.ino +See [doc/plugin/Leader.md](doc/plugin/Leader.md) for documentation. diff --git a/doc/plugin/Leader.md b/doc/plugin/Leader.md new file mode 100644 index 00000000..8fa1e041 --- /dev/null +++ b/doc/plugin/Leader.md @@ -0,0 +1,107 @@ +# Kaleidoscope-Leader + +Leader keys are a kind of key where when they are tapped, all following keys are +swallowed, until the plugin finds a matching sequence in the dictionary, it +times out, or fails to find any possibilities. When a sequence is found, the +corresponding action is executed, but the processing still continues. If any key +is pressed that is not the continuation of the existing sequence, processing +aborts, and the key is handled normally. + +This behaviour is best described with an example. Suppose we want a behaviour +where `LEAD u` starts unicode input mode, and `LEAD u h e a r t` should result +in a heart symbol being input, and we want `LEAD u 0 0 e 9 SPC` to input `é`, +and any other hex code that follows `LEAD u`, should be handled as-is, and +passed to the host. Obviously, we can't have all of this in a dictionary. + +So we put `LEAD u` and `LEAD u h e a r t` in the dictionary only. The first will +start unicode input mode, the second will type in the magic sequence that +results in the symbol, and then aborts the leader sequence processing. With this +setup, if we type `LEAD u 0`, then `LEAD u` will be handled first, and start +unicode input mode. Then, at the `0`, the plugin notices it is not part of any +sequence, so aborts leader processing, and passes the key on as-is, and it ends +up being sent to the host. Thus, we covered all the cases of our scenario! + +## Using the plugin + +To use the plugin, one needs to include the header, implement some actions, +create a dictionary, and configure the provided `Leader` object to use the +dictionary: + +```c++ +#include +#include + +static void leaderA(uint8_t seq_index) { + Serial.println("leaderA"); +} + +static void leaderTX(uint8_t seq_index) { + Serial.println("leaderTX"); +} + +static const kaleidoscope::Leader::dictionary_t leader_dictionary[] PROGMEM = + LEADER_DICT({LEADER_SEQ(LEAD(0), Key_A), leaderA}, + {LEADER_SEQ(LEAD(0), Key_T, Key_X), leaderTX}); + +KALEIDOSCOPE_INIT_PLUGINS(Leader); + +void setup() { + Serial.begin(9600); + + Kaleidoscope.setup(); + + Leader.dictionary = leader_dictionary; +} +``` + +The dictionary is made up of a list of keys, and an action callback. Using the +`LEADER_DICT` and `LEADER_SEQ` helpers is recommended. The dictionary *must* be +marked `PROGMEM`! + +**Note** that we need to use the `Leader` 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 `Leader` object, with the following methods and properties: + +### `.dictionary` + +> Set this property to the dictionary `Leader` should use. The dictionary is an +> array of `kaleidoscope::Leader::dictionary_t` elements. Each element is made +> up of two elements, the first being a list of keys, the second an action to +> perform when the sequence is found.i +> +> The dictionary *MUST* reside in `PROGMEM`. + +### `.reset()` + +> Finishes the leader sequence processing. This is best called from actions that +> are final actions, where one does not wish to continue the leader sequence +> further in the hopes of finding a longer match. + +### `.time_out` + +> The number of milliseconds to wait before a sequence times out. Once the +> sequence timed out, if there is a partial match with an action, that will be +> performed, otherwise the Leader sequence will simply reset. +> +> Defaults to 1000. + +## 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-Leader/blob/master/examples/Leader/Leader.ino + +## Upgrading + +Previous versions of `Leader` used `kaleidoscope::Leader::dictionary_t` as a +type for defining the dictionary. In newer versions, this is +`kaleidoscope::plugin::Leader::dictionary_t`. The old name still works, but will +be removed by 2019-01-14. diff --git a/examples/Leader/Leader.ino b/examples/Leader/Leader.ino index 583c95d9..e49869f6 100644 --- a/examples/Leader/Leader.ino +++ b/examples/Leader/Leader.ino @@ -47,7 +47,7 @@ static void leaderTestAA(uint8_t seq_index) { Serial.println(F("leaderTestAA")); } -static const kaleidoscope::Leader::dictionary_t leader_dictionary[] PROGMEM = +static const kaleidoscope::plugin::Leader::dictionary_t leader_dictionary[] PROGMEM = LEADER_DICT({LEADER_SEQ(LEAD(0), Key_A), leaderTestA}, {LEADER_SEQ(LEAD(0), Key_A, Key_A), leaderTestAA}); diff --git a/src/Kaleidoscope-Leader.h b/src/Kaleidoscope-Leader.h index 1f2fce3e..87b948fa 100644 --- a/src/Kaleidoscope-Leader.h +++ b/src/Kaleidoscope-Leader.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/Leader.cpp b/src/kaleidoscope/plugin/Leader.cpp similarity index 98% rename from src/Kaleidoscope/Leader.cpp rename to src/kaleidoscope/plugin/Leader.cpp index 2b11f969..96968082 100644 --- a/src/Kaleidoscope/Leader.cpp +++ b/src/kaleidoscope/plugin/Leader.cpp @@ -18,6 +18,7 @@ #include namespace kaleidoscope { +namespace plugin { // --- state --- Key Leader::sequence_[LEADER_MAX_SEQUENCE_LENGTH + 1]; @@ -154,6 +155,7 @@ EventHandlerResult Leader::afterEachCycle() { return EventHandlerResult::OK; } +} } -kaleidoscope::Leader Leader; +kaleidoscope::plugin::Leader Leader; diff --git a/src/Kaleidoscope/Leader.h b/src/kaleidoscope/plugin/Leader.h similarity index 93% rename from src/Kaleidoscope/Leader.h rename to src/kaleidoscope/plugin/Leader.h index 6e9564d4..a7c56e87 100644 --- a/src/Kaleidoscope/Leader.h +++ b/src/kaleidoscope/plugin/Leader.h @@ -28,6 +28,7 @@ #define LEADER_DICT(...) { __VA_ARGS__, {{Key_NoKey}, NULL} } namespace kaleidoscope { +namespace plugin { class Leader : public kaleidoscope::Plugin { public: @@ -55,7 +56,10 @@ class Leader : public kaleidoscope::Plugin { static int8_t lookup(void); }; +} +// Backwards compatibility +typedef plugin::Leader Leader; } -extern kaleidoscope::Leader Leader; +extern kaleidoscope::plugin::Leader Leader;