From cc1bfc657ffe346212ed445f9e0ff328ed65fabe Mon Sep 17 00:00:00 2001 From: Josh Klar Date: Sat, 20 Oct 2018 17:53:01 -0700 Subject: [PATCH 1/5] Silly bugfix in ShiftedKeycodes --- kmk/keycodes.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kmk/keycodes.py b/kmk/keycodes.py index b0dea09..847e7d1 100644 --- a/kmk/keycodes.py +++ b/kmk/keycodes.py @@ -364,7 +364,7 @@ class ShiftedKeycodes(KeycodeCategory): KC_DOUBLE_QUOTE = KC_DQUO = KC_DQT = Modifiers.KC_LSHIFT(Common.KC_QUOTE) KC_LEFT_ANGLE_BRACKET = KC_LABK = Modifiers.KC_LSHIFT(Common.KC_COMMA) KC_RIGHT_ANGLE_BRACKET = KC_RABK = Modifiers.KC_LSHIFT(Common.KC_DOT) - KC_QUESTION = KC_QUES = Modifiers.KC_LSHIFT(Common.KC_DOT) + KC_QUESTION = KC_QUES = Modifiers.KC_LSHIFT(Common.KC_SLSH) class FunctionKeys(KeycodeCategory): From b0f8c58828d5f7cb50b4b8b3e19ba955aa27147d Mon Sep 17 00:00:00 2001 From: Josh Klar Date: Fri, 19 Oct 2018 03:04:54 -0700 Subject: [PATCH 2/5] Beginnings of basic tap dance --- kmk/internal_state.py | 82 +++++++++++++++++---- kmk/keycodes.py | 15 ++++ user_keymaps/klardotsh/klarank_featherm4.py | 2 +- 3 files changed, 83 insertions(+), 16 deletions(-) diff --git a/kmk/internal_state.py b/kmk/internal_state.py index 555fe39..cdb82e3 100644 --- a/kmk/internal_state.py +++ b/kmk/internal_state.py @@ -28,6 +28,8 @@ class InternalState: 'leader': None, } timeouts = {} + tapping = False + tap_dance_counts = {} def __init__(self, config): self.config = config @@ -45,6 +47,7 @@ class InternalState: Keycodes.KMK.KC_LEAD.code: self._kc_lead, Keycodes.KMK.KC_NO.code: self._kc_no, Keycodes.KMK.KC_DEBUG.code: self._kc_debug_mode, + RawKeycodes.KC_TAP_DANCE: self._kc_tap_dance, } def __repr__(self): @@ -57,6 +60,8 @@ class InternalState: 'leader_mode_history': self.leader_mode_history, 'leader_mode': self.config.leader_mode, 'start_time': self.start_time, + 'tapping': self.tapping, + 'tap_dance_counts': self.tap_dance_counts, } return ret @@ -103,24 +108,27 @@ class InternalState: print('No key accessible for col, row: {}, {}'.format(row, col)) return self - if is_pressed: - self.keys_pressed.add(kc_changed) - self.coord_keys_pressed[int_coord] = kc_changed + if self.tapping: + self._process_tap_dance(kc_changed, is_pressed) else: - self.keys_pressed.discard(kc_changed) - self.keys_pressed.discard(self.coord_keys_pressed[int_coord]) - self.coord_keys_pressed[int_coord] = None + if is_pressed: + self.keys_pressed.add(kc_changed) + self.coord_keys_pressed[int_coord] = kc_changed + else: + self.keys_pressed.discard(kc_changed) + self.keys_pressed.discard(self.coord_keys_pressed.get(int_coord, None)) + self.coord_keys_pressed[int_coord] = None - if kc_changed.code >= FIRST_KMK_INTERNAL_KEYCODE: - self._process_internal_key_event( - kc_changed, - is_pressed, - ) - else: - self.hid_pending = True + if kc_changed.code >= FIRST_KMK_INTERNAL_KEYCODE: + self._process_internal_key_event( + kc_changed, + is_pressed, + ) + else: + self.hid_pending = True - if self.config.leader_mode % 2 == 1: - self._process_leader_mode() + if self.config.leader_mode % 2 == 1: + self._process_leader_mode() return self @@ -318,6 +326,50 @@ class InternalState: return self + def _kc_tap_dance(self, changed_key, is_pressed): + if is_pressed: + self._begin_tap_dance(changed_key) + else: + self._end_tap_dance() + + return self + + def _begin_tap_dance(self, changed_key): + self.tap_dance_counts[changed_key] = 1 + self.set_timeout(500, self._end_tap_dance) + self.tapping = changed_key + return self + + def _process_tap_dance(self, changed_key, is_pressed): + if is_pressed: + if ( + changed_key not in self.tap_dance_counts or + not self.tap_dance_counts[changed_key] + ): + self._end_tap_dance() + else: + self.tap_dance_counts[changed_key] += 1 + + if self.tap_dance_counts[changed_key] == len(changed_key.codes): + self._end_tap_dance() + + return self + + def _end_tap_dance(self): + k = self.tapping + + if not k: + # already handled elsewhere? + return self + + v = self.tap_dance_counts[k] - 1 + + self.pending_keys.append(k.codes[min(v, len(k.codes) - 1)]) + self.tap_dance_counts[k] = 0 + self.tapping = False + + return self + def _begin_leader_mode(self): if self.config.leader_mode % 2 == 0: self.keys_pressed.discard(Keycodes.KMK.KC_LEAD) diff --git a/kmk/keycodes.py b/kmk/keycodes.py index 847e7d1..55d4443 100644 --- a/kmk/keycodes.py +++ b/kmk/keycodes.py @@ -80,6 +80,7 @@ class RawKeycodes: KC_MACRO = 1110 KC_MACRO_SLEEP_MS = 1111 + KC_TAP_DANCE = 1113 # These shouldn't have all the fancy shenanigans Keycode allows @@ -184,6 +185,13 @@ class Macro: return self.keyup() if self.keyup else None +class TapDanceKeycode: + code = RawKeycodes.KC_TAP_DANCE + + def __init__(self, *codes): + self.codes = codes + + class KeycodeCategory(type): @classmethod def to_dict(cls): @@ -551,6 +559,13 @@ class KMK(KeycodeCategory): def KC_MACRO_SLEEP_MS(ms): return MacroSleepKeycode(RawKeycodes.KC_MACRO_SLEEP_MS, ms) + @staticmethod + def KC_TAP_DANCE(*args): + return TapDanceKeycode(*args) + + +KMK.KC_TD = KMK.KC_TAP_DANCE + class Layers(KeycodeCategory): @staticmethod diff --git a/user_keymaps/klardotsh/klarank_featherm4.py b/user_keymaps/klardotsh/klarank_featherm4.py index 2cb1843..cfd0913 100644 --- a/user_keymaps/klardotsh/klarank_featherm4.py +++ b/user_keymaps/klardotsh/klarank_featherm4.py @@ -61,7 +61,7 @@ keyboard.keymap = [ [KC.GESC, KC.QUOT, KC.COMM, KC.DOT, KC.P, KC.Y, KC.F, KC.G, KC.C, KC.R, KC.L, KC.BSPC], [KC.TAB, KC.A, KC.O, KC.E, KC.U, KC.I, KC.D, KC.H, KC.T, KC.N, KC.S, KC.ENT], [KC.LGUI, KC.SCLN, KC.Q, KC.J, KC.K, KC.X, KC.B, KC.M, KC.W, KC.V, KC.Z, KC.LALT], - [KC.LCTL, KC.LEAD, KC.LSHIFT(KC.LGUI), KC.MO(2), KC.MO(3), KC.LSFT, KC.SPC, KC.MO(1), KC.LEFT, KC.DOWN, KC.UP, KC.RGHT], + [KC.LCTL, KC.TD(KC.A, KC.B), KC.LSHIFT(KC.LGUI), KC.MO(2), KC.MO(3), KC.LSFT, KC.SPC, KC.MO(1), KC.LEFT, KC.DOWN, KC.UP, KC.RGHT], ], [ From 0c13806f1ce5b7469a69bde5eea1984b37e7c7ed Mon Sep 17 00:00:00 2001 From: Josh Klar Date: Sat, 20 Oct 2018 16:55:17 -0700 Subject: [PATCH 3/5] Add key repeat support for basic alphanumeric tap dance --- kmk/firmware.py | 29 ++++++++++++++------ kmk/internal_state.py | 64 +++++++++++++++++++++++++------------------ 2 files changed, 57 insertions(+), 36 deletions(-) diff --git a/kmk/firmware.py b/kmk/firmware.py index 389321d..bf4c134 100644 --- a/kmk/firmware.py +++ b/kmk/firmware.py @@ -95,30 +95,41 @@ class Firmware: print("Firin' lazers. Keyboard is booted.") while True: - update = self.matrix.scan_for_changes() - if update is not None: + matrix_report = self.matrix.scan_for_changes() + state_changed = False + + if matrix_report is not None: self._state.matrix_changed( - update[0], - update[1], - update[2], + matrix_report[0], + matrix_report[1], + matrix_report[2], ) - if self._state.hid_pending: - self._send_hid() + state_changed = True - if self.debug_enabled: - print('New State: {}'.format(self._state._to_dict())) + if self._state.hid_pending: + self._send_hid() + old_timeouts_len = len(self._state.timeouts) self._state.process_timeouts() + new_timeouts_len = len(self._state.timeouts) + + if old_timeouts_len != new_timeouts_len: + state_changed = True for key in self._state.pending_keys: self._send_key(key) self._state.pending_key_handled() + state_changed = True if self._state.macro_pending: for key in self._state.macro_pending(self): self._send_key(key) self._state.resolve_macro() + state_changed = True + + if self.debug_enabled and state_changed: + print('New State: {}'.format(self._state._to_dict())) gc.collect() diff --git a/kmk/internal_state.py b/kmk/internal_state.py index cdb82e3..5352604 100644 --- a/kmk/internal_state.py +++ b/kmk/internal_state.py @@ -1,5 +1,6 @@ from kmk.consts import LeaderMode -from kmk.keycodes import FIRST_KMK_INTERNAL_KEYCODE, Keycodes, RawKeycodes +from kmk.keycodes import (FIRST_KMK_INTERNAL_KEYCODE, Keycodes, RawKeycodes, + TapDanceKeycode) from kmk.kmktime import sleep_ms, ticks_diff, ticks_ms from kmk.util import intify_coordinate @@ -30,6 +31,7 @@ class InternalState: timeouts = {} tapping = False tap_dance_counts = {} + tap_side_effects = {} def __init__(self, config): self.config = config @@ -108,7 +110,7 @@ class InternalState: print('No key accessible for col, row: {}, {}'.format(row, col)) return self - if self.tapping: + if self.tapping and not isinstance(kc_changed, TapDanceKeycode): self._process_tap_dance(kc_changed, is_pressed) else: if is_pressed: @@ -327,18 +329,7 @@ class InternalState: return self def _kc_tap_dance(self, changed_key, is_pressed): - if is_pressed: - self._begin_tap_dance(changed_key) - else: - self._end_tap_dance() - - return self - - def _begin_tap_dance(self, changed_key): - self.tap_dance_counts[changed_key] = 1 - self.set_timeout(500, self._end_tap_dance) - self.tapping = changed_key - return self + return self._process_tap_dance(changed_key, is_pressed) def _process_tap_dance(self, changed_key, is_pressed): if is_pressed: @@ -346,28 +337,47 @@ class InternalState: changed_key not in self.tap_dance_counts or not self.tap_dance_counts[changed_key] ): - self._end_tap_dance() + self.tap_dance_counts[changed_key] = 1 + self.set_timeout(500, lambda: self._end_tap_dance(changed_key)) + self.tapping = True else: self.tap_dance_counts[changed_key] += 1 - if self.tap_dance_counts[changed_key] == len(changed_key.codes): - self._end_tap_dance() + if changed_key not in self.tap_side_effects: + self.tap_side_effects[changed_key] = None + else: + if ( + self.tap_side_effects[changed_key] is not None or + self.tap_dance_counts[changed_key] == len(changed_key.codes) + ): + self._end_tap_dance(changed_key) return self - def _end_tap_dance(self): - k = self.tapping + def _end_tap_dance(self, td_key): + v = self.tap_dance_counts[td_key] - 1 - if not k: - # already handled elsewhere? - return self + if v >= 0: + if td_key in self.keys_pressed: + key_to_press = td_key.codes[v] + self.keys_pressed.add(key_to_press) + self.tap_side_effects[td_key] = key_to_press + self.hid_pending = True + else: + if self.tap_side_effects[td_key]: + self.keys_pressed.discard(self.tap_side_effects[td_key]) + self.tap_side_effects[td_key] = None + self.hid_pending = True + self._cleanup_tap_dance(td_key) + else: + self.pending_keys.append(td_key.codes[v]) + self._cleanup_tap_dance(td_key) - v = self.tap_dance_counts[k] - 1 - - self.pending_keys.append(k.codes[min(v, len(k.codes) - 1)]) - self.tap_dance_counts[k] = 0 - self.tapping = False + return self + def _cleanup_tap_dance(self, td_key): + self.tap_dance_counts[td_key] = 0 + self.tapping = any(count > 0 for count in self.tap_dance_counts.values()) return self def _begin_leader_mode(self): From d117005d8d0ec97c74181d1618fbb45b688241cb Mon Sep 17 00:00:00 2001 From: Josh Klar Date: Sat, 20 Oct 2018 17:53:58 -0700 Subject: [PATCH 4/5] Add press-and-hold support to TapDance, and clean up various ways of mangling key press states. Remove pending_keys entirely, replaced with a callback timeout) --- kmk/firmware.py | 16 ++-- kmk/internal_state.py | 90 +++++++++++++-------- user_keymaps/klardotsh/klarank_featherm4.py | 23 ++++-- 3 files changed, 79 insertions(+), 50 deletions(-) diff --git a/kmk/firmware.py b/kmk/firmware.py index bf4c134..62ba578 100644 --- a/kmk/firmware.py +++ b/kmk/firmware.py @@ -68,11 +68,11 @@ class Firmware: def _send_key(self, key): if not getattr(key, 'no_press', None): - self._state.force_keycode_down(key) + self._state.add_key(key) self._send_hid() if not getattr(key, 'no_release', None): - self._state.force_keycode_up(key) + self._state.remove_key(key) self._send_hid() def go(self): @@ -117,14 +117,10 @@ class Firmware: if old_timeouts_len != new_timeouts_len: state_changed = True - for key in self._state.pending_keys: - self._send_key(key) - self._state.pending_key_handled() - state_changed = True - - if self._state.macro_pending: - for key in self._state.macro_pending(self): - self._send_key(key) + if self._state.macros_pending: + for macro in self._state.macros_pending: + for key in macro(self): + self._send_key(key) self._state.resolve_macro() state_changed = True diff --git a/kmk/internal_state.py b/kmk/internal_state.py index 5352604..5d5d429 100644 --- a/kmk/internal_state.py +++ b/kmk/internal_state.py @@ -13,8 +13,7 @@ GESC_TRIGGERS = { class InternalState: keys_pressed = set() coord_keys_pressed = {} - pending_keys = [] - macro_pending = None + macros_pending = [] leader_pending = None leader_last_len = 0 hid_pending = False @@ -64,6 +63,7 @@ class InternalState: 'start_time': self.start_time, 'tapping': self.tapping, 'tap_dance_counts': self.tap_dance_counts, + 'timeouts': self.timeouts, } return ret @@ -83,14 +83,26 @@ class InternalState: return layer_key def set_timeout(self, after_ticks, callback): - timeout_key = ticks_ms() + after_ticks + if after_ticks is False: + # We allow passing False as an implicit "run this on the next process timeouts cycle" + timeout_key = ticks_ms() + else: + timeout_key = ticks_ms() + after_ticks + self.timeouts[timeout_key] = callback return self def process_timeouts(self): + if not self.timeouts: + return self + current_time = ticks_ms() - for k, v in self.timeouts.items(): + # cast this to a tuple to ensure that if a callback itself sets + # timeouts, we do not handle them on the current cycle + timeouts = tuple(self.timeouts.items()) + + for k, v in timeouts: if k <= current_time: v() del self.timeouts[k] @@ -114,44 +126,48 @@ class InternalState: self._process_tap_dance(kc_changed, is_pressed) else: if is_pressed: - self.keys_pressed.add(kc_changed) self.coord_keys_pressed[int_coord] = kc_changed + self.add_key(kc_changed) else: - self.keys_pressed.discard(kc_changed) + self.remove_key(kc_changed) self.keys_pressed.discard(self.coord_keys_pressed.get(int_coord, None)) self.coord_keys_pressed[int_coord] = None - if kc_changed.code >= FIRST_KMK_INTERNAL_KEYCODE: - self._process_internal_key_event( - kc_changed, - is_pressed, - ) - else: - self.hid_pending = True - if self.config.leader_mode % 2 == 1: self._process_leader_mode() return self - def force_keycode_up(self, keycode): + def remove_key(self, keycode): self.keys_pressed.discard(keycode) - self.hid_pending = True + + if keycode.code >= FIRST_KMK_INTERNAL_KEYCODE: + self._process_internal_key_event(keycode, False) + else: + self.hid_pending = True + return self - def force_keycode_down(self, keycode): + def add_key(self, keycode): + # TODO Make this itself a macro keycode with a keyup handler + # rather than handling this inline here. Gross. if keycode.code == Keycodes.KMK.KC_MACRO_SLEEP_MS: sleep_ms(keycode.ms) else: self.keys_pressed.add(keycode) - self.hid_pending = True + + if keycode.code >= FIRST_KMK_INTERNAL_KEYCODE: + self._process_internal_key_event(keycode, True) + else: + self.hid_pending = True return self - def pending_key_handled(self): - popped = self.pending_keys.pop() - - if self.config.debug_enabled: - print('Popped pending key: {}'.format(popped)) + def tap_key(self, keycode): + self.add_key(keycode) + # On the next cycle, we'll remove the key. This is way more clean than + # the `pending_keys` implementation that we used to rely on in + # firmware.py + self.set_timeout(False, lambda: self.remove_key(keycode)) return self @@ -163,7 +179,7 @@ class InternalState: if self.config.debug_enabled: print('Macro complete!') - self.macro_pending = None + self.macros_pending.pop() return self def _process_internal_key_event(self, changed_key, is_pressed): @@ -224,7 +240,7 @@ class InternalState: ticks_diff(ticks_ms(), self.start_time['lt']) < self.config.tap_time ): self.hid_pending = True - self.pending_keys.append(changed_key.kc) + self.tap_key(changed_key.kc) self._layer_mo(changed_key, is_pressed) self.start_time['lt'] = None @@ -284,10 +300,10 @@ class InternalState: def _kc_macro(self, changed_key, is_pressed): if is_pressed: if changed_key.keyup: - self.macro_pending = changed_key.keyup + self.macros_pending.append(changed_key.keyup) else: if changed_key.keydown: - self.macro_pending = changed_key.keydown + self.macros_pending.append(changed_key.keydown) return self @@ -333,12 +349,22 @@ class InternalState: def _process_tap_dance(self, changed_key, is_pressed): if is_pressed: + if not isinstance(changed_key, TapDanceKeycode): + # If we get here, changed_key is not a TapDanceKeycode and thus + # the user kept typing elsewhere (presumably). End ALL of the + # currently outstanding tap dance runs. + for k, v in self.tap_dance_counts.items(): + if v: + self._end_tap_dance(k) + + return self + if ( changed_key not in self.tap_dance_counts or not self.tap_dance_counts[changed_key] ): self.tap_dance_counts[changed_key] = 1 - self.set_timeout(500, lambda: self._end_tap_dance(changed_key)) + self.set_timeout(self.config.tap_time, lambda: self._end_tap_dance(changed_key)) self.tapping = True else: self.tap_dance_counts[changed_key] += 1 @@ -360,17 +386,17 @@ class InternalState: if v >= 0: if td_key in self.keys_pressed: key_to_press = td_key.codes[v] - self.keys_pressed.add(key_to_press) + self.add_key(key_to_press) self.tap_side_effects[td_key] = key_to_press self.hid_pending = True else: if self.tap_side_effects[td_key]: - self.keys_pressed.discard(self.tap_side_effects[td_key]) + self.remove_key(self.tap_side_effects[td_key]) self.tap_side_effects[td_key] = None self.hid_pending = True self._cleanup_tap_dance(td_key) else: - self.pending_keys.append(td_key.codes[v]) + self.tap_key(td_key.codes[v]) self._cleanup_tap_dance(td_key) return self @@ -395,7 +421,7 @@ class InternalState: lmh = tuple(self.leader_mode_history) if lmh in self.config.leader_dictionary: - self.macro_pending = self.config.leader_dictionary[lmh].keydown + self.macros_pending.append(self.config.leader_dictionary[lmh].keydown) return self._exit_leader_mode() diff --git a/user_keymaps/klardotsh/klarank_featherm4.py b/user_keymaps/klardotsh/klarank_featherm4.py index cfd0913..d8cf199 100644 --- a/user_keymaps/klardotsh/klarank_featherm4.py +++ b/user_keymaps/klardotsh/klarank_featherm4.py @@ -10,9 +10,6 @@ keyboard = Firmware() keyboard.debug_enabled = True keyboard.unicode_mode = UnicodeModes.LINUX -_______ = KC.TRNS -xxxxxxx = KC.NO - emoticons = cuss({ # Emojis 'BEER': r'🍺', @@ -56,12 +53,22 @@ keyboard.leader_dictionary = { glds('cel'): emoticons.CELEBRATORY_GLITTER, } +_______ = KC.TRNS +xxxxxxx = KC.NO +HELLA_TD = KC.TD( + KC.A, + KC.B, + send_string('macros in a tap dance? I think yes'), + KC.TG(1), +) + + keyboard.keymap = [ [ [KC.GESC, KC.QUOT, KC.COMM, KC.DOT, KC.P, KC.Y, KC.F, KC.G, KC.C, KC.R, KC.L, KC.BSPC], [KC.TAB, KC.A, KC.O, KC.E, KC.U, KC.I, KC.D, KC.H, KC.T, KC.N, KC.S, KC.ENT], [KC.LGUI, KC.SCLN, KC.Q, KC.J, KC.K, KC.X, KC.B, KC.M, KC.W, KC.V, KC.Z, KC.LALT], - [KC.LCTL, KC.TD(KC.A, KC.B), KC.LSHIFT(KC.LGUI), KC.MO(2), KC.MO(3), KC.LSFT, KC.SPC, KC.MO(1), KC.LEFT, KC.DOWN, KC.UP, KC.RGHT], + [KC.LCTL, KC.LEAD, KC.LSHIFT(KC.LGUI), KC.MO(2), KC.MO(3), KC.LSFT, KC.SPC, KC.MO(1), KC.LEFT, KC.DOWN, KC.UP, KC.RGHT], ], [ @@ -79,10 +86,10 @@ keyboard.keymap = [ ], [ - [KC.GRV, KC.EXLM, KC.AT, KC.HASH, KC.DLR, KC.PERC, KC.CIRC, KC.AMPR, KC.ASTR, KC.LPRN, KC.RPRN, KC.SLSH], - [KC.TAB, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, KC.MINS], - [KC.LGUI, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx], - [KC.LCTL, KC.DBG, xxxxxxx, xxxxxxx, _______, _______, xxxxxxx, xxxxxxx, KC.MUTE, KC.VOLD, KC.VOLU, xxxxxxx], + [KC.GRV, KC.EXLM, KC.AT, KC.HASH, KC.DLR, KC.PERC, KC.CIRC, KC.AMPR, KC.ASTR, KC.LPRN, KC.RPRN, KC.SLSH], + [KC.TAB, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, KC.MINS], + [KC.LGUI, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx], + [KC.LCTL, KC.DBG, HELLA_TD, xxxxxxx, _______, _______, xxxxxxx, xxxxxxx, KC.MUTE, KC.VOLD, KC.VOLU, xxxxxxx], ], ] From db741eb055b39f7d59abee8cc35abd36209b78a9 Mon Sep 17 00:00:00 2001 From: Josh Klar Date: Mon, 5 Nov 2018 21:33:42 -0800 Subject: [PATCH 5/5] Add some documentation --- docs/tapdance.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 docs/tapdance.md diff --git a/docs/tapdance.md b/docs/tapdance.md new file mode 100644 index 0000000..0f79078 --- /dev/null +++ b/docs/tapdance.md @@ -0,0 +1,61 @@ +# Tap Dance + +Tap dance is a way to allow a single physical key to work as multple logical +keys / actions without using layers. With basic tap dance, you can trigger these +"nested" keys or macros through a series of taps of the physical key within a +given timeout. + +The resulting "logical" action works just like any other key - it can be pressed +and immediately released, or it can be held. For example, let's take a key +`KC.TD(KC.A, KC.B)`. If the tap dance key is tapped and released once quickly, +the letter "a" will be sent. If it is tapped and released twice quickly, the +letter "b" will be sent. If it is tapped once and held, the letter "a" will be +held down until the tap dance key is released. If it is tapped and released once +quickly, then tapped and held (both actions within the timeout window), the +letter "b" will be held down until the tap dance key is released. + +To use this, you may want to define a `tap_time` value in your keyboard +configuration. This is an integer in milliseconds, and defaults to `300`. + +You'll then want to create a sequence of keys using `KC.TD(KC.SOMETHING, +KC.SOMETHING_ELSE, MAYBE_THIS_IS_A_MACRO, WHATEVER_YO)`, and place it in your +keymap somewhere. The only limits on how many keys can go in the sequence are, +theoretically, the amount of RAM your MCU/board has, and how fast you can mash +the physical key. Here's your chance to use all that button-mash video game +experience you've built up over the years. + +**NOTE**: Currently our basic tap dance implementation has some limitations that +are planned to be worked around "eventually", but for now are noteworthy: + +- The behavior of momentary layer switching within a tap dance sequence is + currently "undefined" at best, and will probably crash your keyboard. For now, + we strongly recommend avoiding `KC.MO` (or any other layer switch keys that + use momentary switch behavior - `KC.LM`, `KC.LT`, and `KC.TT`) + +- Super fancy stuff like sending a keypress only when the leader key is released + (perhaps based on how long the leader key was held) is **unsupported** - an + example usecase might be "tap for Home, hold for Shift" + +Here's an example of all this in action: + +```python +# user_keymaps/some_silly_example.py +from kmk.boards.klarank import Firmware +from kmk.keycodes import KC +from kmk.macros.simple import send_string + +keyboard = Firmware() + +keyboard.tap_time = 750 + +EXAMPLE_TD = KC.TD( + KC.A, # Tap once for "a" + KC.B, # Tap twice for "b" + # Tap three times to send a raw string via macro + send_string('macros in a tap dance? I think yes'), + # Tap four times to toggle layer index 1 + KC.TG(1), +) + +keyboard.keymap = [[ ...., EXAMPLE_TD, ....], ....] +```