Kaleidoscope/plugins/Kaleidoscope-AutoShift

AutoShift

AutoShift allows you to type shifted characters by long-pressing a key, rather than chording it with a modifier key.

Using the plugin

Using the plugin with its defaults is as simple as including the header, and enabling the plugin:

#include <Kaleidoscope.h>
#include <Kaleidoscope-AutoShift.h>

KALEIDOSCOPE_INIT_PLUGINS(AutoShift);

With AutoShift enabled, when you first press a key that AutoShift acts on, its output will be delayed. If you hold the key down long enough, you will see the shifted symbol appear in the output. If you release the key before the timeout, the output will be unshifted.

Turning AutoShift on and off

The AutoShift object provides three methods for turning itself on and off:

• To turn the plugin on, call AutoShift.enable().
• To turn the plugin off, call AutoShift.disable().
• To toggle the plugin's state, call AutoShift.toggle().

Note: Disabling the AutoShift plugin does not affect which Key categories it will affect when it is re-enabled.

Setting the AutoShift long-press delay

To set the length of time AutoShift will wait before adding the shift modifier to the key's output, use AutoShift.setTimeout(t), where t is a number of milliseconds.

Configuring which keys get auto-shifted

AutoShift provides a set of key categories that can be independently added or removed from the set of keys that will be auto-shifted when long-pressed:

• AutoShift.letterKeys(): Letter keys
• AutoShift.numberKeys(): Number keys (number row, not numeric keypad)
• AutoShift.symbolKeys(): Other printable symbols
• AutoShift.arrowKeys(): Navigational arrow keys
• AutoShift.functionKeys(): All function keys (F1-F24)
• AutoShift.printableKeys(): Letters, numbers, and symbols
• AutoShift.allKeys(): All non-modifier USB Keyboard keys

These categories are restricted to USB Keyboard-type keys, and any modifier flags attached to the key is ignored when determining if it will be auto-shifted. Any of the above expressions can be used as the category parameter in the functions described below.

• To include a category in the set that will be auto-shifted, call AutoShift.enable(category)
• To remove a category from the set that will be auto-shifted, call AutoShift.disable(category)
• To set the full list of categories that will be auto-shifted, call AutoShift.setEnabled(categories), where categories can be either a single category from the above list, or list of categories combined using the | (bitwise-or) operator (e.g. AutoShift.setEnabled(AutoShift.letterKeys() | AutoShift.numberKeys())).

Advanced customization of which keys get auto-shifted

If the above categories are not sufficient for your auto-shifting needs, it is possible to get even finer-grained control of which keys are affected by AutoShift, by overriding the isAutoShiftable() method in your sketch. For example, to make AutoShift only act on keys A and Z, include the following code in your sketch:

bool AutoShift::isAutoShiftable(Key key) {
  if (key == Key_A || key == key_Z)
    return true;
  return false;
}

As you can see, this method takes a Key as its input and returns either true (for keys eligible to be auto-shifted) or false (for keys AutoShift will leave alone).

Plugin compatibility

If you're using AutoShift in a sketch that also includes the Qukeys and/or SpaceCadet plugins, make sure to register AutoShift after those other plugins in order to prevent auto-shifts from getting clobbered. The recommended order is as follows:

KALEIDOSCOPE_INIT_PLUGINS(Qukeys, SpaceCadet, AutoShift)

It's not generally recommended to use AutoShift on the same key(s) handled by either Qukeys or SpaceCadet, as this can result in confusing behaviour.

Further reading

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