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.
101 lines
3.9 KiB
101 lines
3.9 KiB
# 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:
|
|
|
|
```c++
|
|
#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:
|
|
|
|
```c++
|
|
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:
|
|
|
|
```c++
|
|
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][plugin:example] is the recommended way of getting
|
|
started with the plugin.
|
|
|
|
[plugin:example]: /examples/Keystrokes/AutoShift/AutoShift.ino
|