readme.md: Update the tap dance docs

Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
This commit is contained in:
Gergely Nagy 2016-07-20 12:04:14 +02:00
parent fca34e2ad6
commit 13385f5691

View File

@ -389,7 +389,7 @@ First, you will need `TAP_DANCE_ENABLE=yes` in your `Makefile`, because the feat
This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options: This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options:
* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. * `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.
* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action. * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
* `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. * `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.
@ -397,8 +397,6 @@ The first option is enough for a lot of cases, that just want dual roles. For ex
And that's the bulk of it! And that's the bulk of it!
Do 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.
And now, on to the explanation of how it works! And now, on to the explanation of how it works!
The 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. The 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 +419,25 @@ enum {
/* Have the above three on the keymap, TD(CT_SE), etc... */ /* Have the above three on the keymap, TD(CT_SE), etc... */
void dance_cln (qk_tap_dance_state_t *state) { void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) { if (state->count == 1) {
register_code (KC_RSFT); register_code (KC_RSFT);
register_code (KC_SCLN); register_code (KC_SCLN);
unregister_code (KC_SCLN);
unregister_code (KC_RSFT);
} else { } else {
register_code (KC_SCLN); register_code (KC_SCLN);
unregister_code (KC_SCLN);
reset_tap_dance (state);
} }
} }
void dance_egg (qk_tap_dance_state_t *state) { void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
unregister_code (KC_RSFT);
unregister_code (KC_SCLN);
} else {
unregister_code (KC_SCLN);
}
}
void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 100) { if (state->count >= 100) {
SEND_STRING ("Safety dance!"); SEND_STRING ("Safety dance!");
reset_tap_dance (state); reset_tap_dance (state);
@ -443,7 +446,7 @@ void dance_egg (qk_tap_dance_state_t *state) {
// on each tap, light up one led, from right to left // on each tap, light up one led, from right to left
// on the forth tap, turn them off from right to left // on the forth tap, turn them off from right to left
void dance_flsh_each(qk_tap_dance_state_t *state) { void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
switch (state->count) { switch (state->count) {
case 1: case 1:
ergodox_right_led_3_on(); ergodox_right_led_3_on();
@ -464,7 +467,7 @@ void dance_flsh_each(qk_tap_dance_state_t *state) {
} }
// on the fourth tap, set the keyboard on flash state // on the fourth tap, set the keyboard on flash state
void dance_flsh_finished(qk_tap_dance_state_t *state) { void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 4) { if (state->count >= 4) {
reset_keyboard(); reset_keyboard();
reset_tap_dance(state); reset_tap_dance(state);
@ -472,7 +475,7 @@ void dance_flsh_finished(qk_tap_dance_state_t *state) {
} }
// if the flash state didnt happen, then turn off leds, left to right // if the flash state didnt happen, then turn off leds, left to right
void dance_flsh_reset(qk_tap_dance_state_t *state) { void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
ergodox_right_led_1_off(); ergodox_right_led_1_off();
_delay_ms(50); _delay_ms(50);
ergodox_right_led_2_off(); ergodox_right_led_2_off();
@ -482,7 +485,7 @@ void dance_flsh_reset(qk_tap_dance_state_t *state) {
const qk_tap_dance_action_t tap_dance_actions[] = { const qk_tap_dance_action_t tap_dance_actions[] = {
[CT_SE] = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT) [CT_SE] = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
,[CT_CLN] = ACTION_TAP_DANCE_FN (dance_cln) ,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg) ,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset) ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
}; };