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.
227 lines
9.8 KiB
227 lines
9.8 KiB
# Qukeys
|
|
|
|
## Concept
|
|
|
|
This Kaleidoscope plugin allows you to overload keys on your keyboard so that
|
|
they produce one keycode (i.e. symbol) when tapped, and a different keycode --
|
|
most likely a modifier (e.g. `shift` or `alt`) -- when held. The name is a play
|
|
on the term _qubit_; a qukey is a "quantum key". When it is first pressed it is
|
|
in a superposition of states until some event determines which state it ends up
|
|
in. While a qukey is in this indeterminate state, its key press event and any
|
|
subsequent key presses are delayed until something determines the qukey's
|
|
ultimate state.
|
|
|
|
Most likely, what determines the qukey's state (_primary_ or _alternate_) is the
|
|
release of a key; if the qukey is released before a subsequent key, it will take
|
|
on its primary value (most likely a printable character), but if the subsequent
|
|
key is released first, it will take on its alternate value (usually a modifier).
|
|
|
|
Qukeys is designed to make it practical to use these overloaded keys on the home
|
|
row, where similar designs have historically been problematic. For some typists
|
|
(particularly those who are accustomed to rolling over from modifiers to
|
|
modified keys, rather than deliberately holding the modifier until the
|
|
subsequent key has been released), this may still not work perfectly with
|
|
Qukeys, but some people have reported good results with home-row qukeys.
|
|
|
|
|
|
## Setup
|
|
|
|
- Include the header file:
|
|
```
|
|
#include <Kaleidoscope-Qukeys.h>
|
|
```
|
|
- Use the plugin in the `KALEIDOSCOPE_INIT_PLUGINS` macro:
|
|
```
|
|
KALEIDOSCOPE_INIT_PLUGINS(Qukeys);
|
|
```
|
|
|
|
- Define some `Qukeys` of the format `Qukey(layer, key_addr, alternate_key)`.
|
|
Layers and key addresses are all zero-indexed, in key addresses rows are top to bottom and
|
|
columns are left to right:
|
|
|
|
- For the Keyboardio Model 01, key coordinates refer to [this header
|
|
file](https://github.com/keyboardio/Kaleidoscope/blob/master/src/kaleidoscope/device/keyboardio/Model01.h#L167-L179).
|
|
|
|
```
|
|
QUKEYS(
|
|
// left-side modifiers
|
|
kaleidoscope::plugin::Qukey(0, KeyAddr(2, 1), Key_LeftGui), // A
|
|
kaleidoscope::plugin::Qukey(0, KeyAddr(2, 2), Key_LeftAlt), // S
|
|
kaleidoscope::plugin::Qukey(0, KeyAddr(2, 3), Key_LeftControl), // D
|
|
kaleidoscope::plugin::Qukey(0, KeyAddr(2, 4), Key_LeftShift), // F
|
|
// left-side layer shifts
|
|
kaleidoscope::plugin::Qukey(0, KeyAddr(3, 3), ShiftToLayer(NUMPAD)), // C
|
|
kaleidoscope::plugin::Qukey(0, KeyAddr(3, 4), ShiftToLayer(FUNCTION)), // V
|
|
```
|
|
|
|
`Qukeys` will work best if it's the first plugin in the `INIT()` list, because when typing
|
|
overlap occurs, it will (temporarily) mask keys and block them from being processed by
|
|
other plugins. If those other plugins handle the keypress events first, it may not work as
|
|
expected. It doesn't _need_ to be first, but if it's `INIT()`'d after another plugin that
|
|
handles typing events, especially one that sends extra keyboard HID reports, it is more
|
|
likely to generate errors and out-of-order events.
|
|
|
|
|
|
## Configuration
|
|
|
|
### `.setHoldTimeout(timeout)`
|
|
|
|
> Sets the time (in milliseconds) after which a qukey held on its own will take
|
|
> on its alternate state. Note: this is not the primary determining factor for a
|
|
> qukey's state. It is not necessary to wait this long before pressing a key
|
|
> that should be modified by the qukey's alternate value. The primary function
|
|
> of this timeout is so that a qukey can be used as a modifier for an separate
|
|
> pointing device (i.e. `shift` + `click`).
|
|
>
|
|
> Defaults to `250`.
|
|
|
|
### `.setOverlapThreshold(percentage)`
|
|
|
|
> This sets a variable that allows the user to roll over from a qukey to a
|
|
> subsequent key (i.e. the qukey is released first), and still get the qukey's
|
|
> alternate (modifier) state.
|
|
>
|
|
> The `percentage` parameter should be between `1` and `100` (`75` means 75%),
|
|
> and represents the fraction of the _subsequent_ key press's duration that
|
|
> overlaps with the qukey's press. If the subsequent key is released soon enough
|
|
> after the qukey is released, the percentage overlap will be high, and the
|
|
> qukey will take on its alternate (modifier) value. If, on the other hand, the
|
|
> subsequent key is held longer after the qukey is released, the qukey will take
|
|
> on its primary (non-modifier) value.
|
|
>
|
|
> Setting `percentage` to a low value (e.g. `30`) will result in a longer grace
|
|
> period. If you're getting primary values when you intended modifiers, try
|
|
> decreasing this setting. If, on the other hand, you start getting modifiers
|
|
> when you intend primary values, try increasing this setting. If you're getting
|
|
> both, the only solution is to change your typing habits, unfortunately.
|
|
>
|
|
> Defaults to `80`.
|
|
|
|
### `.setMinimumHoldTime(min_hold_time)`
|
|
|
|
> Sets the minimum amount of time (in milliseconds) a qukey must be held before
|
|
> it is allowed to resolve to its alternate `Key` value. Use this if you find
|
|
> that you're getting unintended alternate values (i.e. modifiers) while typing
|
|
> on home-row qukeys, despite setting the overlap threshold (see above) to
|
|
> 100%. It may mean that you'll need to slow down when using Qukeys to get
|
|
> modifiers, however.
|
|
>
|
|
> Defaults to `50` (milliseconds).
|
|
|
|
### `.activate()`
|
|
### `.deactivate()`
|
|
### `.toggle()`
|
|
|
|
> Activate/deactivate `Qukeys` plugin.
|
|
|
|
### DualUse key definitions
|
|
|
|
In addition to normal `Qukeys` described above, Kaleidoscope-Qukeys also treats
|
|
DualUse keys in the keymap as `Qukeys`. This makes `Qukeys` a drop-in replacement
|
|
for the `DualUse` plugin, without the need to edit the keymap.
|
|
|
|
The plugin provides a number of macros one can use in keymap definitions:
|
|
|
|
#### `CTL_T(key)`
|
|
|
|
> A key that acts as the *left* `Control` when held, or used in conjunction with
|
|
> other keys, but as `key` when tapped in isolation. The `key` argument must be
|
|
> a plain old key, and can't have any modifiers or anything else applied.
|
|
|
|
#### `ALT_T(key)`
|
|
|
|
> A key that acts as the *left* `Alt` when held, or used in conjunction with
|
|
> other keys, but as `key` when tapped in isolation. The `key` argument must be
|
|
> a plain old key, and can't have any modifiers or anything else applied.
|
|
|
|
#### `SFT_T(key)`
|
|
|
|
> A key that acts as the *left* `Shift` when held, or used in conjunction with
|
|
> other keys, but as `key` when tapped in isolation. The `key` argument must be
|
|
> a plain old key, and can't have any modifiers or anything else applied.
|
|
|
|
#### `GUI_T(key)`
|
|
|
|
> A key that acts as the *left* `GUI` when held, or used in conjunction with
|
|
> other keys, but as `key` when tapped in isolation. The `key` argument must be
|
|
> a plain old key, and can't have any modifiers or anything else applied.
|
|
|
|
#### `MT(mod, key)`
|
|
|
|
> A key that acts as `mod` when held, or used in conjunction with other keys,
|
|
> but as `key` when tapped in isolation. The `key` argument must be a plain old
|
|
> key, and can't have any modifiers or anything else applied. The `mod` argument
|
|
> can be any of the modifiers, *left* or *right* alike.
|
|
|
|
#### `LT(layer, key)`
|
|
|
|
> A key that momentarily switches to `layer` when held, or used in conjunction
|
|
> with other keys, but as `key` when tapped in isolation. The `key` argument
|
|
> must be a plain old key, and can't have any modifiers or anything else
|
|
> applied.
|
|
|
|
DualUse keys are more limited than `Qukey` definitions, which can contain any
|
|
valid `Key` value for both the primary and alternate keys, but they take up less
|
|
space in program memory, and are just as functional for typical definitions.
|
|
|
|
|
|
### SpaceCadet Emulation
|
|
|
|
It is possible to define a `Qukey` on a key with a _primary_ value that is a
|
|
modifier. In this case, the qukey is treated specially, and the _primary_ value
|
|
is used when the key is held, rather than the alternate value. The _alternate_
|
|
value is only used if the qukey is tapped on its own, without rolling over to
|
|
any other key. This is a reasonable facsimile of the behaviour of the SpaceCadet
|
|
plugin, and is much more suitable for keys that are mainly used as modifiers,
|
|
with an additional "tap" feature.
|
|
|
|
In addition to working this way on keyboard modifiers (`shift`, `control`, _et
|
|
al_), this works for keys that are primarily layer shift keys
|
|
(e.g. `ShiftToLayer(N)`).
|
|
|
|
As an added bonus, if Qukeys is deactivated, such a key reverts to being a
|
|
modifier, because that's what's in the keymap.
|
|
|
|
|
|
### The Wildcard Layer
|
|
|
|
There is a special value (`Qukeys::layer_wildcard`) that can be used in place of
|
|
the layer number in the definition of a `Qukey`. This will define a qukey with
|
|
the given alternate value on all layers, regardless of what the primary value is
|
|
for that key on the top currently active layer.
|
|
|
|
|
|
## Design & Implementation
|
|
|
|
When a qukey is pressed, it doesn't immediately add a corresponding keycode to
|
|
the HID report; it adds that key to a queue, and waits until one of three things
|
|
happens:
|
|
|
|
1. the qukey is released
|
|
1. a subsequently-pressed key is released
|
|
1. a time limit is reached
|
|
|
|
Until one of those conditions is met, all subsequent keypresses are simply added
|
|
to the queue, and no new reports are sent to the host. Once a condition is met,
|
|
the qukey is flushed from the queue, and so are any subsequent keypresses (up
|
|
to, but not including, the next qukey that is still pressed).
|
|
|
|
Basically, if you hold the qukey, then press and release some other key, you'll
|
|
get the alternate keycode (probably a modifier) for the qukey, even if you don't
|
|
wait for a timeout. If you're typing quickly, and there's some overlap between
|
|
two keypresses, you won't get the alternate keycode, and the keys will be
|
|
reported in the order that they were pressed -- as long as the keys are released
|
|
in the same order they were pressed.
|
|
|
|
The time limit is mainly there so that a qukey can be used as a modifier (in its
|
|
alternate state) with a second input device (e.g. a mouse). It can be quite
|
|
short (200ms is probably short enough) -- as long as your "taps" while typing
|
|
are shorter than the time limit, you won't get any unintended alternate
|
|
keycodes.
|
|
|
|
## Further reading
|
|
|
|
The [example][plugin:example] can help to learn how to use this plugin.
|
|
|
|
[plugin:example]: ../../examples/Keystrokes/Qukeys/Qukeys.ino
|