Move the documentation to `doc/plugin/MagicCombo.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/365/head
parent
b95c4049c3
commit
d3e7364ac7
Before Width: | Height: | Size: 89 KiB After Width: | Height: | Size: 89 KiB |
@ -1,5 +1,75 @@
|
|||||||
Breaking changes in `MagicCombo`
|
# Kaleidoscope-MagicCombo
|
||||||
================================
|
|
||||||
|
The `MagicCombo` extension provides a way to perform custom actions when a
|
||||||
|
particular set of keys are held down together. The functionality assigned to
|
||||||
|
these keys are not changed, and the custom action triggers as long as all keys
|
||||||
|
within the set are pressed. The order in which they were pressed do not matter.
|
||||||
|
|
||||||
|
This can be used to tie complex actions to key chords.
|
||||||
|
|
||||||
|
## Using the extension
|
||||||
|
|
||||||
|
To use the extension, we must include the header, create actions for the magic
|
||||||
|
combos we want to trigger, and set up a mapping:
|
||||||
|
|
||||||
|
```c++
|
||||||
|
#include <Kaleidoscope.h>
|
||||||
|
#include <Kaleidoscope-Macros.h>
|
||||||
|
#include <Kaleidoscope-MagicCombo.h>
|
||||||
|
|
||||||
|
enum { KIND_OF_MAGIC };
|
||||||
|
|
||||||
|
void kindOfMagic(uint8_t combo_index) {
|
||||||
|
Macros.type(PSTR("It's a kind of magic!"));
|
||||||
|
}
|
||||||
|
|
||||||
|
USE_MAGIC_COMBOS(
|
||||||
|
[KIND_OF_MAGIC] = {
|
||||||
|
.action = kindOfMagic,
|
||||||
|
.keys = {R3C6, R3C9} // Left Fn + Right Fn
|
||||||
|
});
|
||||||
|
|
||||||
|
KALEIDOSCOPE_INIT_PLUGINS(MagicCombo, Macros);
|
||||||
|
|
||||||
|
void setup() {
|
||||||
|
Kaleidoscope.setup();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
It is recommended to use the `RxCy` macros of the core firmware to set the keys
|
||||||
|
that are part of a combination.
|
||||||
|
|
||||||
|
## Plugin properties
|
||||||
|
|
||||||
|
The extension provides a `MagicCombo` singleton object, with the following
|
||||||
|
property:
|
||||||
|
|
||||||
|
### `.min_interval`
|
||||||
|
|
||||||
|
> Restrict the magic action to fire at most once every `min_interval`
|
||||||
|
> milliseconds.
|
||||||
|
>
|
||||||
|
> Defaults to 500.
|
||||||
|
|
||||||
|
## Plugin callbacks
|
||||||
|
|
||||||
|
Whenever a combination is found to be held, the plugin will trigger the
|
||||||
|
specified action, which is just a regular method with a single `uint8_t`
|
||||||
|
argument: the index of the magic combo. This function will be called repeatedly
|
||||||
|
(every `min_interval` milliseconds) while the combination is held.
|
||||||
|
|
||||||
|
## Further reading
|
||||||
|
|
||||||
|
Starting from the [example][plugin:example] is the recommended way of getting
|
||||||
|
started with the plugin.
|
||||||
|
|
||||||
|
`RxCy` coordinates for a Model01:
|
||||||
|
|
||||||
|
![rxcy layout](../model01_coordinates.png)
|
||||||
|
|
||||||
|
[plugin:example]: https://github.com/keyboardio/Kaleidoscope-MagicCombo/blob/master/examples/MagicCombo/MagicCombo.ino
|
||||||
|
|
||||||
|
## Upgrading
|
||||||
|
|
||||||
To make `MagicCombo` more portable, and easier to use, we had to break the API
|
To make `MagicCombo` more portable, and easier to use, we had to break the API
|
||||||
previously provided, there was no way to maintain backwards compatibility. This
|
previously provided, there was no way to maintain backwards compatibility. This
|
Loading…
Reference in new issue