|
|
|
|
# Akela-MagicCombo
|
|
|
|
|
|
|
|
|
|
![status][st:stable]
|
|
|
|
|
|
|
|
|
|
[st:stable]: https://img.shields.io/badge/stable-✔-black.png?style=flat&colorA=44cc11&colorB=494e52
|
|
|
|
|
[st:broken]: https://img.shields.io/badge/broken-X-black.png?style=flat&colorA=e05d44&colorB=494e52
|
|
|
|
|
[st:experimental]: https://img.shields.io/badge/experimental----black.png?style=flat&colorA=dfb317&colorB=494e52
|
|
|
|
|
|
|
|
|
|
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 a dictionary, and
|
|
|
|
|
configure the plugin to use it:
|
|
|
|
|
|
|
|
|
|
```c++
|
|
|
|
|
#include <Akela-MagicCombo.h>
|
|
|
|
|
|
|
|
|
|
static const Akela::MagicCombo::dictionary_t dictionary[] PROGMEM = {
|
|
|
|
|
{R1C3 | R2C1 | R2C4 | R2C7, // left hand,
|
|
|
|
|
R0C11 | R1C12 | R2C14 //right hand
|
|
|
|
|
},
|
|
|
|
|
{0, 0}
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
void setup (void) {
|
|
|
|
|
MagicCombo.configure (dictionary);
|
|
|
|
|
|
|
|
|
|
Keyboardio.setup (KEYMAP_SIZE);
|
|
|
|
|
Keyboardio.use (&MagicCombo, NULL);
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The dictionary **must** reside in `PROGMEM`, and is a list of tuples. Each
|
|
|
|
|
element in the array has two fields: the left hand state, and the right hand
|
|
|
|
|
state upon which to trigger the custom action. Both of these are bit fields,
|
|
|
|
|
each bit set tells the extension that the key with that index must be held for
|
|
|
|
|
the action to trigger. It is recommended to use the `RxCy` macros of the core
|
|
|
|
|
`KeyboardioFirmware`, and *or* them together to form a bitfield.
|
|
|
|
|
|
|
|
|
|
The dictionary **must** end with an element containing zero values for both the
|
|
|
|
|
left and the right halves.
|
|
|
|
|
|
|
|
|
|
## Extension methods
|
|
|
|
|
|
|
|
|
|
The extension provides a `MagicCombo` singleton object, with the following method:
|
|
|
|
|
|
|
|
|
|
### `.configure(dictionary[, timeout])`
|
|
|
|
|
|
|
|
|
|
> Configures the extension to use the supplied dictionary, and restrict it to
|
|
|
|
|
> fire at most once every `timeout` cycles.
|
|
|
|
|
>
|
|
|
|
|
> If the timeout is not specified, it defaults to `DEFAULT_TIMEOUT`, which in
|
|
|
|
|
> turn is 40 cycles.
|
|
|
|
|
|
|
|
|
|
## Overrideable methods
|
|
|
|
|
|
|
|
|
|
Whenever an combination is found to be held, the extension will trigger an
|
|
|
|
|
action, in each scan cycle until the keys remain held. This is done by calling
|
|
|
|
|
the overrideable `magicComboActions` function:
|
|
|
|
|
|
|
|
|
|
### `magicComboActions(comboIndex, leftHand, rightHand)`
|
|
|
|
|
|
|
|
|
|
> Called whenever a combination is found to be held. The function by default
|
|
|
|
|
> does nothing, and it is recommended to override it from within the Sketch.
|
|
|
|
|
>
|
|
|
|
|
> The first argument will be the index in the dictionary, the other two are the
|
|
|
|
|
> key states on the left and right halves, respectively.
|
|
|
|
|
>
|
|
|
|
|
> Plugins that build upon this extensions *should not* override this function,
|
|
|
|
|
> but provide helpers that can be called from it. An override should only happen
|
|
|
|
|
> in the Sketch.
|
|
|
|
|
|
|
|
|
|
## Further reading
|
|
|
|
|
|
|
|
|
|
Starting from the [example][plugin:example] is the recommended way of getting
|
|
|
|
|
started with the plugin.
|
|
|
|
|
|
|
|
|
|
[plugin:example]: https://github.com/keyboardio/Akela-MagicCombo/blob/master/examples/MagicCombo/MagicCombo.ino
|
