diff --git a/README.md b/README.md index 55bc9dc4..4d54fd53 100644 --- a/README.md +++ b/README.md @@ -5,98 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-Cycle.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-Cycle -If you ever wanted a key that works like keys on old cell phones, when you press -a key and it cycles through a number of options in a sequence, then the cycling -key is what you are looking for. It is a bit different than on cell phones of -old, as it is a separate key, that works in combination of other keys: you press -a key, then the cycle key, and the cycle key will replace the previously input -symbol with another. Keep tapping the cycle key, and it will replace symbols -with new ones, in a loop. - -## Using the plugin - -To use the plugin, we need to include the header, and declare the behaviour -used. Then, we need to place a cycle key or two on the keymap. And finally, we -need to implement the [`cycleAction`][cycleaction] function that gets called -each time the cycling key triggers. - - [cycleaction]: #cycleactionpreviouskey-cyclecount - -```c++ -#include - -// Somewhere in the keymap: -Key_Cycle - -// later in the Sketch: -void cycleAction(Key previous_key, uint8_t cycle_count) { - if (previous_key.raw == Key_A.raw) { - cycleThrough (Key_B, Key_C, Key_D); - } -} - -KALEIDOSCOPE_INIT_PLUGINS(Cycle); - -void setup(void) { - Kaleidoscope.setup(); -} -``` - -## Keymap markup - -### `Key_Cycle` - -> The key code for the cycle key. There can be as many of this on the keymap, as -> many one wants, but they all behave the same. There is little point in having -> more than one on each side. - -## Plugin methods - -The plugin provides a `Cycle` object, but to implement the actions, we need to -define a function ([`cycleAction`][cycleaction]) outside of the object. A -handler, of sorts. The object also provides a helper method to replace the -previous symbol with another. The plugin also provides one macro that is -particularly useful, and in most cases, should be used over the `.replace()` -method explained below. - -### `cycleThrough(keys...)` - -> Cycles through all the possibilities given in `keys` (starting from the -> beginning once it reached the end). This should be used from -> the [`cycleAction`][cycleaction] function, once it is determined what sequence -> to cycle through. -> -> To make the cycling loop complete, the first element of the `keys` list should -> be the one that - when followed by the Cycle key - triggers the action. - -### `.replace(key)` - -> Deletes the previous symbol (by sending a `Backspace`), and inputs the new -> one. This is used by `cycleThrough()` above, behind the scenes. -> -> The recommended method is to use the macro, but in special circumstances, this -> function can be of direct use as well. - -## Overrideable methods - -### `cycleAction(previous_key, cycle_count)` - -> The heart and soul of the plugin, that must be defined in the Sketch. It will -> be called whenever the cycling key triggers, and the two arguments are the -> last key pressed (not counting repeated taps of the cycling key itself), and -> the number of times the cycling key has been pressed. -> -> It is up to us to decide what to do, and when. But the most common - and -> expected - action is to call `cycleThrough()` with a different sequence for -> each key we want to use together with the cycling key. - -## 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-Cycle/blob/master/examples/Cycle/Cycle.ino +See [doc/plugin/Cycle.md](doc/plugin/Cycle.md) for documentation. diff --git a/doc/plugin/Cycle.md b/doc/plugin/Cycle.md new file mode 100644 index 00000000..69a7d00a --- /dev/null +++ b/doc/plugin/Cycle.md @@ -0,0 +1,97 @@ +# Kaleidoscope-Cycle + +If you ever wanted a key that works like keys on old cell phones, when you press +a key and it cycles through a number of options in a sequence, then the cycling +key is what you are looking for. It is a bit different than on cell phones of +old, as it is a separate key, that works in combination of other keys: you press +a key, then the cycle key, and the cycle key will replace the previously input +symbol with another. Keep tapping the cycle key, and it will replace symbols +with new ones, in a loop. + +## Using the plugin + +To use the plugin, we need to include the header, and declare the behaviour +used. Then, we need to place a cycle key or two on the keymap. And finally, we +need to implement the [`cycleAction`][cycleaction] function that gets called +each time the cycling key triggers. + + [cycleaction]: #cycleactionpreviouskey-cyclecount + +```c++ +#include + +// Somewhere in the keymap: +Key_Cycle + +// later in the Sketch: +void cycleAction(Key previous_key, uint8_t cycle_count) { + if (previous_key.raw == Key_A.raw) { + cycleThrough (Key_B, Key_C, Key_D); + } +} + +KALEIDOSCOPE_INIT_PLUGINS(Cycle); + +void setup(void) { + Kaleidoscope.setup(); +} +``` + +## Keymap markup + +### `Key_Cycle` + +> The key code for the cycle key. There can be as many of this on the keymap, as +> many one wants, but they all behave the same. There is little point in having +> more than one on each side. + +## Plugin methods + +The plugin provides a `Cycle` object, but to implement the actions, we need to +define a function ([`cycleAction`][cycleaction]) outside of the object. A +handler, of sorts. The object also provides a helper method to replace the +previous symbol with another. The plugin also provides one macro that is +particularly useful, and in most cases, should be used over the `.replace()` +method explained below. + +### `cycleThrough(keys...)` + +> Cycles through all the possibilities given in `keys` (starting from the +> beginning once it reached the end). This should be used from +> the [`cycleAction`][cycleaction] function, once it is determined what sequence +> to cycle through. +> +> To make the cycling loop complete, the first element of the `keys` list should +> be the one that - when followed by the Cycle key - triggers the action. + +### `.replace(key)` + +> Deletes the previous symbol (by sending a `Backspace`), and inputs the new +> one. This is used by `cycleThrough()` above, behind the scenes. +> +> The recommended method is to use the macro, but in special circumstances, this +> function can be of direct use as well. + +## Overrideable methods + +### `cycleAction(previous_key, cycle_count)` + +> The heart and soul of the plugin, that must be defined in the Sketch. It will +> be called whenever the cycling key triggers, and the two arguments are the +> last key pressed (not counting repeated taps of the cycling key itself), and +> the number of times the cycling key has been pressed. +> +> It is up to us to decide what to do, and when. But the most common - and +> expected - action is to call `cycleThrough()` with a different sequence for +> each key we want to use together with the cycling key. + +## 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-Cycle/blob/master/examples/Cycle/Cycle.ino diff --git a/src/Kaleidoscope-Cycle.h b/src/Kaleidoscope-Cycle.h index d8b22f0c..d66fe39d 100644 --- a/src/Kaleidoscope-Cycle.h +++ b/src/Kaleidoscope-Cycle.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/Cycle.cpp b/src/kaleidoscope/plugin/Cycle.cpp similarity index 97% rename from src/Kaleidoscope/Cycle.cpp rename to src/kaleidoscope/plugin/Cycle.cpp index 4f16408a..ec279c7b 100644 --- a/src/Kaleidoscope/Cycle.cpp +++ b/src/kaleidoscope/plugin/Cycle.cpp @@ -20,6 +20,7 @@ #include "kaleidoscope/hid.h" namespace kaleidoscope { +namespace plugin { // --- state --- Key Cycle::last_non_cycle_key_; uint8_t Cycle::cycle_count_; @@ -80,10 +81,11 @@ EventHandlerResult Cycle::onKeyswitchEvent(Key &mapped_key, byte row, byte col, return EventHandlerResult::EVENT_CONSUMED; } -}; +} +} __attribute__((weak)) void cycleAction(Key previous_key, uint8_t cycle_count) { } -kaleidoscope::Cycle Cycle; +kaleidoscope::plugin::Cycle Cycle; diff --git a/src/Kaleidoscope/Cycle.h b/src/kaleidoscope/plugin/Cycle.h similarity index 95% rename from src/Kaleidoscope/Cycle.h rename to src/kaleidoscope/plugin/Cycle.h index ee85125e..d5004626 100644 --- a/src/Kaleidoscope/Cycle.h +++ b/src/kaleidoscope/plugin/Cycle.h @@ -28,6 +28,7 @@ }) namespace kaleidoscope { +namespace plugin { class Cycle : public kaleidoscope::Plugin { public: Cycle(void) {} @@ -41,8 +42,9 @@ class Cycle : public kaleidoscope::Plugin { static Key last_non_cycle_key_; static uint8_t cycle_count_; }; -}; +} +} void cycleAction(Key previous_key, uint8_t cycle_count); -extern kaleidoscope::Cycle Cycle; +extern kaleidoscope::plugin::Cycle Cycle;