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.
Kaleidoscope/plugins/Kaleidoscope-Escape-OneShot
Gergely Nagy ddad1305e2
EscapeOneShot: Always treat `Key_OneShotCancel` as cancel key
3 years ago
..
src EscapeOneShot: Always treat `Key_OneShotCancel` as cancel key 3 years ago
README.md EscapeOneShot: Always treat `Key_OneShotCancel` as cancel key 3 years ago
library.properties More library tweaking to comply with arduino requirements 4 years ago

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.

Additionally, the special Key_OneShotCancel key will also count as a oneshot cancel key, would one want a dedicated key for the purpose.

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 Key_OneShotCancel, 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

Optional dependencies

Further reading

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