You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Kaleidoscope/README.md

107 lines
3.9 KiB

# Kaleidoscope-Cycle
![status][st:stable] [![Build Status][travis:image]][travis:status]
[travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-Cycle.svg?branch=master
[travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-Cycle
[st:stable]: https://img.shields.io/badge/stable-✔-black.svg?style=flat&colorA=44cc11&colorB=494e52
[st:broken]: https://img.shields.io/badge/broken-X-black.svg?style=flat&colorA=e05d44&colorB=494e52
[st:experimental]: https://img.shields.io/badge/experimental----black.svg?style=flat&colorA=dfb317&colorB=494e52
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 <Kaleidoscope-Cycle.h>
// 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);
}
}
void setup(void) {
USE_PLUGINS(&Cycle);
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