aboutsummaryrefslogtreecommitdiff
path: root/readme.md
diff options
context:
space:
mode:
Diffstat (limited to 'readme.md')
-rw-r--r--readme.md31
1 files changed, 18 insertions, 13 deletions
diff --git a/readme.md b/readme.md
index 9a4c314dc..affee1b62 100644
--- a/readme.md
+++ b/readme.md
@@ -346,6 +346,8 @@ That's what `KC_LEAD` does. Here's an example:
3463. Within your `matrix_scan_user` function, do something like this: 3463. Within your `matrix_scan_user` function, do something like this:
347 347
348``` 348```
349LEADER_EXTERNS();
350
349void matrix_scan_user(void) { 351void matrix_scan_user(void) {
350 LEADER_DICTIONARY() { 352 LEADER_DICTIONARY() {
351 leading = false; 353 leading = false;
@@ -373,7 +375,7 @@ As you can see, you have three function. you can use - `SEQ_ONE_KEY` for single-
373 375
374### Tap Dance: A single key can do 3, 5, or 100 different things 376### Tap Dance: A single key can do 3, 5, or 100 different things
375 377
376Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/jackhumbert/qmk_firmware/pull/451). Here's how Algernon describes the feature: 378Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/jackhumbert/qmk_firmware/pull/451). Here's how algernon describes the feature:
377 379
378With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter. 380With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter.
379 381
@@ -389,7 +391,7 @@ First, you will need `TAP_DANCE_ENABLE=yes` in your `Makefile`, because the feat
389 391
390This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options: 392This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options:
391 393
392* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. 394* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held.
393* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action. 395* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
394* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function on when the dance action finishes (like the previous option), and the last function when the tap dance action resets. 396* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function on when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
395 397
@@ -397,8 +399,6 @@ The first option is enough for a lot of cases, that just want dual roles. For ex
397 399
398And that's the bulk of it! 400And that's the bulk of it!
399 401
400Do note, however, that this implementation does have some consequences: keys do not register until either they reach the tapping ceiling, or they time out. This means that if you hold the key, nothing happens, no repeat, no nothing. It is possible to detect held state, and register an action then too, but that's not implemented yet. Keys also unregister immediately after being registered, so you can't even hold the second tap. This is intentional, to be consistent.
401
402And now, on to the explanation of how it works! 402And now, on to the explanation of how it works!
403 403
404The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and the timer. 404The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and the timer.
@@ -421,20 +421,25 @@ enum {
421 421
422/* Have the above three on the keymap, TD(CT_SE), etc... */ 422/* Have the above three on the keymap, TD(CT_SE), etc... */
423 423
424void dance_cln (qk_tap_dance_state_t *state) { 424void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
425 if (state->count == 1) { 425 if (state->count == 1) {
426 register_code (KC_RSFT); 426 register_code (KC_RSFT);
427 register_code (KC_SCLN); 427 register_code (KC_SCLN);
428 unregister_code (KC_SCLN);
429 unregister_code (KC_RSFT);
430 } else { 428 } else {
431 register_code (KC_SCLN); 429 register_code (KC_SCLN);
430 }
431}
432
433void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
434 if (state->count == 1) {
435 unregister_code (KC_RSFT);
436 unregister_code (KC_SCLN);
437 } else {
432 unregister_code (KC_SCLN); 438 unregister_code (KC_SCLN);
433 reset_tap_dance (state);
434 } 439 }
435} 440}
436 441
437void dance_egg (qk_tap_dance_state_t *state) { 442void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
438 if (state->count >= 100) { 443 if (state->count >= 100) {
439 SEND_STRING ("Safety dance!"); 444 SEND_STRING ("Safety dance!");
440 reset_tap_dance (state); 445 reset_tap_dance (state);
@@ -443,7 +448,7 @@ void dance_egg (qk_tap_dance_state_t *state) {
443 448
444// on each tap, light up one led, from right to left 449// on each tap, light up one led, from right to left
445// on the forth tap, turn them off from right to left 450// on the forth tap, turn them off from right to left
446void dance_flsh_each(qk_tap_dance_state_t *state) { 451void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
447 switch (state->count) { 452 switch (state->count) {
448 case 1: 453 case 1:
449 ergodox_right_led_3_on(); 454 ergodox_right_led_3_on();
@@ -464,7 +469,7 @@ void dance_flsh_each(qk_tap_dance_state_t *state) {
464} 469}
465 470
466// on the fourth tap, set the keyboard on flash state 471// on the fourth tap, set the keyboard on flash state
467void dance_flsh_finished(qk_tap_dance_state_t *state) { 472void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
468 if (state->count >= 4) { 473 if (state->count >= 4) {
469 reset_keyboard(); 474 reset_keyboard();
470 reset_tap_dance(state); 475 reset_tap_dance(state);
@@ -472,7 +477,7 @@ void dance_flsh_finished(qk_tap_dance_state_t *state) {
472} 477}
473 478
474// if the flash state didnt happen, then turn off leds, left to right 479// if the flash state didnt happen, then turn off leds, left to right
475void dance_flsh_reset(qk_tap_dance_state_t *state) { 480void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
476 ergodox_right_led_1_off(); 481 ergodox_right_led_1_off();
477 _delay_ms(50); 482 _delay_ms(50);
478 ergodox_right_led_2_off(); 483 ergodox_right_led_2_off();
@@ -482,7 +487,7 @@ void dance_flsh_reset(qk_tap_dance_state_t *state) {
482 487
483const qk_tap_dance_action_t tap_dance_actions[] = { 488const qk_tap_dance_action_t tap_dance_actions[] = {
484 [CT_SE] = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT) 489 [CT_SE] = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
485 ,[CT_CLN] = ACTION_TAP_DANCE_FN (dance_cln) 490 ,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
486 ,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg) 491 ,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
487 ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset) 492 ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
488}; 493};