alpha
/
Kaleidoscope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'plugin/Qukeys/f/monorepo' into f/monorepo-stage2

Browse Source
pull/389/head
Gergely Nagy 6 years ago
parent c6e05848d8 3d21853dad
commit b0e3db9328
No known key found for this signature in database
GPG Key ID: AC1E90BAC433F68F
6 changed files with 848 additions and 0 deletions
Show Stats Download Patch File Download Diff File

158
doc/plugin/Qukeys.md
Unescape View File

@ -0,0 +1,158 @@
# Kaleidoscope-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.
## 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, row, col, alt_keycode)`
(layers, rows and columns are all zero-indexed, rows are top to bottom and
columns are left to right):
- For the Keyboardio Model 01, key coordinates refer to [this header
file](Hardware-Model01/blob/f469015346535cb864a340bf8eb317d268943248/src/Kaleidoscope-Hardware-Model01.h#L267-L279)..md
```
QUKEYS(
// l, r, c, alt_keycode
kaleidoscope::plugin::Qukey(0, 2, 1, Key_LeftGui), // A/cmd
kaleidoscope::plugin::Qukey(0, 2, 2, Key_LeftAlt), // S/alt
kaleidoscope::plugin::Qukey(0, 2, 3, Key_LeftControl), // D/ctrl
kaleidoscope::plugin::Qukey(0, 2, 4, Key_LeftShift), // F/shift
kaleidoscope::plugin::Qukey(0, 1, 14, Key_LeftShift), // P/shift
kaleidoscope::plugin::Qukey(0, 3, 15, Key_LeftShift) // Minus/shift
)
```
`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
### `.setTimeout(time_limit)`
> Sets the time length in milliseconds which determines if a key has been tapped or held.
>
> Defaults to 250.
### `.setReleaseDelay(release_delay)`
> Sets the time length in milliseconds to artificially delay the release of the Qukey.
>
> This is to accommodate users who are in the habit of releasing modifiers and the keys
> they modify (almost) simultaneously, since the Qukey may be detected as released
> *slightly* before the other key, which would not trigger the desired alternate keycode.
>
> It is best to keep this a very small value such as 20 to avoid over-extending the
> modifier to further keystrokes.
>
> Defaults to 0.
### `.activate()`
### `.deactivate()`
### `.toggle()`
> activate/deactivate `Qukeys`
### 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.
## 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. a time limit is reached
2. the `Qukey` is released
3. a subsequently-pressed key is released
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/Qukeys/Qukeys.ino
## Upgrading
Previous versions of `Qukeys` used `kaleidoscope::Qukey` objects within the
`QUKEYS` macro. In newer versions, this is `kaleidoscope::plugin::Qukey`
instead. The old name still works, but will be removed by 2019-01-14.

81
examples/Qukeys/Qukeys.ino
Unescape View File

@ -0,0 +1,81 @@
// -*- mode: c++ -*-
#include <Kaleidoscope.h>
#include <Kaleidoscope-Qukeys.h>
#include <Kaleidoscope-Macros.h>
enum { MACRO_TOGGLE_QUKEYS };
// *INDENT-OFF*
KEYMAPS(
[0] = KEYMAP_STACKED
(
Key_NoKey, Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey,
Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab,
Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G,
Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape,
Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift,
Key_Q,
M(MACRO_TOGGLE_QUKEYS), Key_6, Key_7, Key_8, Key_9, Key_0, Key_skip,
Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals,
Key_H, SFT_T(J), CTL_T(K), ALT_T(L), GUI_T(Semicolon), Key_Quote,
Key_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus,
Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl,
LT(1,E)
),
[1] = KEYMAP_STACKED
(
___, Key_B, Key_C, Key_D, Key_E, Key_F, Key_G,
Key_A, Key_B, Key_C, Key_D, Key_E, Key_F, Key_G,
Key_A, Key_B, Key_C, Key_D, Key_E, Key_F,
Key_A, Key_B, Key_C, Key_D, Key_E, Key_F, Key_G,
Key_1, Key_2, Key_3, Key_4,
___,
___, Key_B, Key_C, Key_D, Key_E, Key_F, Key_G,
Key_A, Key_B, Key_C, Key_D, Key_E, Key_F, Key_G,
Key_A, Key_B, Key_C, Key_D, Key_E, Key_F,
Key_A, Key_B, Key_C, Key_D, Key_E, Key_F, Key_G,
Key_1, Key_2, Key_3, Key_4,
___
),
)
// *INDENT-ON*
// Defining a macro (on the "any" key: see above) to toggle Qukeys on and off
const macro_t *macroAction(uint8_t macro_index, uint8_t key_state) {
switch (macro_index) {
case MACRO_TOGGLE_QUKEYS:
if (keyToggledOn(key_state))
Qukeys.toggle();
break;
}
return MACRO_NONE;
}
// Use Qukeys
KALEIDOSCOPE_INIT_PLUGINS(Qukeys, Macros);
void setup() {
QUKEYS(
kaleidoscope::plugin::Qukey(0, 2, 1, Key_LeftGui), // A/cmd
kaleidoscope::plugin::Qukey(0, 2, 2, Key_LeftAlt), // S/alt
kaleidoscope::plugin::Qukey(0, 2, 3, Key_LeftControl), // D/ctrl
kaleidoscope::plugin::Qukey(0, 2, 4, Key_LeftShift), // F/shift
kaleidoscope::plugin::Qukey(0, 3, 6, ShiftToLayer(1)) // Q/layer-shift (on `fn`)
)
Qukeys.setTimeout(200);
Qukeys.setReleaseDelay(20);
Kaleidoscope.setup();
}
void loop() {
Kaleidoscope.loop();
}

21
src/Kaleidoscope-Qukeys.h
Unescape View File

@ -0,0 +1,21 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Qukeys -- Assign two keycodes to a single key
* Copyright (C) 2017 Michael Richters
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <kaleidoscope/plugin/Qukeys.h>

44
src/kaleidoscope/addr.h
Unescape View File

@ -0,0 +1,44 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Qukeys -- Assign two keycodes to a single key
* Copyright (C) 2017 Michael Richters
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <Kaleidoscope.h>
// Helper functions for converting between separate (row,col)
// coordinates and a single-byte key number (addr). This works as long
// as the keyboard has fewer than 256 keys.
namespace kaleidoscope {
namespace addr {
inline uint8_t row(uint8_t key_addr) {
return (key_addr / COLS);
}
inline uint8_t col(uint8_t key_addr) {
return (key_addr % COLS);
}
inline uint8_t addr(uint8_t row, uint8_t col) {
return ((row * COLS) + col);
}
inline void mask(uint8_t key_addr) {
KeyboardHardware.maskKey(row(key_addr), col(key_addr));
}
inline void unmask(uint8_t key_addr) {
KeyboardHardware.unMaskKey(row(key_addr), col(key_addr));
}
} // namespace addr {
} // namespace kaleidoscope {

396
src/kaleidoscope/plugin/Qukeys.cpp
Unescape View File

@ -0,0 +1,396 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Qukeys -- Assign two keycodes to a single key
* Copyright (C) 2017 Michael Richters
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include <Kaleidoscope.h>
#include <Kaleidoscope-Qukeys.h>
#include <kaleidoscope/hid.h>
#include <MultiReport/Keyboard.h>
#include <Kaleidoscope-Ranges.h>
#ifdef ARDUINO_VIRTUAL
#define debug_print(...) printf(__VA_ARGS__)
#else
#define debug_print(...)
#endif
namespace kaleidoscope {
namespace plugin {
inline
bool isDualUse(Key k) {
if (k.raw < ranges::DU_FIRST || k.raw > ranges::DU_LAST)
return false;
return true;
}
inline
bool isDualUse(byte key_addr) {
byte row = addr::row(key_addr);
byte col = addr::col(key_addr);
Key k = Layer.lookup(row, col);
return isDualUse(k);
}
Key getDualUsePrimaryKey(Key k) {
if (k.raw >= ranges::DUM_FIRST && k.raw <= ranges::DUM_LAST) {
k.raw -= ranges::DUM_FIRST;
k.flags = 0;
} else if (k.raw >= ranges::DUL_FIRST && k.raw <= ranges::DUL_LAST) {
k.raw -= ranges::DUL_FIRST;
k.flags = 0;
}
return k;
}
Key getDualUseAlternateKey(Key k) {
if (k.raw >= ranges::DUM_FIRST && k.raw <= ranges::DUM_LAST) {
k.raw -= ranges::DUM_FIRST;
k.raw = (k.raw >> 8) + Key_LeftControl.keyCode;
} else if (k.raw >= ranges::DUL_FIRST && k.raw <= ranges::DUL_LAST) {
k.raw -= ranges::DUL_FIRST;
byte layer = k.flags;
// Should be `ShiftToLayer(layer)`, but that gives "narrowing conversion"
// warnings that I can't figure out how to resolve
k.keyCode = layer + LAYER_SHIFT_OFFSET;
k.flags = KEY_FLAGS | SYNTHETIC | SWITCH_TO_KEYMAP;
}
return k;
}
Qukey::Qukey(int8_t layer, byte row, byte col, Key alt_keycode) {
this->layer = layer;
this->addr = addr::addr(row, col);
this->alt_keycode = alt_keycode;
}
Qukey * Qukeys::qukeys;
uint8_t Qukeys::qukeys_count = 0;
bool Qukeys::active_ = true;
uint16_t Qukeys::time_limit_ = 250;
uint8_t Qukeys::release_delay_ = 0;
QueueItem Qukeys::key_queue_[] = {};
uint8_t Qukeys::key_queue_length_ = 0;
byte Qukeys::qukey_state_[] = {};
bool Qukeys::flushing_queue_ = false;
constexpr uint16_t QUKEYS_RELEASE_DELAY_OFFSET = 4096;
// Empty constructor; nothing is stored at the instance level
Qukeys::Qukeys(void) {}
int8_t Qukeys::lookupQukey(uint8_t key_addr) {
if (key_addr == QUKEY_UNKNOWN_ADDR) {
return QUKEY_NOT_FOUND;
}
for (int8_t i = 0; i < qukeys_count; i++) {
if (qukeys[i].addr == key_addr) {
byte row = addr::row(key_addr);
byte col = addr::col(key_addr);
if ((qukeys[i].layer == QUKEY_ALL_LAYERS) ||
(qukeys[i].layer == Layer.lookupActiveLayer(row, col))) {
return i;
}
}
}
return QUKEY_NOT_FOUND;
}
void Qukeys::enqueue(uint8_t key_addr) {
if (key_queue_length_ == QUKEYS_QUEUE_MAX) {
setQukeyState(key_queue_[0].addr, QUKEY_STATE_PRIMARY);
flushKey(QUKEY_STATE_PRIMARY, IS_PRESSED | WAS_PRESSED);
flushQueue();
}
// default to alternate state to stop keys being flushed from the queue before the grace
// period timeout
setQukeyState(key_addr, QUKEY_STATE_ALTERNATE);
key_queue_[key_queue_length_].addr = key_addr;
key_queue_[key_queue_length_].start_time = millis();
key_queue_length_++;
addr::mask(key_addr);
}
int8_t Qukeys::searchQueue(uint8_t key_addr) {
for (int8_t i = 0; i < key_queue_length_; i++) {
if (key_queue_[i].addr == key_addr)
return i;
}
return QUKEY_NOT_FOUND;
}
// flush a single entry from the head of the queue
bool Qukeys::flushKey(bool qukey_state, uint8_t keyswitch_state) {
addr::unmask(key_queue_[0].addr);
int8_t qukey_index = lookupQukey(key_queue_[0].addr);
bool is_qukey = (qukey_index != QUKEY_NOT_FOUND);
byte row = addr::row(key_queue_[0].addr);
byte col = addr::col(key_queue_[0].addr);
bool is_dual_use = isDualUse(Layer.lookup(row, col));
Key keycode = Key_NoKey;
if (is_qukey || is_dual_use) {
if (qukey_state == QUKEY_STATE_PRIMARY &&
getQukeyState(key_queue_[0].addr) == QUKEY_STATE_ALTERNATE) {
// If there's a release delay in effect, and there's at least one key after it in
// the queue, delay this key's release event:
if (release_delay_ > 0 && key_queue_length_ > 1) {
key_queue_[0].start_time = millis() + QUKEYS_RELEASE_DELAY_OFFSET;
return false;
}
}
setQukeyState(key_queue_[0].addr, qukey_state);
if (qukey_state == QUKEY_STATE_ALTERNATE) {
if (is_dual_use) {
keycode = getDualUseAlternateKey(keycode);
} else { // is_qukey
keycode = qukeys[qukey_index].alt_keycode;
}
}
}
// Before calling handleKeyswitchEvent() below, make sure Qukeys knows not to handle
// these events:
flushing_queue_ = true;
// Since we're in the middle of the key scan, we don't necessarily
// have a full HID report, and we don't want to accidentally turn
// off keys that the scan hasn't reached yet, so we force the
// current report to be the same as the previous one, then proceed
HID_KeyboardReport_Data_t hid_report;
// First, save the current report
memcpy(hid_report.allkeys, Keyboard.keyReport.allkeys, sizeof(hid_report));
// Next, copy the old report
memcpy(Keyboard.keyReport.allkeys, Keyboard.lastKeyReport.allkeys, sizeof(Keyboard.keyReport));
// Instead of just calling pressKey here, we start processing the
// key again, as if it was just pressed, and mark it as injected, so
// we can ignore it and don't start an infinite loop. It would be
// nice if we could use key_state to also indicate which plugin
// injected the key.
handleKeyswitchEvent(keycode, row, col, IS_PRESSED);
// Now we send the report (if there were any changes)
hid::sendKeyboardReport();
// Next, we restore the current state of the report
memcpy(Keyboard.keyReport.allkeys, hid_report.allkeys, sizeof(hid_report));
// Last, if the key is still down, add its code back in
if (keyswitch_state & IS_PRESSED)
handleKeyswitchEvent(keycode, row, col, IS_PRESSED | WAS_PRESSED);
// Now that we're done sending the report(s), Qukeys can process events again:
flushing_queue_ = false;
// Shift the queue, so key_queue[0] is always the first key that gets processed
for (byte i = 0; i < key_queue_length_; i++) {
key_queue_[i] = key_queue_[i + 1];
}
key_queue_length_--;
return true;
}
// flushQueue() is called when a key that's in the key_queue is
// released. This means that all the keys ahead of it in the queue are
// still being held, so first we flush them, then we flush the
// released key (with different parameters).
void Qukeys::flushQueue(int8_t index) {
if (index == QUKEY_NOT_FOUND)
return;
for (int8_t i = 0; i < index; i++) {
if (key_queue_length_ == 0)
return;
flushKey(QUKEY_STATE_ALTERNATE, IS_PRESSED | WAS_PRESSED);
}
if (isQukey(key_queue_[0].addr)) {
flushKey(QUKEY_STATE_PRIMARY, IS_PRESSED | WAS_PRESSED);
} else {
flushKey(QUKEY_STATE_PRIMARY, WAS_PRESSED);
}
}
// Flush all the non-qukey keys from the front of the queue
void Qukeys::flushQueue() {
// flush keys until we find a qukey:
while (key_queue_length_ > 0 && !isQukey(key_queue_[0].addr)) {
if (flushKey(QUKEY_STATE_PRIMARY, IS_PRESSED | WAS_PRESSED) == false)
break;
}
}
inline
bool Qukeys::isQukey(uint8_t addr) {
return (isDualUse(addr) || lookupQukey(addr) != QUKEY_NOT_FOUND);
}
EventHandlerResult Qukeys::onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state) {
// If key_addr is not a physical key, ignore it; some other plugin injected it
if (row >= ROWS || col >= COLS || (key_state & INJECTED) != 0)
return EventHandlerResult::OK;
// If Qukeys is turned off, continue to next plugin
if (!active_) {
mapped_key = getDualUsePrimaryKey(mapped_key);
return EventHandlerResult::OK;
}
// get key addr & qukey (if any)
uint8_t key_addr = addr::addr(row, col);
int8_t qukey_index = lookupQukey(key_addr);
// If the key was injected (from the queue being flushed)
if (flushing_queue_) {
// If it's a DualUse key, we still need to update its keycode
if (isDualUse(mapped_key)) {
if (getQukeyState(key_addr) == QUKEY_STATE_ALTERNATE) {
mapped_key = getDualUseAlternateKey(mapped_key);
} else {
mapped_key = getDualUsePrimaryKey(mapped_key);
}
}
// ...otherwise, just continue to the next plugin
return EventHandlerResult::OK;
}
// If the key isn't active, and didn't just toggle off, continue to next plugin
if (!keyIsPressed(key_state) && !keyWasPressed(key_state)) {
mapped_key = getDualUsePrimaryKey(mapped_key);
return EventHandlerResult::OK;
}
// If the key was just pressed:
if (keyToggledOn(key_state)) {
// If the queue is empty and the key isn't a qukey, proceed:
if (key_queue_length_ == 0 &&
! isDualUse(mapped_key) &&
qukey_index == QUKEY_NOT_FOUND) {
return EventHandlerResult::OK;
}
// Otherwise, queue the key and stop processing:
enqueue(key_addr);
// flushQueue() has already handled this key release
return EventHandlerResult::EVENT_CONSUMED;
}
// In all other cases, we need to know if the key is queued already
int8_t queue_index = searchQueue(key_addr);
// If the key was just released:
if (keyToggledOff(key_state)) {
// If the key isn't in the key_queue, proceed
if (queue_index == QUKEY_NOT_FOUND) {
// If a qukey was released while in its alternate state, change its keycode
if (isDualUse(mapped_key)) {
if (getQukeyState(key_addr) == QUKEY_STATE_ALTERNATE) {
mapped_key = getDualUseAlternateKey(mapped_key);
} else {
mapped_key = getDualUsePrimaryKey(mapped_key);
}
} else if (qukey_index != QUKEY_NOT_FOUND) {
if (getQukeyState(key_addr) == QUKEY_STATE_ALTERNATE) {
mapped_key = qukeys[qukey_index].alt_keycode;
}
}
return EventHandlerResult::OK;
}
flushQueue(queue_index);
flushQueue();
mapped_key = getDualUsePrimaryKey(mapped_key);
return EventHandlerResult::OK;
}
// Otherwise, the key is still pressed
// If the key is not a qukey:
if (qukey_index == QUKEY_NOT_FOUND &&
! isDualUse(mapped_key)) {
// If the key was pressed before the keys in the queue, proceed:
if (queue_index == QUKEY_NOT_FOUND) {
return EventHandlerResult::OK;
} else {
// suppress this keypress; it's still in the queue
return EventHandlerResult::EVENT_CONSUMED;
}
}
// If the qukey is not in the queue, check its state
if (queue_index == QUKEY_NOT_FOUND) {
if (getQukeyState(key_addr) == QUKEY_STATE_ALTERNATE) {
if (isDualUse(mapped_key)) {
mapped_key = getDualUseAlternateKey(mapped_key);
} else {
mapped_key = qukeys[qukey_index].alt_keycode;
}
} else { // qukey_state == QUKEY_STATE_PRIMARY
mapped_key = getDualUsePrimaryKey(mapped_key);
}
return EventHandlerResult::OK;
}
// else state is undetermined; block. I could check timeouts here,
// but I'd rather do that in the pre-report hook
return EventHandlerResult::EVENT_CONSUMED;
}
EventHandlerResult Qukeys::beforeReportingState() {
uint16_t current_time = millis();
if (release_delay_ > 0 && key_queue_length_ > 0) {
int16_t diff_time = key_queue_[0].start_time - current_time;
if (diff_time > 0) {
int16_t delay_window = QUKEYS_RELEASE_DELAY_OFFSET - release_delay_;
if (diff_time < delay_window) {
setQukeyState(key_queue_[0].addr, QUKEY_STATE_PRIMARY);
flushKey(QUKEY_STATE_PRIMARY, WAS_PRESSED);
flushQueue();
}
return EventHandlerResult::OK;
}
}
// If the qukey has been held longer than the time limit, set its
// state to the alternate keycode and add it to the report
while (key_queue_length_ > 0) {
if ((current_time - key_queue_[0].start_time) > time_limit_) {
flushKey(QUKEY_STATE_ALTERNATE, IS_PRESSED | WAS_PRESSED);
flushQueue();
} else {
break;
}
}
return EventHandlerResult::OK;
}
EventHandlerResult Qukeys::onSetup() {
// initializing the key_queue seems unnecessary, actually
for (int8_t i = 0; i < QUKEYS_QUEUE_MAX; i++) {
key_queue_[i].addr = QUKEY_UNKNOWN_ADDR;
key_queue_[i].start_time = 0;
}
key_queue_length_ = 0;
return EventHandlerResult::OK;
}
} // namespace plugin {
} // namespace kaleidoscope {
kaleidoscope::plugin::Qukeys Qukeys;

148
src/kaleidoscope/plugin/Qukeys.h
Unescape View File

@ -0,0 +1,148 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Qukeys -- Assign two keycodes to a single key
* Copyright (C) 2017 Michael Richters
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <Kaleidoscope.h>
#include <kaleidoscope/addr.h>
#include <Kaleidoscope-Ranges.h>
// Maximum length of the pending queue
#define QUKEYS_QUEUE_MAX 8
// Total number of keys on the keyboard (assuming full grid)
#define TOTAL_KEYS ROWS * COLS
// Boolean values for storing qukey state
#define QUKEY_STATE_PRIMARY false
#define QUKEY_STATE_ALTERNATE true
// Initialization addr value for empty key_queue. This seems to be
// unnecessary, because we rely on keeping track of the lenght of the
// queue, anyway.
#define QUKEY_UNKNOWN_ADDR 0xFF
// Value to return when no match is found in Qukeys.dict. A successful
// match returns an index in the array, so this must be negative. Also
// used for failed search of the key_queue.
#define QUKEY_NOT_FOUND -1
// Wildcard value; this matches any layer
#define QUKEY_ALL_LAYERS -1
#define MT(mod, key) (Key) { \
.raw = kaleidoscope::ranges::DUM_FIRST + \
(((Key_ ## mod).keyCode - Key_LeftControl.keyCode) << 8) + (Key_ ## key).keyCode }
#define SFT_T(key) MT(LeftShift, key)
#define CTL_T(key) MT(LeftControl, key)
#define ALT_T(key) MT(LeftAlt, key)
#define GUI_T(key) MT(LeftGui, key)
#define LT(layer, key) (Key) { .raw = kaleidoscope::ranges::DUL_FIRST + (layer << 8) + (Key_ ## key).keyCode }
namespace kaleidoscope {
namespace plugin {
// Data structure for an individual qukey
struct Qukey {
public:
Qukey(void) {}
Qukey(int8_t layer, byte row, byte col, Key alt_keycode);
int8_t layer;
uint8_t addr;
Key alt_keycode;
};
// Data structure for an entry in the key_queue
struct QueueItem {
uint8_t addr; // keyswitch coordinates
uint16_t start_time; // time a queued key was pressed
};
// The plugin itself
class Qukeys : public kaleidoscope::Plugin {
// I could use a bitfield to get the state values, but then we'd
// have to check the key_queue (there are three states). Or use a
// second bitfield for the indeterminite state. Using a bitfield
// would enable storing the qukey list in PROGMEM, but I don't know
// if the added complexity is worth it.
public:
Qukeys(void);
static void activate(void) {
active_ = true;
}
static void deactivate(void) {
active_ = false;
}
static void toggle(void) {
active_ = !active_;
}
static void setTimeout(uint16_t time_limit) {
time_limit_ = time_limit;
}
static void setReleaseDelay(uint8_t release_delay) {
release_delay_ = release_delay;
}
static Qukey * qukeys;
static uint8_t qukeys_count;
EventHandlerResult onSetup();
EventHandlerResult onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state);
EventHandlerResult beforeReportingState();
private:
static bool active_;
static uint16_t time_limit_;
static uint8_t release_delay_;
static QueueItem key_queue_[QUKEYS_QUEUE_MAX];
static uint8_t key_queue_length_;
static bool flushing_queue_;
// Qukey state bitfield
static uint8_t qukey_state_[(TOTAL_KEYS) / 8 + ((TOTAL_KEYS) % 8 ? 1 : 0)];
static bool getQukeyState(uint8_t addr) {
return bitRead(qukey_state_[addr / 8], addr % 8);
}
static void setQukeyState(uint8_t addr, boolean qukey_state) {
bitWrite(qukey_state_[addr / 8], addr % 8, qukey_state);
}
static int8_t lookupQukey(uint8_t key_addr);
static void enqueue(uint8_t key_addr);
static int8_t searchQueue(uint8_t key_addr);
static bool flushKey(bool qukey_state, uint8_t keyswitch_state);
static void flushQueue(int8_t index);
static void flushQueue(void);
static bool isQukey(uint8_t addr);
};
} // namespace plugin {
// Backwards compatibility
typedef plugin::Qukey Qukey;
} // namespace kaleidoscope {
extern kaleidoscope::plugin::Qukeys Qukeys;
// macro for use in sketch file to simplify definition of qukeys
#define QUKEYS(qukey_defs...) { \
static kaleidoscope::plugin::Qukey qk_table[] = { qukey_defs }; \
Qukeys.qukeys = qk_table; \
Qukeys.qukeys_count = sizeof(qk_table) / sizeof(kaleidoscope::plugin::Qukey); \
}
Write Preview
Loading…
Cancel
Save