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.
107 lines
3.9 KiB
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
|