From f478112e2dbc98e258add54514b47e4cfac68973 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 13 Oct 2018 15:22:14 +0200 Subject: [PATCH] Rearrange the file layout in preparation of becoming a monorepo Move the documentation to `doc/plugin/ShapeShifter.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 | 60 +--------------- doc/plugin/ShapeShifter.md | 69 +++++++++++++++++++ examples/ShapeShifter/ShapeShifter.ino | 2 +- src/Kaleidoscope-ShapeShifter.h | 2 +- .../plugin}/ShapeShifter.cpp | 4 +- .../plugin}/ShapeShifter.h | 6 +- 6 files changed, 80 insertions(+), 63 deletions(-) create mode 100644 doc/plugin/ShapeShifter.md rename src/{Kaleidoscope => kaleidoscope/plugin}/ShapeShifter.cpp (96%) rename src/{Kaleidoscope => kaleidoscope/plugin}/ShapeShifter.h (88%) diff --git a/README.md b/README.md index cbc318e8..a7cf2fc6 100644 --- a/README.md +++ b/README.md @@ -5,62 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-ShapeShifter.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-ShapeShifter -`ShapeShifter` is a plugin that makes it considerably easier to change what -symbol is input when a key is pressed together with `Shift`. If one wants to -rearrange the symbols on the number row for example, without modifying the -layout on the operating system side, this plugin is where one can turn to. - -What it does, is very simple: if any key in its dictionary is found pressed -while `Shift` is held, it will press another key instead of the one triggering -the event. For example, if it sees `Shift + 1` pressed together, which normally -results in a `!`, it will press `4` instead of `1`, inputting `$`. - -## Using the plugin - -To use the plugin, one needs to include the header, create a dictionary, and -configure the provided `ShapeShifter` object to use the dictionary: - -```c++ -#include -#include - -static const kaleidoscope::ShapeShifter::dictionary_t shape_shift_dictionary[] PROGMEM = { - {Key_1, Key_4}, - {Key_4, Key_1}, - {Key_NoKey, Key_NoKey}, -}; - -KALEIDOSCOPE_INIT_PLUGINS(ShapeShifter); - -void setup() { - Kaleidoscope.setup(); - - ShapeShifter.dictionary = shape_shift_dictionary; -} -``` - -The dictionary is made up of `Key` pairs: the first one is to replace, the -second is the replacement. The dictionary must be closed with a `{Key_NoKey, -Key_NoKey}` pair, and **must** reside in `PROGMEM`. - -## Plugin methods - -The plugin provides the `ShapeShifter` object, with the following methods and -properties: - -### `.dictionary` - -> Set this property to the dictionary `ShapeShifter` should use. The dictionary -> is an array of `kaleidoscope::ShapeShifter::dictionary_t` elements, which is -> just a very verbose way of saying that its a pair of keys. The first one is -> the one to replace, and the other is to replace it with. -> -> Be aware that the replacement key will be pressed with `Shift` held, so do -> keep that in mind! - -## 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-ShapeShifter/blob/master/examples/ShapeShifter/ShapeShifter.ino +See [doc/plugin/ShapeShifter.md](doc/plugin/ShapeShifter.md) for documentation. diff --git a/doc/plugin/ShapeShifter.md b/doc/plugin/ShapeShifter.md new file mode 100644 index 00000000..f1f324dc --- /dev/null +++ b/doc/plugin/ShapeShifter.md @@ -0,0 +1,69 @@ +# Kaleidoscope-ShapeShifter + +`ShapeShifter` is a plugin that makes it considerably easier to change what +symbol is input when a key is pressed together with `Shift`. If one wants to +rearrange the symbols on the number row for example, without modifying the +layout on the operating system side, this plugin is where one can turn to. + +What it does, is very simple: if any key in its dictionary is found pressed +while `Shift` is held, it will press another key instead of the one triggering +the event. For example, if it sees `Shift + 1` pressed together, which normally +results in a `!`, it will press `4` instead of `1`, inputting `$`. + +## Using the plugin + +To use the plugin, one needs to include the header, create a dictionary, and +configure the provided `ShapeShifter` object to use the dictionary: + +```c++ +#include +#include + +static const kaleidoscope::plugin::ShapeShifter::dictionary_t shape_shift_dictionary[] PROGMEM = { + {Key_1, Key_4}, + {Key_4, Key_1}, + {Key_NoKey, Key_NoKey}, +}; + +KALEIDOSCOPE_INIT_PLUGINS(ShapeShifter); + +void setup() { + Kaleidoscope.setup(); + + ShapeShifter.dictionary = shape_shift_dictionary; +} +``` + +The dictionary is made up of `Key` pairs: the first one is to replace, the +second is the replacement. The dictionary must be closed with a `{Key_NoKey, +Key_NoKey}` pair, and **must** reside in `PROGMEM`. + +## Plugin methods + +The plugin provides the `ShapeShifter` object, with the following methods and +properties: + +### `.dictionary` + +> Set this property to the dictionary `ShapeShifter` should use. The dictionary +> is an array of `kaleidoscope::ShapeShifter::dictionary_t` elements, which is +> just a very verbose way of saying that its a pair of keys. The first one is +> the one to replace, and the other is to replace it with. +> +> Be aware that the replacement key will be pressed with `Shift` held, so do +> keep that in mind! + +## 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-ShapeShifter/blob/master/examples/ShapeShifter/ShapeShifter.ino + +## Upgrading + +Previous versions of `ShapeShifter` used +`kaleidoscope::ShapeShifter::dictionary_t` as a type for defining the +dictionary. In newer versions, this is +`kaleidoscope::plugin::ShapeShifter::dictionary_t`. The old name still works, +but will be removed by 2019-01-14. diff --git a/examples/ShapeShifter/ShapeShifter.ino b/examples/ShapeShifter/ShapeShifter.ino index 1af4c553..14631dee 100644 --- a/examples/ShapeShifter/ShapeShifter.ino +++ b/examples/ShapeShifter/ShapeShifter.ino @@ -40,7 +40,7 @@ const Key keymaps[][ROWS][COLS] PROGMEM = { }; // *INDENT-ON* -static const kaleidoscope::ShapeShifter::dictionary_t shape_shift_dictionary[] PROGMEM = { +static const kaleidoscope::plugin::ShapeShifter::dictionary_t shape_shift_dictionary[] PROGMEM = { {Key_1, Key_2}, {Key_2, Key_1}, {Key_NoKey, Key_NoKey}, diff --git a/src/Kaleidoscope-ShapeShifter.h b/src/Kaleidoscope-ShapeShifter.h index 588933ba..b08d872f 100644 --- a/src/Kaleidoscope-ShapeShifter.h +++ b/src/Kaleidoscope-ShapeShifter.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/ShapeShifter.cpp b/src/kaleidoscope/plugin/ShapeShifter.cpp similarity index 96% rename from src/Kaleidoscope/ShapeShifter.cpp rename to src/kaleidoscope/plugin/ShapeShifter.cpp index 3202dfe4..f97cefbf 100644 --- a/src/Kaleidoscope/ShapeShifter.cpp +++ b/src/kaleidoscope/plugin/ShapeShifter.cpp @@ -19,6 +19,7 @@ #include namespace kaleidoscope { +namespace plugin { const ShapeShifter::dictionary_t *ShapeShifter::dictionary = NULL; bool ShapeShifter::mod_active_; @@ -59,6 +60,7 @@ EventHandlerResult ShapeShifter::onKeyswitchEvent(Key &mapped_key, byte row, byt return EventHandlerResult::OK; } +} } -kaleidoscope::ShapeShifter ShapeShifter; +kaleidoscope::plugin::ShapeShifter ShapeShifter; diff --git a/src/Kaleidoscope/ShapeShifter.h b/src/kaleidoscope/plugin/ShapeShifter.h similarity index 88% rename from src/Kaleidoscope/ShapeShifter.h rename to src/kaleidoscope/plugin/ShapeShifter.h index 344a741e..59344fb5 100644 --- a/src/Kaleidoscope/ShapeShifter.h +++ b/src/kaleidoscope/plugin/ShapeShifter.h @@ -20,6 +20,7 @@ #include namespace kaleidoscope { +namespace plugin { class ShapeShifter : public kaleidoscope::Plugin { public: @@ -37,7 +38,10 @@ class ShapeShifter : public kaleidoscope::Plugin { private: static bool mod_active_; }; +} +// Backwards compatibility +typedef plugin::ShapeShifter ShapeShifter; } -extern kaleidoscope::ShapeShifter ShapeShifter; +extern kaleidoscope::plugin::ShapeShifter ShapeShifter;