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.
100 lines
3.5 KiB
100 lines
3.5 KiB
# 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 <Kaleidoscope-Cycle.h>
|
|
|
|
// Somewhere in the keymap:
|
|
Key_Cycle
|
|
|
|
// later in the Sketch:
|
|
void cycleAction(Key previous_key, uint8_t cycle_count) {
|
|
bool is_shifted = previous_key.getFlags() & SHIFT_HELD;
|
|
if (previous_key.getKeyCode() == Key_A.getKeyCode() && is_shifted)
|
|
cycleThrough (LSHIFT(Key_A), LSHIFT(Key_B), LSHIFT(Key_C));
|
|
if (previous_key.getKeyCode() == Key_A.getKeyCode() && !is_shifted)
|
|
cycleThrough (Key_A, Key_B, Key_C);
|
|
}
|
|
|
|
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](Ranges.md)
|
|
|
|
## Further reading
|
|
|
|
Starting from the [example][plugin:example] is the recommended way of getting
|
|
started with the plugin.
|
|
|
|
[plugin:example]: ../../examples/Keystrokes/Cycle/Cycle.ino
|