From 6a5f8da4a310d5ddd1de8b87d35f394144080502 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 13 Oct 2018 14:49:45 +0200 Subject: [PATCH] Rearrange the file layout in preparation of becoming a monorepo Move the documentation to `doc/plugin/LED-AlphaSquare.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 | 101 +--------------- doc/plugin/LED-AlphaSquare.md | 109 ++++++++++++++++++ examples/LED-AlphaSquare/LED-AlphaSquare.ino | 8 +- src/Kaleidoscope-LED-AlphaSquare.h | 6 +- .../plugin}/AlphaSquare-Effect.cpp | 4 +- .../plugin}/AlphaSquare-Effect.h | 4 +- .../plugin}/AlphaSquare-Symbols.h | 8 +- .../plugin}/LED-AlphaSquare-3x4.h | 0 .../plugin}/LED-AlphaSquare-4x4.h | 0 .../plugin}/LED-AlphaSquare.cpp | 6 +- .../plugin}/LED-AlphaSquare.h | 4 +- 11 files changed, 137 insertions(+), 113 deletions(-) create mode 100644 doc/plugin/LED-AlphaSquare.md rename src/{Kaleidoscope => kaleidoscope/plugin}/AlphaSquare-Effect.cpp (96%) rename src/{Kaleidoscope => kaleidoscope/plugin}/AlphaSquare-Effect.h (93%) rename src/{Kaleidoscope => kaleidoscope/plugin}/AlphaSquare-Symbols.h (86%) rename src/{Kaleidoscope => kaleidoscope/plugin}/LED-AlphaSquare-3x4.h (100%) rename src/{Kaleidoscope => kaleidoscope/plugin}/LED-AlphaSquare-4x4.h (100%) rename src/{Kaleidoscope => kaleidoscope/plugin}/LED-AlphaSquare.cpp (95%) rename src/{Kaleidoscope => kaleidoscope/plugin}/LED-AlphaSquare.h (97%) diff --git a/README.md b/README.md index 57b10d64..469787f3 100644 --- a/README.md +++ b/README.md @@ -5,103 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-LED-AlphaSquare.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-LED-AlphaSquare -An alphabet for your per-key LEDs, `AlphaSquare` provides a way to display 4x4 -"pixel" symbols on your keyboard. With this building block, one can build some -sweet animations, or just show off - the possibilities are almost endless! - -## Using the plugin - -To use the plugin, one needs to include the header in their Sketch, tell the -firmware to `use` the plugin, and one way or another, call the `display` method. -This can be done from a macro, or via the `AlphaSquareEffect` LED mode. - -```c++ -#include -#include -#include - -KALEIDOSCOPE_INIT_PLUGINS(LEDControl, - AlphaSquare, - AlphaSquareEffect); - -void setup() { - Kaleidoscope.setup(); - - AlphaSquare.display (Key_A); -} -``` - -## Plugin methods - -The plugin provides the `AlphaSquare` object, which has its methods and -properties listed below, and an `AlphaSquareEffect` LED mode, which has no -methods or properties other than those provided by all LED modes. - -### `.display(key)` -### `.display(key, col)` -### `.display(key, row, col)` -### `.display(key, row, col, color)` - -> Display the symbol for `key` at the given row or column, with pixels set to -> the specified `color`. If `row` is omitted, the first row - `0` is assumed. If -> the column is omitted, then the third column - `2` - is used. -> If the `color` is omitted, the plugin will use the global `.color` property. -> -> The plugin can display the English alphabet, and the numbers from 0 to 9. The -> symbol will be drawn with the top-left corner at the given position. -> -> Please consult the appropriate hardware library of your keyboard to see how -> keys are laid out in rows and columns. - -### `.display(symbol)` -### `.display(symbol, col)` -### `.display(symbol, row, col)` -### `.display(symbol, row, col, color)` - -> As the previous function, but instead of a key, it expects a 4x4 bitmap in -> the form of a 16-bit unsigned integer, where the low bit is the top-right -> corner, the second-lowest bit is to the right of that, and so on. -> -> The `SYM4x4` macro can be used to simplify creating these bitmaps. - -### `.clear(key)`, `.clear(symbol)` -### `.clear(key, col)`, `.clear(symbol, col)` -### `.clear(key, col, row)`, `.clear(symbol, col, row)` - -> Just like the `.display()` counterparts, except these clear the symbol, by -> turning the LED pixels it is made up from off. - -### `.color` - -> The color to use to draw the pixels. -> -> Defaults to `{ 0x80, 0x80, 0x80 }` (light gray). - -## Plugin helpers - -### `SYM4x4(...)` - -> A helper macro, which can be used to set up custom bitmaps. It expects 16 -> values, a 4x4 square of zeroes and ones. Zeroes are transparent pixels, ones -> will be colored. - -## Extra symbols - -There is a growing number of pre-defined symbols available in the -`kaleidoscope::alpha_square::symbols` namespace. Ok, growing may have been an -exaggeration, there is only one as of this writing: - -### `Lambda` - -> A lambda (`λ`) symbol. - -## Dependencies - -* [Kaleidoscope-LEDControl](https://github.com/keyboardio/Kaleidoscope-LEDControl) - -## 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-LED-AlphaSquare/blob/master/examples/LED-AlphaSquare/LED-AlphaSquare.ino +See [doc/plugin/LED-AlphaSquare.md](doc/plugin/LED-AlphaSquare.md) for documentation. diff --git a/doc/plugin/LED-AlphaSquare.md b/doc/plugin/LED-AlphaSquare.md new file mode 100644 index 00000000..1bb0cb16 --- /dev/null +++ b/doc/plugin/LED-AlphaSquare.md @@ -0,0 +1,109 @@ +# Kaleidoscope-LED-AlphaSquare + +An alphabet for your per-key LEDs, `AlphaSquare` provides a way to display 4x4 +"pixel" symbols on your keyboard. With this building block, one can build some +sweet animations, or just show off - the possibilities are almost endless! + +## Using the plugin + +To use the plugin, one needs to include the header in their Sketch, tell the +firmware to `use` the plugin, and one way or another, call the `display` method. +This can be done from a macro, or via the `AlphaSquareEffect` LED mode. + +```c++ +#include +#include +#include + +KALEIDOSCOPE_INIT_PLUGINS(LEDControl, + AlphaSquare, + AlphaSquareEffect); + +void setup() { + Kaleidoscope.setup(); + + AlphaSquare.display (Key_A); +} +``` + +## Plugin methods + +The plugin provides the `AlphaSquare` object, which has its methods and +properties listed below, and an `AlphaSquareEffect` LED mode, which has no +methods or properties other than those provided by all LED modes. + +### `.display(key)` +### `.display(key, col)` +### `.display(key, row, col)` +### `.display(key, row, col, color)` + +> Display the symbol for `key` at the given row or column, with pixels set to +> the specified `color`. If `row` is omitted, the first row - `0` is assumed. If +> the column is omitted, then the third column - `2` - is used. +> If the `color` is omitted, the plugin will use the global `.color` property. +> +> The plugin can display the English alphabet, and the numbers from 0 to 9. The +> symbol will be drawn with the top-left corner at the given position. +> +> Please consult the appropriate hardware library of your keyboard to see how +> keys are laid out in rows and columns. + +### `.display(symbol)` +### `.display(symbol, col)` +### `.display(symbol, row, col)` +### `.display(symbol, row, col, color)` + +> As the previous function, but instead of a key, it expects a 4x4 bitmap in +> the form of a 16-bit unsigned integer, where the low bit is the top-right +> corner, the second-lowest bit is to the right of that, and so on. +> +> The `SYM4x4` macro can be used to simplify creating these bitmaps. + +### `.clear(key)`, `.clear(symbol)` +### `.clear(key, col)`, `.clear(symbol, col)` +### `.clear(key, col, row)`, `.clear(symbol, col, row)` + +> Just like the `.display()` counterparts, except these clear the symbol, by +> turning the LED pixels it is made up from off. + +### `.color` + +> The color to use to draw the pixels. +> +> Defaults to `{ 0x80, 0x80, 0x80 }` (light gray). + +## Plugin helpers + +### `SYM4x4(...)` + +> A helper macro, which can be used to set up custom bitmaps. It expects 16 +> values, a 4x4 square of zeroes and ones. Zeroes are transparent pixels, ones +> will be colored. + +## Extra symbols + +There is a growing number of pre-defined symbols available in the +`kaleidoscope::plugin::alpha_square::symbols` namespace. Ok, growing may have +been an exaggeration, there is only one as of this writing: + +### `Lambda` + +> A lambda (`λ`) symbol. + +## Dependencies + +* [Kaleidoscope-LEDControl](https://github.com/keyboardio/Kaleidoscope-LEDControl) + +## 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-LED-AlphaSquare/blob/master/examples/LED-AlphaSquare/LED-AlphaSquare.ino + +## Upgrading + +Former versions of the plugin used to have extra symbols in the +`kaleidoscope::alpha_square::symbols` namespace, while current versions have +them under `kaleidoscope::plugin::alpha_square::symbols`. The old name is +deprecated, and will be removed by 2019-01-14. diff --git a/examples/LED-AlphaSquare/LED-AlphaSquare.ino b/examples/LED-AlphaSquare/LED-AlphaSquare.ino index 5030ba8d..c4a3eb51 100644 --- a/examples/LED-AlphaSquare/LED-AlphaSquare.ino +++ b/examples/LED-AlphaSquare/LED-AlphaSquare.ino @@ -75,15 +75,15 @@ const macro_t *macroAction(uint8_t macro_index, uint8_t key_state) { for (uint8_t step = 0; step <= 0xf0; step += 8) { AlphaSquare.color = { step, step, step }; - AlphaSquare.display(kaleidoscope::alpha_square::symbols::Lambda, 2); - AlphaSquare.display(kaleidoscope::alpha_square::symbols::Lambda, 10); + AlphaSquare.display(kaleidoscope::plugin::alpha_square::symbols::Lambda, 2); + AlphaSquare.display(kaleidoscope::plugin::alpha_square::symbols::Lambda, 10); delay(10); } for (uint8_t step = 0xff; step >= 8; step -= 8) { AlphaSquare.color = { step, step, step }; - AlphaSquare.display(kaleidoscope::alpha_square::symbols::Lambda, 2); - AlphaSquare.display(kaleidoscope::alpha_square::symbols::Lambda, 10); + AlphaSquare.display(kaleidoscope::plugin::alpha_square::symbols::Lambda, 2); + AlphaSquare.display(kaleidoscope::plugin::alpha_square::symbols::Lambda, 10); delay(10); } delay(100); diff --git a/src/Kaleidoscope-LED-AlphaSquare.h b/src/Kaleidoscope-LED-AlphaSquare.h index 9366536c..2d43bacf 100644 --- a/src/Kaleidoscope-LED-AlphaSquare.h +++ b/src/Kaleidoscope-LED-AlphaSquare.h @@ -17,6 +17,6 @@ #pragma once -#include -#include -#include +#include +#include +#include diff --git a/src/Kaleidoscope/AlphaSquare-Effect.cpp b/src/kaleidoscope/plugin/AlphaSquare-Effect.cpp similarity index 96% rename from src/Kaleidoscope/AlphaSquare-Effect.cpp rename to src/kaleidoscope/plugin/AlphaSquare-Effect.cpp index d5d343a5..025ec20d 100644 --- a/src/Kaleidoscope/AlphaSquare-Effect.cpp +++ b/src/kaleidoscope/plugin/AlphaSquare-Effect.cpp @@ -18,6 +18,7 @@ #include namespace kaleidoscope { +namespace plugin { uint16_t AlphaSquareEffect::length = 1000; uint32_t AlphaSquareEffect::end_time_left_, AlphaSquareEffect::end_time_right_; @@ -67,6 +68,7 @@ EventHandlerResult AlphaSquareEffect::onKeyswitchEvent(Key &mappedKey, byte row, return EventHandlerResult::OK; } +} } -kaleidoscope::AlphaSquareEffect AlphaSquareEffect; +kaleidoscope::plugin::AlphaSquareEffect AlphaSquareEffect; diff --git a/src/Kaleidoscope/AlphaSquare-Effect.h b/src/kaleidoscope/plugin/AlphaSquare-Effect.h similarity index 93% rename from src/Kaleidoscope/AlphaSquare-Effect.h rename to src/kaleidoscope/plugin/AlphaSquare-Effect.h index af9d4554..3227afdf 100644 --- a/src/Kaleidoscope/AlphaSquare-Effect.h +++ b/src/kaleidoscope/plugin/AlphaSquare-Effect.h @@ -21,6 +21,7 @@ #include namespace kaleidoscope { +namespace plugin { class AlphaSquareEffect : public LEDMode { public: AlphaSquareEffect(void) {} @@ -37,5 +38,6 @@ class AlphaSquareEffect : public LEDMode { static Key last_key_left_, last_key_right_; }; } +} -extern kaleidoscope::AlphaSquareEffect AlphaSquareEffect; +extern kaleidoscope::plugin::AlphaSquareEffect AlphaSquareEffect; diff --git a/src/Kaleidoscope/AlphaSquare-Symbols.h b/src/kaleidoscope/plugin/AlphaSquare-Symbols.h similarity index 86% rename from src/Kaleidoscope/AlphaSquare-Symbols.h rename to src/kaleidoscope/plugin/AlphaSquare-Symbols.h index 05b74566..e829a81d 100644 --- a/src/Kaleidoscope/AlphaSquare-Symbols.h +++ b/src/kaleidoscope/plugin/AlphaSquare-Symbols.h @@ -17,9 +17,10 @@ #pragma once -#include +#include namespace kaleidoscope { +namespace plugin { namespace alpha_square { namespace symbols { @@ -31,3 +32,8 @@ static constexpr uint16_t Lambda = SYM4x4(1, 0, 0, 0, } } } + +// Backwards compatibility +namespace alpha_square = kaleidoscope::plugin::alpha_square; + +} diff --git a/src/Kaleidoscope/LED-AlphaSquare-3x4.h b/src/kaleidoscope/plugin/LED-AlphaSquare-3x4.h similarity index 100% rename from src/Kaleidoscope/LED-AlphaSquare-3x4.h rename to src/kaleidoscope/plugin/LED-AlphaSquare-3x4.h diff --git a/src/Kaleidoscope/LED-AlphaSquare-4x4.h b/src/kaleidoscope/plugin/LED-AlphaSquare-4x4.h similarity index 100% rename from src/Kaleidoscope/LED-AlphaSquare-4x4.h rename to src/kaleidoscope/plugin/LED-AlphaSquare-4x4.h diff --git a/src/Kaleidoscope/LED-AlphaSquare.cpp b/src/kaleidoscope/plugin/LED-AlphaSquare.cpp similarity index 95% rename from src/Kaleidoscope/LED-AlphaSquare.cpp rename to src/kaleidoscope/plugin/LED-AlphaSquare.cpp index 3004ec48..a650c179 100644 --- a/src/Kaleidoscope/LED-AlphaSquare.cpp +++ b/src/kaleidoscope/plugin/LED-AlphaSquare.cpp @@ -16,9 +16,10 @@ */ #include -#include +#include namespace kaleidoscope { +namespace plugin { static const uint16_t alphabet[] PROGMEM = { ALPHASQUARE_SYMBOL_A, @@ -94,6 +95,7 @@ void AlphaSquare::display(uint16_t symbol, uint8_t row, uint8_t col) { display(symbol, row, col, color); } +} } -kaleidoscope::AlphaSquare AlphaSquare; +kaleidoscope::plugin::AlphaSquare AlphaSquare; diff --git a/src/Kaleidoscope/LED-AlphaSquare.h b/src/kaleidoscope/plugin/LED-AlphaSquare.h similarity index 97% rename from src/Kaleidoscope/LED-AlphaSquare.h rename to src/kaleidoscope/plugin/LED-AlphaSquare.h index 1c602064..296a7ca7 100644 --- a/src/Kaleidoscope/LED-AlphaSquare.h +++ b/src/kaleidoscope/plugin/LED-AlphaSquare.h @@ -32,6 +32,7 @@ p30 << 12 | p31 << 13 | p32 << 14 | p33 << 15 ) namespace kaleidoscope { +namespace plugin { class AlphaSquare : public kaleidoscope::Plugin { public: AlphaSquare(void) {} @@ -77,6 +78,7 @@ class AlphaSquare : public kaleidoscope::Plugin { static cRGB color; }; +} } -extern kaleidoscope::AlphaSquare AlphaSquare; +extern kaleidoscope::plugin::AlphaSquare AlphaSquare;