From 1f24088a69d952ec14262fbfc9c3e81d3229a200 Mon Sep 17 00:00:00 2001 From: Michael Richters Date: Wed, 11 Nov 2020 16:56:24 -0600 Subject: [PATCH] Add documentation and examples for Qukeys tap-repeat feature Signed-off-by: Michael Richters --- docs/NEWS.md | 18 ++++++++++++++++++ examples/Keystrokes/Qukeys/Qukeys.ino | 1 + plugins/Kaleidoscope-Qukeys/README.md | 26 ++++++++++++++++++++++++++ 3 files changed, 45 insertions(+) diff --git a/docs/NEWS.md b/docs/NEWS.md index ff2bef6d..b00e3872 100644 --- a/docs/NEWS.md +++ b/docs/NEWS.md @@ -12,6 +12,24 @@ See [UPGRADING.md](UPGRADING.md) for more detailed instructions about upgrading ## New features +### New Qukeys features + +#### Tap-repeat + +It is now possible to get the "tap" value of a qukey to repeat (as if that key +for that character was simply being held down on a normal keyboard) by tapping +the qukey, then quickly pressing and holding it down. The result on the OS will +be as if the key was pressed and held just once, so that users of macOS apps +that use the Cocoa input system can get the menu for characters with diacritics +without an extra character in the output. + +The maximum interval between the two keypresses that will trigger a tap repeat +can be configured via the `Qukeys.setMaxIntervalForTapRepeat(ms)` function, +where the argument specifies the number of milliseconds Qukeys will wait after a +qukey is tapped for it to be pressed a second time. If it is, but the qukey is +released within that same interval from the first tap's release, it will be +treated as a double-tap, and both taps will be sent to the OS. + ### New OneShot features #### Auto-OneShot modifiers & layers diff --git a/examples/Keystrokes/Qukeys/Qukeys.ino b/examples/Keystrokes/Qukeys/Qukeys.ino index 5cc8c8cc..c2cad0d3 100644 --- a/examples/Keystrokes/Qukeys/Qukeys.ino +++ b/examples/Keystrokes/Qukeys/Qukeys.ino @@ -74,6 +74,7 @@ void setup() { Qukeys.setOverlapThreshold(50); Qukeys.setMinimumHoldTime(100); Qukeys.setMinimumPriorInterval(80); + Qukeys.setMaxIntervalForTapRepeat(150); Kaleidoscope.setup(); } diff --git a/plugins/Kaleidoscope-Qukeys/README.md b/plugins/Kaleidoscope-Qukeys/README.md index 36d7c028..6a1beac6 100644 --- a/plugins/Kaleidoscope-Qukeys/README.md +++ b/plugins/Kaleidoscope-Qukeys/README.md @@ -75,6 +75,22 @@ likely to generate errors and out-of-order events. > > Defaults to `250`. +### `.setMaxIntervalForTapRepeat(timeout)` + +> Sets the time (in milliseconds) that limits the tap-repeat window. If the same +> qukey is pressed, released, and pressed again within this timeframe, then +> held, Qukeys will turn it into a single press and hold event, using the +> primary key value (which cannot otherwise be held). If the second press is +> also a tap, and the two _release_ events occur within the same timeframe, it +> will instead be treated as a double tap (of the primary key value). +> +> To effectively shut off the tap-repeat feature, set this value to `0`. The +> maximum value is `255`; anything higher than `250` could result in key repeat +> being triggered on the host before Qukeys determines whether it's a tap-repeat +> or a double-tap sequence, because most systems delay the key repeat by 500 ms. +> +> Defaults to `200`. + ### `.setOverlapThreshold(percentage)` > This sets a variable that allows the user to roll over from a qukey to a @@ -205,6 +221,16 @@ the given alternate value on all layers, regardless of what the primary value is for that key on the top currently active layer. +### Tap-Repeat Behaviour + +If a qukey is tapped, then immediately pressed and held, Qukeys will turn that +sequence of events into a single press and hold of the primary key value +(whereas merely holding the key yeilds the alternate value). This is +particularly useful on macOS apps that use Apple's Cocoa input system, where +holding a key gives the user access to a menu of accented characters, rather +than merely repeating the same character until the key is released. + + ## Design & Implementation When a qukey is pressed, it doesn't immediately add a corresponding keycode to