Florian Bruhin 4a6aea650d | 3 years ago | |
---|---|---|
.. | ||
src | 3 years ago | |
README.md | 4 years ago | |
library.properties | 4 years ago |
README.md
OneShot
One-shots are a new kind of behaviour for your standard modifier and momentary layer keys: instead of having to hold them while pressing other keys, they can be tapped and released, and will remain active until any other key is pressed subject to a time-out.
In short, they turn Shift, A
into Shift+A
, and Fn, 1
to Fn+1
. The main
advantage is that this allows us to place the modifiers and layer keys to
positions that would otherwise be awkward when chording. Nevertheless, they
still act as normal when held, that behaviour is not lost.
Furthermore, if a one-shot key is double-tapped ie tapped two times in quick succession, it becomes sticky, and remains active until disabled with a third tap. This can be useful when one needs to input a number of keys with the modifier or layer active, and does not wish to hold the key down. If this "stickability" feature is undesirable, it can be unset (and later again set) for individual modifiers/layers. If stickability is unset, double-tapping a one-shot modifier will just restart the timer.
To make multi-modifier, or multi-layer shortcuts possible, one-shot keys remain
active if another one-shot of the same type is tapped, so Ctrl, Alt, b
becomes
Ctrl+Alt+b
, and L1, L2, c
is turned into L1+L2+c
. Furthermore, modifiers
and other layer keys do not cancel the one-shot effect, either.
Using One-Shot keys
To enter one-shot mode, tap quickly on a one-shot key. The next
normal (non-one-shot) key you press will have the modifier applied,
and then the modifier will automatically turn off. If the Shift key is
a one-shot modifier, then hitting Shift, a, b
will give you Ab
,
if you hit shift quickly.
Longish keypresses do not activate one-shot mode. If you press Shift, a, b
, as above, but hold the Shift key a bit longer, you'll get ab
.
To enter sticky mode, tap twice quickly on a one-shot key. The
modifier will now stay on until you press it again. Continuing the
Shift
example, tapping Shift, Shift
quickly and then a, b, c, Shift, d, e, f
will give you ABCdef
.
This can be a bit tricky; combining this plugin with LED-ActiveModColor will help you understand what state your one-shot is in; when a one-shot key is active, it will have a yellow LED highlight; when sticky, a red highlight. When it is in a "held" state, but will be deactivated when released like any non-one-shot key, it will have a white highlight. (These colors are configurable.)
Using the plugin
After adding one-shot keys to the keymap, all one needs to do, is enable the plugin:
#include <Kaleidoscope.h>
#include <Kaleidoscope-OneShot.h>
// somewhere in the keymap...
OSM(LeftControl), OSL(_FN)
KALEIDOSCOPE_INIT_PLUGINS(OneShot);
void setup() {
Kaleidoscope.setup();
}
Keymap markup
There are two macros the plugin provides:
OSM(mod)
A macro that takes a single argument, the name of the modifier:
LeftControl
,LeftShift
,LeftAlt
,LeftGui
or their right-side variant. When marked up with this macro, the modifier will act as a one-shot modifier.
OSL(layer)
Takes a layer number as argument, and sets up the key to act as a one-shot layer key.
Please note that while
Kaleidoscope
supports more, one-shot layers are limited to 8 layers only.
In addition, there is a special key:
Key_MetaSticky
A key that behaves like a one-shot key, but while active, it makes other keys that are pressed become sticky, just like double-tapped one-shot keys.
Plugin methods
The plugin provides one object, OneShot
, which implements both one-shot
modifiers and one-shot layer keys. It has the following methods:
Configuration methods: Timeouts
.setTimeout(timeout)
OneShot keys will remain active after they're pressed for
timeout
milliseconds (or until a subsequent non-oneshot key is pressed). The default value is 2500 (2.5 seconds).
.setHoldTimeout(timeout)
If a one-shot key is held for longer than
timeout
milliseconds, it will behave like a normal key, and won't remain active after it is released. The default value is 250 (1/4 seconds).
.setDoubleTapTimeout(timeout)
If a one-shot key is double-tapped (pressed twice in a row) in less than
timeout
milliseconds, it wil become sticky, and will remain active until it is pressed a third time. The default value is -1, which indicates that it should use the same timeout as.setTimeout()
.
Configuration methods: Stickability
.enableStickability(key...)
.disableStickability(key...)
Enables/disables stickability for all keys listed. The keys should all be OneShot keys, modifier keys, or layer-shift keys, as specified on the keymap. For example:
OneShot.enableStickability(OSM(LeftShift), OSL(1), Key_RightGUI)
.OneShot.disableStickability(OSM(RighttAlt), OSL(2), ShiftToLayer(4))
.By default, all OneShot keys are stickable.
.enableStickabilityForModifiers()
.enableStickabilityForLayers()
.disableStickabilityForModifiers()
.disableStickabilityForLayers()
Enables/disables stickability for all modifiers and layers, respectively. These are convenience methods for cases where one wants to enable stickability for a group of one-shot keys.
Configuration methods: Automatic one-shot keys
.enableAutoModifiers()
.disableAutoModifiers()
.toggleAutoModifiers()
Enables/disables/toggles auto-oneshot functionality for modifier keys. When enabled, all normal modifier keys, including those with other modifier flags added to them (e.g.
LSHIFT(Key_LeftAlt)
,Key_Meh
) will be automatically treated as one-shot keys, in addition to dedicated ones likeOSM(LeftGui)
.
.enableAutoLayers()
.disableAutoLayers()
.toggleAutoLayers()
Enables/disables/toggles auto-oneshot functionality for layer shift keys (see above).
.enableAutoOneShot()
.disableAutoOneShot()
.toggleAutoOneShot()
Enables/disables/toggles auto-oneshot functionality for all modifiers and layer shift keys.
Test methods
.isActive(key_addr)
Returns
true
if the key atkey_addr
is in an active one-shot state. Note that if a key is still being held, but will be not remain active after it is released, it is not considered to be in a one-shot state, even if it had been earlier.
.isTemporary(key_addr)
Returns
true
if the key atkey_addr
is in a temporary one-shot state. Such a key will eventually time out or get deactivated by a subsequent key press.
.isSticky(key_addr)
Returns
true
if the key atkey_addr
is in a permanent one-shot state. Such a key will not be deactivated by subsequent keypresses, nor will it time out. It will only be deactivated by pressing it one more time, or by being cancelled by thecancel()
method (see below).
.isActive()
Returns
true
if there are any active one-shot keys. Note: it returnsfalse
if there are no currently active one-shot keys, but there are keys that were at one time in a one-shot state, but are still being held after that state has been cancelled.
.isSticky()
Returns
true
if there are any sticky one-shot keys.
.isStickable(key)
Returns
true
if a key of the specified value can be made sticky by double-tapping.
.isModifier(key)
Returns
true
if the specified key is a modifier key. This does not include OneShot modifiers (e.g.OSM(LeftShift)
), but it does include modifiers with additional modifier flags (e.g.Key_Meh
,LCTRL(Key_RightGui)
).
.isLayerShift(key)
Returns
true
if the specified key is a layer-shift key (e.g.ShiftToLayer(2)
). OneShot layer keys (e.g.OSL(5)
are not included).
.isOneShotKey(key)
Returns
true
if the specified key is a OneShot modifier or layer-shift key (e.g.OSM(LeftAlt)
,OSL(3)
).
Other methods
.cancel([with_stickies])
Immediately deactivates the one-shot status of any temporary one-shot keys. Any keys still being physically held will continue to function as normal modifier/layer-shift keys.
If
with_stickies
istrue
(the default isfalse
), sticky one-shot keys will also be deactivated, in the same way.
Deprecated methods
The following methods have been deprecated, and should no longer be
used, if possible. These functions made more sense when OneShot was
based on Key
values; it has since be rewritten to be based on
KeyAddr
values.
.inject(key, key_state)
Finds an idle key on the keyboard, and turns it into a one-shot key. When OneShot was based on
Key
values, this made more sense, as it didn't need a validKeyAddr
to work. Since the main purpose of this method was to enable the triggering of multiple one-shot modifiers with a single key, it is much better to use automatic one-shot modifiers, if possible, because then it's not necessary to use a Macro to configure.
.isModifierActive(key)
Returns
true
if a keymap cache entry with the current value ofkey
is active (one-shot, sticky, or held). This should be a function that is not specific to OneShot.
.isActive(key)
Returns
true
if a keymap cache entry with the current value ofkey
is in an active one-shot state. Please use.isActive(key_addr)
instead.
.isSticky(key)
Returns
true
if a keymap cache entry with the current value ofkey
is in a sticky one-shot state. Please use.isSticky(key_addr)
instead.
.isPressed()
Returns
false
. OneShot doesn't need to keep track of whether or not a one-shot key is still pressed any more. This function was mainly used by LED-ActiveModColor, which no longer needs it.
Plugin properties [DEPRECATED]
Along with the methods listed above, the OneShot
object has the
following properties, too. [Note: these have all been deprecated,
please use the .set*Timeout()
methods above instead.]
.time_out
Set this property to the number of milliseconds to wait before timing out and cancelling the one-shot effect (unless interrupted or cancelled before by any other means).
Defaults to 2500.
.hold_time_out
Set this property to the number of milliseconds to wait before considering a held one-shot key as intentionally held. In this case, the one-shot effect will not trigger when the key is released. In other words, holding a one-shot key at least this long, and then releasing it, will not trigger the one-shot effect.
Defaults to 200.
.double_tap_time_out
Set this property to the number of milliseconds within which a second uninterrupted tap of the same one-shot key will be treated as a sticky-tap. Only takes effect when
.double_tap_sticky
is set.Setting the property to
-1
will make the double-tap timeout use.time_out
for its calculations.Defaults to -1.
Dependencies
Further reading
Starting from the example is the recommended way of getting started with the plugin.