History

Gergely Nagy 8ac4d9f5c1 A more efficient way to handle onFocusEvent commands In the past, we were using `Focus.handleHelp()` to see if we're handling a `help` command, and print the commands supported by the handler. We also used `strcmp_P` directly to compare (parts of) our input against command supported by the handler. This approach works, but had multiple major disadvantages: it duplicated strings between `handleHelp` and the `strcmp_P` calls, and it relied on fragile substring pointers to save space. To replace all that, this patch implements a different approach. Help handling is split between a check (`Focus.inputMatchesHelp()`) and a reply (`Focus.printHelp()`), the latter of which takes a list of `PSTR()` strings, rather than one single string. This allows us to reuse the same strings for comparing against the handler's input. The new approach no longer uses the fragile substring pointers, nor does it use `strcmp_P` directly, but goes through a wrapper (`Focus.inputMatchesCommand()`) instead. These changes lead to a more readable pattern. While we do use longer strings as a result, there is less duplication, and the new patterns also require less code, so we end up with saving space, at least on AVR devices. The old methods are still available and usable, but they're deprecated. Signed-off-by: Gergely Nagy <algernon@keyboard.io>		2 years ago
..
src	A more efficient way to handle onFocusEvent commands	2 years ago
README.md	Convert Macros and DynamicMacros plugins to use MacroSupport plugin	3 years ago
library.properties	More library tweaking to comply with arduino requirements	4 years ago

README.md

DynamicMacros

Dynamic macros are similar to Macros, but unlike them, they can be re-defined without compiling and flashing new firmware: one can change dynamic macros via Focus, using a tool like Chrysalis.

Dynamic macros come with certain limitations, however: unlike the built-in macros, dynamic ones do not support running custom code, they can only play back a sequence of events (keys, mousekeys, etc), and do so whenever one presses the dynamic macro key.

You can define up to 32 dynamic macros, there is no limit on their length, except the amount of storage available on the keyboard.

Using the plugin

To use the plugin, we need to include the header, initialize the plugin with KALEIDOSCOPE_INIT_PLUGINS(), and reserve storage space for the macros. This is best illustrated with an example:

#include <Kaleidoscope.h>
#include <Kaleidoscope-EEPROMSettings.h>
#include <Kaleidoscope-FocusSerial.h>
#include <Kaleidoscope-DynamicMacros.h>

KALEIDOSCOPE_INIT_PLUGINS(
  EEPROMSettings,
  Focus,
  DynamicMacros
);

void setup() {
  Kaleidoscope.setup();

  DynamicMacros.reserve_storage(128);
}

Keymap markup

`DM(id)`

Places a dynamic macro key on the keymap, with the id number (0 to 31) as identifier. Pressing the key will immediately run the associated dynamic macro.

Plugin methods

The plugin provides a DynamicMacros object, with the following methods and properties available:

`.reserve_storage(size)`

Reserves size bytes of storage for dynamic macros. This must be called from the setup() method of your sketch, otherwise dynamic macros will not function.

`.play(macro_id)`

Plays back a macro, specified by macro_id.

`MACRO` steps

The plugin supports the same macro steps as the Macros plugin, please refer to the documentation therein.

Focus commands

The plugin provides two Focus commands: macros.map and macros.trigger.

`macros.map [macros...]`

Without arguments, displays all the stored macros. Each macro is terminated by an end marker (MACRO_ACTION_END), and the last macro is followed by an additional marker. The plugin will send back the entire dynamic macro storage space, even the data after the final marker.

With arguments, it replaces the current set of dynamic macros with the newly given ones. Macros are terminated by an end marker, and the last macro must be terminated by an additional one.

In both cases, the data sent or expected is a sequence of 8-bit values, a memory dump.

`macros.trigger macro_id`

Runs the dynamic macro associated with macro_id immediately. This can be used to test macros without having to place them on the keymap.

README.md

DynamicMacros

Using the plugin

Keymap markup

DM(id)

Plugin methods

.reserve_storage(size)

.play(macro_id)

MACRO steps