Move the documentation to `doc/plugin/Leader.md`, sources under `src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of merging plugins into a single monorepo. Signed-off-by: Gergely Nagy <algernon@keyboard.io>pull/389/head
Gergely Nagy
6 years ago
parent
13f92255cb
commit
e37669a623
@ -0,0 +1,107 @@
|
|||||||
|
# Kaleidoscope-Leader
|
||||||
|
|
||||||
|
Leader keys are a kind of key where when they are tapped, all following keys are
|
||||||
|
swallowed, until the plugin finds a matching sequence in the dictionary, it
|
||||||
|
times out, or fails to find any possibilities. When a sequence is found, the
|
||||||
|
corresponding action is executed, but the processing still continues. If any key
|
||||||
|
is pressed that is not the continuation of the existing sequence, processing
|
||||||
|
aborts, and the key is handled normally.
|
||||||
|
|
||||||
|
This behaviour is best described with an example. Suppose we want a behaviour
|
||||||
|
where `LEAD u` starts unicode input mode, and `LEAD u h e a r t` should result
|
||||||
|
in a heart symbol being input, and we want `LEAD u 0 0 e 9 SPC` to input `é`,
|
||||||
|
and any other hex code that follows `LEAD u`, should be handled as-is, and
|
||||||
|
passed to the host. Obviously, we can't have all of this in a dictionary.
|
||||||
|
|
||||||
|
So we put `LEAD u` and `LEAD u h e a r t` in the dictionary only. The first will
|
||||||
|
start unicode input mode, the second will type in the magic sequence that
|
||||||
|
results in the symbol, and then aborts the leader sequence processing. With this
|
||||||
|
setup, if we type `LEAD u 0`, then `LEAD u` will be handled first, and start
|
||||||
|
unicode input mode. Then, at the `0`, the plugin notices it is not part of any
|
||||||
|
sequence, so aborts leader processing, and passes the key on as-is, and it ends
|
||||||
|
up being sent to the host. Thus, we covered all the cases of our scenario!
|
||||||
|
|
||||||
|
## Using the plugin
|
||||||
|
|
||||||
|
To use the plugin, one needs to include the header, implement some actions,
|
||||||
|
create a dictionary, and configure the provided `Leader` object to use the
|
||||||
|
dictionary:
|
||||||
|
|
||||||
|
```c++
|
||||||
|
#include <Kaleidoscope.h>
|
||||||
|
#include <Kaleidoscope-Leader.h>
|
||||||
|
|
||||||
|
static void leaderA(uint8_t seq_index) {
|
||||||
|
Serial.println("leaderA");
|
||||||
|
}
|
||||||
|
|
||||||
|
static void leaderTX(uint8_t seq_index) {
|
||||||
|
Serial.println("leaderTX");
|
||||||
|
}
|
||||||
|
|
||||||
|
static const kaleidoscope::Leader::dictionary_t leader_dictionary[] PROGMEM =
|
||||||
|
LEADER_DICT({LEADER_SEQ(LEAD(0), Key_A), leaderA},
|
||||||
|
{LEADER_SEQ(LEAD(0), Key_T, Key_X), leaderTX});
|
||||||
|
|
||||||
|
KALEIDOSCOPE_INIT_PLUGINS(Leader);
|
||||||
|
|
||||||
|
void setup() {
|
||||||
|
Serial.begin(9600);
|
||||||
|
|
||||||
|
Kaleidoscope.setup();
|
||||||
|
|
||||||
|
Leader.dictionary = leader_dictionary;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The dictionary is made up of a list of keys, and an action callback. Using the
|
||||||
|
`LEADER_DICT` and `LEADER_SEQ` helpers is recommended. The dictionary *must* be
|
||||||
|
marked `PROGMEM`!
|
||||||
|
|
||||||
|
**Note** that we need to use the `Leader` object before any other that adds or
|
||||||
|
changes key behaviour! Failing to do so may result in unpredictable behaviour.
|
||||||
|
|
||||||
|
## Plugin methods
|
||||||
|
|
||||||
|
The plugin provides the `Leader` object, with the following methods and properties:
|
||||||
|
|
||||||
|
### `.dictionary`
|
||||||
|
|
||||||
|
> Set this property to the dictionary `Leader` should use. The dictionary is an
|
||||||
|
> array of `kaleidoscope::Leader::dictionary_t` elements. Each element is made
|
||||||
|
> up of two elements, the first being a list of keys, the second an action to
|
||||||
|
> perform when the sequence is found.i
|
||||||
|
>
|
||||||
|
> The dictionary *MUST* reside in `PROGMEM`.
|
||||||
|
|
||||||
|
### `.reset()`
|
||||||
|
|
||||||
|
> Finishes the leader sequence processing. This is best called from actions that
|
||||||
|
> are final actions, where one does not wish to continue the leader sequence
|
||||||
|
> further in the hopes of finding a longer match.
|
||||||
|
|
||||||
|
### `.time_out`
|
||||||
|
|
||||||
|
> The number of milliseconds to wait before a sequence times out. Once the
|
||||||
|
> sequence timed out, if there is a partial match with an action, that will be
|
||||||
|
> performed, otherwise the Leader sequence will simply reset.
|
||||||
|
>
|
||||||
|
> Defaults to 1000.
|
||||||
|
|
||||||
|
## 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-Leader/blob/master/examples/Leader/Leader.ino
|
||||||
|
|
||||||
|
## Upgrading
|
||||||
|
|
||||||
|
Previous versions of `Leader` used `kaleidoscope::Leader::dictionary_t` as a
|
||||||
|
type for defining the dictionary. In newer versions, this is
|
||||||
|
`kaleidoscope::plugin::Leader::dictionary_t`. The old name still works, but will
|
||||||
|
be removed by 2019-01-14.
|
||||||
Loading…
Reference in new issue