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.
102 lines
3.5 KiB
102 lines
3.5 KiB
5 years ago
|
# Kaleidoscope-DynamicTapDance
|
||
|
|
|
||
|
|
The `DynamicTapDance` plugin allows one to set up [TapDance][plugin:tapdance] keys
|
||
|
|
without the need to compile and flash new firmware: one can change dynamic
|
||
|
|
dances via [Focus][plugin:focus], using a tool like [Chrysalis][chrysalis].
|
||
|
|
|
||
|
|
[plugin:tapdance]: TapDance.md
|
||
|
|
[plugin:focus]: FocusSerial.md
|
||
|
|
[chrysalis]: https://github.com/keyboardio/Chrysalis
|
||
|
|
|
||
|
|
Dynamic dances come with certain limitations, however: unlike the built-in ones,
|
||
|
|
dynamic ones do not support running custom code. They can only choose a key from
|
||
|
|
a list of possibilities. Given a list of keys, the plugin will choose the one
|
||
|
|
corresponding to the number of taps on the key, just like `TapDance` itself does.
|
||
|
|
|
||
|
|
Basically, this plugin allows us to store `tapDanceActionKeys` key lists in the
|
||
|
|
on-board memory of our keyboard.
|
||
|
|
|
||
|
|
You can define up to 16 dynamic dances, there is no limit on their length,
|
||
|
|
except the amount of storage available on the keyboard. You can even mix them
|
||
|
|
with built-in dances! But the total number of tap-dances is 16.
|
||
|
|
|
||
|
|
## Using the plugin
|
||
|
|
|
||
|
|
To use the plugin, we need to include the header, tell the firmware to `use` the
|
||
|
|
plugin, and reserve storage space for the dances. This is best illustrated with
|
||
|
|
an example:
|
||
|
|
|
||
|
|
```c++
|
||
|
|
#include <Kaleidoscope.h>
|
||
|
|
#include <Kaleidoscope-EEPROMSettings.h>
|
||
|
|
#include <Kaleidoscope-FocusSerial.h>
|
||
|
|
#include <Kaleidoscope-TapDance.h>
|
||
|
|
#include <Kaleidoscope-DynamicTapDance.h>
|
||
|
|
|
||
|
|
KALEIDOSCOPE_INIT_PLUGINS(
|
||
|
|
EEPROMSettings,
|
||
|
|
Focus,
|
||
|
|
TapDance,
|
||
|
|
DynamicTapDance
|
||
|
|
);
|
||
|
|
|
||
|
|
void tapDanceAction(uint8_t tap_dance_index, KeyAddr key_addr, uint8_t tap_count, kaleidoscope::plugin::TapDance::ActionType tap_dance_action) {
|
||
|
|
DynamicTapDance.dance(tap_dance_index, key_addr, tap_count, tap_dance_action);
|
||
|
|
}
|
||
|
|
|
||
|
|
void setup() {
|
||
|
|
Kaleidoscope.setup();
|
||
|
|
|
||
|
|
// 0 is the amount of built-in dances we have.
|
||
|
|
// 128 is how much space (in bytes) we reserve for dances.
|
||
|
|
DynamicTapDance.setup(0, 128);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Plugin methods
|
||
|
|
|
||
|
|
The plugin provides a `DynamicTapDance` object, with the following methods and properties available:
|
||
|
|
|
||
|
|
### `.setup(builtin_dances, size)`
|
||
|
|
|
||
|
|
> Reserves `size` bytes of storage for dynamic dances. This must be called from
|
||
|
|
> the `setup()` method of your sketch, otherwise dynamic tap-dances will not
|
||
|
|
> function.
|
||
|
|
>
|
||
|
|
> The `builtin_dances` argument tells the plugin how many built-in dances there
|
||
|
|
> are.
|
||
|
|
|
||
|
|
### `.dance(index, key_addr, tap_count, tap_dance_action)`
|
||
|
|
|
||
|
|
> Performs a given dance (`index`) made on the key at `key_addr` address, which
|
||
|
|
> has been tapped `tap_count` times, and the action to perform is
|
||
|
|
> `tap_dance_action`.
|
||
|
|
>
|
||
|
|
> This mirrors the overrideable `tapDanceAction()` method of
|
||
|
|
> [TapDance][plugin:tapdance], and is intended to be called from therein.
|
||
|
|
|
||
|
|
## Focus commands
|
||
|
|
|
||
|
|
The plugin provides one Focus command: `tapdance.ap`.
|
||
|
|
|
||
|
|
### `tapdance.map [dances...]`
|
||
|
|
|
||
|
|
> Without arguments, displays all the stored dances. Each dance is terminated by
|
||
|
|
> an end marker (`0`, aka `Key_NoKey`), and the last dance is followed by an
|
||
|
|
> additional marker. The plugin will send back the entire dynamic tap-dance
|
||
|
|
> storage space, even data after the final marker.
|
||
|
|
>
|
||
|
|
> With arguments, it replaces the current set of dynamic dances with the newly
|
||
|
|
> given ones. Dances are terminated by an end marker, and the last macro must be
|
||
|
|
> terminated by an additional one. It is up to the caller to make sure these
|
||
|
|
> rules are obeyed.
|
||
|
|
>
|
||
|
|
> In both cases, the data sent or expected is a sequence of 16-bit values, a
|
||
|
|
> memory dump.
|
||
|
|
|
||
|
|
## Dependencies
|
||
|
|
|
||
|
|
* [Kaleidoscope-EEPROM-Settings](EEPROM-Settings.md)
|
||
|
|
* [Kaleidoscope-FocusSerial](FocusSerial.md)
|
||
|
|
* [Kaleidoscope-TapDance](TapDance.md)
|