Gergely Nagy 26340b7edb | 2 years ago | |
---|---|---|
.. | ||
src | 2 years ago | |
README.md | 4 years ago | |
library.properties | 4 years ago |
README.md
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 keysAutoShift.numberKeys()
: Number keys (number row, not numeric keypad)AutoShift.symbolKeys()
: Other printable symbolsAutoShift.arrowKeys()
: Navigational arrow keysAutoShift.functionKeys()
: All function keys (F1-F24)AutoShift.printableKeys()
: Letters, numbers, and symbolsAutoShift.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)
, wherecategories
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.