Kaleidoscope/plugins/Kaleidoscope-Escape-OneShot/README.md

Escape-OneShot

Turn the Esc key into a special key, that can cancel any active OneShot effect - or act as the normal Esc key if none are active, or if any of them are still held. For those times when one accidentally presses a one-shot key, or change their minds.

Using the plugin

To use the plugin, one needs to include the header, and activate it. No further configuration is necessary.

#include <Kaleidoscope.h>
#include <Kaleidoscope-OneShot.h>
#include <Kaleidoscope-Escape-OneShot.h>

KALEIDOSCOPE_INIT_PLUGINS(OneShot,
                          EscapeOneShot);

void setup () {
  Kaleidoscope.setup ();
}

If one wishes to configure the plugin at run-time via Focus, the optional EscapeOneShotConfig plugin must also be enabled:

#include <Kaleidoscope.h>
#include <Kaleidoscope-EEPROM-Settings.h>
#include <Kaleidoscope-FocusSerial.h>
#include <Kaleidoscope-OneShot.h>
#include <Kaleidoscope-Escape-OneShot.h>

KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings,
                          Focus,
                          OneShot,
                          EscapeOneShot,
                          EscapeOneShotConfig);

void setup () {
  Kaleidoscope.setup ();
}

The plugin only makes sense when using one-shot keys.

Plugin methods

The plugin provides the EscapeOneShot object, which has the following public configuration methods:

.setCancelKey(key)

Changes the Key value that will trigger deactivation of one-shot (including sticky) keys. The default is to use Key_Escape (the normal Esc key), but if you would rather have a dedicated key (so that you can use Key_Escape in combination with one-shot modifiers), there is the special OneShotCancelKey, which will not have any side effects.

.getCancelKey(key)

Returns the Key value that will trigger deactivation of one-shot (including sticky) keys.

.enable(), .disable(), .toggle(), and .isEnabled()

Enables, disables, toggles, and returns the enabled state of the plugin, respectively.

By default, the plugin starts enabled.

Focus commands

The plugin provides two Focus commands: escape_oneshot.enabled, and escape_oneshot.cancel_key.

escape_oneshot.enabled [0|1]

Without arguments, returns whether the plugin is enabled or not.

With an argument, enables or disables it.

escape_oneshot.cancel_key [keycode]

Without an argument, returns the raw 16-bit keycode of the cancel key set.

With an argument - a raw 16-bit keycode -, sets the cancel key to the one corresponding to the given code.

Dependencies

• Kaleidoscope-OneShot

Optional dependencies

• Kaleidoscope-EEPROM-Settings
• Kaleidoscope-FocusSerial

Further reading

Starting from the example is the recommended way of getting started with the plugin.