Add documentation and examples for Qukeys tap-repeat feature

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>

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

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();
 }

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