andrejl
/
qmk-dactyl-manuform-a
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Clean up Tap Dance docs (#9372) 

* Clean up Tap Dance docs

* Add heading IDs for translation
master
Ryan 2020-06-18 10:10:35 +10:00 committed by GitHub
parent a0bf235644
commit 1a159a38ed
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 261 additions and 273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

534
docs/feature_tap_dance.md
View File

@ -1,31 +1,24 @@
# Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things # Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things
## Introduction ## Introduction :id=introduction
Hit 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/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature: Hit 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/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature:
With 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. With 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.
## Explanatory Comparison with `ACTION_FUNCTION_TAP` ## How to Use Tap Dance :id=how-to-use
`ACTION_FUNCTION_TAP` can offer similar functionality to Tap Dance, but it's worth noting some important differences. To do this, let's explore a certain setup! We want one key to send `Space` on single-tap, but `Enter` on double-tap.
With `ACTION_FUNCTION_TAP`, it is quite a rain-dance to set this up, and has the problem that when the sequence is interrupted, the interrupting key will be sent first. Thus, `SPC a` will result in `a SPC` being sent, if `SPC` and `a` are both typed within `TAPPING_TERM`. With the Tap Dance feature, that'll come out correctly as `SPC a` (even if both `SPC` and `a` are typed within the `TAPPING_TERM`. First, you will need `TAP_DANCE_ENABLE = yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size.
To achieve this correct handling of interrupts, the implementation of Tap Dance hooks into two parts of the system: `process_record_quantum()`, and the matrix scan. These two parts are explained below, but for now the point to note is that we need the latter to be able to time out a tap sequence even when a key is not being pressed. That way, `SPC` alone will time out and register after `TAPPING_TERM` time.
## How to Use Tap Dance
But enough of the generalities; lets look at how to actually use Tap Dance!
First, you will need `TAP_DANCE_ENABLE=yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size.
Optionally, you might want to set a custom `TAPPING_TERM` time by adding something like this in you `config.h`: Optionally, you might want to set a custom `TAPPING_TERM` time by adding something like this in you `config.h`:
``` ```c
#define TAPPING_TERM 175 #define TAPPING_TERM 175
``` ```
The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead.
Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that - similar to `F()` - takes a number, which will later be used as an index into the `tap_dance_actions` array. Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that takes a number which will later be used as an index into the `tap_dance_actions` array.
After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options: After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options:
@ -43,11 +36,12 @@ The first option is enough for a lot of cases, that just want dual roles. For ex
Similar to the first option, the second option is good for simple layer-switching cases. Similar to the first option, the second option is good for simple layer-switching cases.
For more complicated cases, use the third or fourth options (examples of each are listed below). For more complicated cases, use the third or fourth options (examples of each are listed below).
Finally, the fifth option is particularly useful if your non-Tap-Dance keys start behaving weirdly after adding the code for your Tap Dance keys. The likely problem is that you changed the `TAPPING_TERM` time to make your Tap Dance keys easier for you to use, and that this has changed the way your other keys handle interrupts. Finally, the fifth option is particularly useful if your non-Tap-Dance keys start behaving weirdly after adding the code for your Tap Dance keys. The likely problem is that you changed the `TAPPING_TERM` time to make your Tap Dance keys easier for you to use, and that this has changed the way your other keys handle interrupts.
## Implementation Details ## Implementation Details :id=implementation
Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works! Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all 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 reset 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 reset the timer.
@ -58,9 +52,9 @@ Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-danc
For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros. For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros.
# Examples ## Examples :id=examples
## Simple Example ### Simple Example :id=simple-example
Here's a simple example for a single definition: Here's a simple example for a single definition:
@ -69,23 +63,26 @@ Here's a simple example for a single definition:
3. In your `keymap.c` file, define the variables and definitions, then add to your keymap: 3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
```c ```c
//Tap Dance Declarations // Tap Dance declarations
enum { enum {
TD_ESC_CAPS = 0 TD_ESC_CAPS,
}; };
//Tap Dance Definitions // Tap Dance definitions
qk_tap_dance_action_t tap_dance_actions[] = { qk_tap_dance_action_t tap_dance_actions[] = {
//Tap once for Esc, twice for Caps Lock // Tap once for Escape, twice for Caps Lock
[TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS) [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS),
// Other declarations would go here, separated by commas, if you have them
}; };
//In Layer declaration, add tap dance item in place of a key code // Add tap dance item in place of a key code
TD(TD_ESC_CAPS) const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
// ...
TD(TD_ESC_CAPS)
// ...
};
``` ```
## Complex Examples ### Complex Examples :id=complex-examples
This section details several complex tap dance examples. This section details several complex tap dance examples.
All the enums used in the examples are declared like this: All the enums used in the examples are declared like this:
@ -93,104 +90,105 @@ All the enums used in the examples are declared like this:
```c ```c
// Enums defined for all examples: // Enums defined for all examples:
enum { enum {
CT_SE = 0, CT_SE,
CT_CLN, CT_CLN,
CT_EGG, CT_EGG,
CT_FLSH, CT_FLSH,
X_TAP_DANCE X_TAP_DANCE
}; };
``` ```
### Example 1: Send `:` on Single Tap, `;` on Double Tap
#### Example 1: Send `:` on Single Tap, `;` on Double Tap :id=example-1
```c ```c
void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) { 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_code16(KC_COLN);
register_code (KC_SCLN); } else {
} else { register_code(KC_SCLN);
register_code (KC_SCLN); }
}
} }
void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) { void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) { if (state->count == 1) {
unregister_code (KC_RSFT); unregister_code16(KC_COLN);
unregister_code (KC_SCLN); } else {
} else { unregister_code(KC_SCLN);
unregister_code (KC_SCLN); }
}
} }
//All tap dance functions would go here. Only showing this one. // All tap dance functions would go here. Only showing this one.
qk_tap_dance_action_t tap_dance_actions[] = { qk_tap_dance_action_t tap_dance_actions[] = {
[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset) [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
}; };
``` ```
### Example 2: Send "Safety Dance!" After 100 Taps
#### Example 2: Send "Safety Dance!" After 100 Taps :id=example-2
```c ```c
void dance_egg (qk_tap_dance_state_t *state, void *user_data) { 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);
} }
} }
qk_tap_dance_action_t tap_dance_actions[] = { qk_tap_dance_action_t tap_dance_actions[] = {
[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg) [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
}; };
``` ```
### Example 3: Turn LED Lights On Then Off, One at a Time #### Example 3: Turn LED Lights On Then Off, One at a Time :id=example-3
```c ```c
// 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 fourth tap, turn them off from right to left
void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) { 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();
break; break;
case 2: case 2:
ergodox_right_led_2_on(); ergodox_right_led_2_on();
break; break;
case 3: case 3:
ergodox_right_led_1_on(); ergodox_right_led_1_on();
break; break;
case 4: case 4:
ergodox_right_led_3_off(); ergodox_right_led_3_off();
_delay_ms(50); wait_ms(50);
ergodox_right_led_2_off(); ergodox_right_led_2_off();
_delay_ms(50); wait_ms(50);
ergodox_right_led_1_off(); ergodox_right_led_1_off();
} }
} }
// 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 *user_data) { 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); }
}
} }
// if the flash state didn't happen, then turn off LEDs, left to right // If the flash state didn't happen, then turn off LEDs, left to right
void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) { 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); wait_ms(50);
ergodox_right_led_2_off(); ergodox_right_led_2_off();
_delay_ms(50); wait_ms(50);
ergodox_right_led_3_off(); ergodox_right_led_3_off();
} }
//All tap dances now put together. Example 3 is "CT_FLASH" // All tap dances now put together. Example 3 is "CT_FLASH"
qk_tap_dance_action_t tap_dance_actions[] = { 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_ADVANCED (NULL, dance_cln_finished, dance_cln_reset) [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)
}; };
``` ```
### Example 4: 'Quad Function Tap-Dance' #### Example 4: 'Quad Function Tap-Dance' :id=example-4
By [DanielGGordon](https://github.com/danielggordon) By [DanielGGordon](https://github.com/danielggordon)
@ -201,40 +199,37 @@ Below is a specific example:
* Double Tap = Send `Escape` * Double Tap = Send `Escape`
* Double Tap and Hold = Send `Alt` * Double Tap and Hold = Send `Alt`
## Setup
You will need a few things that can be used for 'Quad Function Tap-Dance'. You will need a few things that can be used for 'Quad Function Tap-Dance'.
You'll need to add these to the top of your `keymap.c` file, before your keymap. You'll need to add these to the top of your `keymap.c` file, before your keymap.
```c ```c
typedef struct { typedef struct {
bool is_press_action; bool is_press_action;
int state; uint8_t state;
} tap; } tap;
enum { enum {
SINGLE_TAP = 1, SINGLE_TAP = 1,
SINGLE_HOLD = 2, SINGLE_HOLD,
DOUBLE_TAP = 3, DOUBLE_TAP,
DOUBLE_HOLD = 4, DOUBLE_HOLD,
DOUBLE_SINGLE_TAP = 5, //send two single taps DOUBLE_SINGLE_TAP, // Send two single taps
TRIPLE_TAP = 6, TRIPLE_TAP,
TRIPLE_HOLD = 7 TRIPLE_HOLD
}; };
//Tap dance enums // Tap dance enums
enum { enum {
X_CTL = 0, X_CTL,
SOME_OTHER_DANCE SOME_OTHER_DANCE
}; };
int cur_dance (qk_tap_dance_state_t *state); uint8_t cur_dance(qk_tap_dance_state_t *state);
//for the x tap dance. Put it here so it can be used in any keymap
void x_finished (qk_tap_dance_state_t *state, void *user_data);
void x_reset (qk_tap_dance_state_t *state, void *user_data);
// For the x tap dance. Put it here so it can be used in any keymap
void x_finished(qk_tap_dance_state_t *state, void *user_data);
void x_reset(qk_tap_dance_state_t *state, void *user_data);
``` ```
Now, at the bottom of your `keymap.c` file, you'll need to add the following: Now, at the bottom of your `keymap.c` file, you'll need to add the following:
@ -267,65 +262,62 @@ Now, at the bottom of your `keymap.c` file, you'll need to add the following:
* For the third point, there does exist the 'DOUBLE_SINGLE_TAP', however this is not fully tested * For the third point, there does exist the 'DOUBLE_SINGLE_TAP', however this is not fully tested
* *
*/ */
int cur_dance (qk_tap_dance_state_t *state) { uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) { if (state->count == 1) {
if (state->interrupted || !state->pressed) return SINGLE_TAP; if (state->interrupted || !state->pressed) return SINGLE_TAP;
//key has not been interrupted, but they key is still held. Means you want to send a 'HOLD'. // Key has not been interrupted, but the key is still held. Means you want to send a 'HOLD'.
else return SINGLE_HOLD; else return SINGLE_HOLD;
} } else if (state->count == 2) {
else if (state->count == 2) { // DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap
/* // action when hitting 'pp'. Suggested use case for this return value is when you want to send two
* DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap // keystrokes of the key, and not the 'double tap' action/macro.
* action when hitting 'pp'. Suggested use case for this return value is when you want to send two if (state->interrupted) return DOUBLE_SINGLE_TAP;
* keystrokes of the key, and not the 'double tap' action/macro. else if (state->pressed) return DOUBLE_HOLD;
*/ else return DOUBLE_TAP;
if (state->interrupted) return DOUBLE_SINGLE_TAP; }
else if (state->pressed) return DOUBLE_HOLD;
else return DOUBLE_TAP; // Assumes no one is trying to type the same letter three times (at least not quickly).
} // If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add
//Assumes no one is trying to type the same letter three times (at least not quickly). // an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP'
//If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add if (state->count == 3) {
//an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP' if (state->interrupted || !state->pressed) return TRIPLE_TAP;
if (state->count == 3) { else return TRIPLE_HOLD;
if (state->interrupted || !state->pressed) return TRIPLE_TAP; } else return 8; // Magic number. At some point this method will expand to work for more presses
else return TRIPLE_HOLD;
}
else return 8; //magic number. At some point this method will expand to work for more presses
} }
//instanalize an instance of 'tap' for the 'x' tap dance. // Create an instance of 'tap' for the 'x' tap dance.
static tap xtap_state = { static tap xtap_state = {
.is_press_action = true, .is_press_action = true,
.state = 0 .state = 0
}; };
void x_finished (qk_tap_dance_state_t *state, void *user_data) { void x_finished(qk_tap_dance_state_t *state, void *user_data) {
xtap_state.state = cur_dance(state); xtap_state.state = cur_dance(state);
switch (xtap_state.state) { switch (xtap_state.state) {
case SINGLE_TAP: register_code(KC_X); break; case SINGLE_TAP: register_code(KC_X); break;
case SINGLE_HOLD: register_code(KC_LCTRL); break; case SINGLE_HOLD: register_code(KC_LCTRL); break;
case DOUBLE_TAP: register_code(KC_ESC); break; case DOUBLE_TAP: register_code(KC_ESC); break;
case DOUBLE_HOLD: register_code(KC_LALT); break; case DOUBLE_HOLD: register_code(KC_LALT); break;
case DOUBLE_SINGLE_TAP: register_code(KC_X); unregister_code(KC_X); register_code(KC_X); // Last case is for fast typing. Assuming your key is `f`:
//Last case is for fast typing. Assuming your key is `f`: // For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`.
//For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`. // In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms.
//In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms. case DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X);
} }
} }
void x_reset (qk_tap_dance_state_t *state, void *user_data) { void x_reset(qk_tap_dance_state_t *state, void *user_data) {
switch (xtap_state.state) { switch (xtap_state.state) {
case SINGLE_TAP: unregister_code(KC_X); break; case SINGLE_TAP: unregister_code(KC_X); break;
case SINGLE_HOLD: unregister_code(KC_LCTRL); break; case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
case DOUBLE_TAP: unregister_code(KC_ESC); break; case DOUBLE_TAP: unregister_code(KC_ESC); break;
case DOUBLE_HOLD: unregister_code(KC_LALT); case DOUBLE_HOLD: unregister_code(KC_LALT);
case DOUBLE_SINGLE_TAP: unregister_code(KC_X); case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
} }
xtap_state.state = 0; xtap_state.state = 0;
} }
qk_tap_dance_action_t tap_dance_actions[] = { qk_tap_dance_action_t tap_dance_actions[] = {
[X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL,x_finished, x_reset) [X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset)
}; };
``` ```
@ -335,90 +327,91 @@ If you want to implement this in your userspace, then you may want to check out
> In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`). > In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`).
### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys #### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5
Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`. Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`.
Below your layers and custom keycodes, add the following: Below your layers and custom keycodes, add the following:
```c ```c
// tapdance keycodes // Tap Dance keycodes
enum td_keycodes { enum td_keycodes {
ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance. ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance.
}; };
// define a type containing as many tapdance states as you need // Define a type containing as many tapdance states as you need
typedef enum { typedef enum {
SINGLE_TAP, SINGLE_TAP,
SINGLE_HOLD, SINGLE_HOLD,
DOUBLE_SINGLE_TAP DOUBLE_SINGLE_TAP
} td_state_t; } td_state_t;
// create a global instance of the tapdance state type // Create a global instance of the tapdance state type
static td_state_t td_state; static td_state_t td_state;
// declare your tapdance functions: // Declare your tapdance functions:
// function to determine the current tapdance state // Function to determine the current tapdance state
int cur_dance (qk_tap_dance_state_t *state); uint8_t cur_dance(qk_tap_dance_state_t *state);
// `finished` and `reset` functions for each tapdance keycode // `finished` and `reset` functions for each tapdance keycode
void altlp_finished (qk_tap_dance_state_t *state, void *user_data); void altlp_finished(qk_tap_dance_state_t *state, void *user_data);
void altlp_reset (qk_tap_dance_state_t *state, void *user_data); void altlp_reset(qk_tap_dance_state_t *state, void *user_data);
``` ```
Below your `LAYOUT`, define each of the tapdance functions: Below your `LAYOUT`, define each of the tapdance functions:
```c ```c
// determine the tapdance state to return // Determine the tapdance state to return
int cur_dance (qk_tap_dance_state_t *state) { uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) { if (state->count == 1) {
if (state->interrupted || !state->pressed) { return SINGLE_TAP; } if (state->interrupted || !state->pressed) return SINGLE_TAP;
else { return SINGLE_HOLD; } else return SINGLE_HOLD;
} }
if (state->count == 2) { return DOUBLE_SINGLE_TAP; }
else { return 3; } // any number higher than the maximum state value you return above
}
// handle the possible states for each tapdance keycode you define:
void altlp_finished (qk_tap_dance_state_t *state, void *user_data) { if (state->count == 2) return DOUBLE_SINGLE_TAP;
td_state = cur_dance(state); else return 3; // Any number higher than the maximum state value you return above
switch (td_state) {
case SINGLE_TAP:
register_code16(KC_LPRN);
break;
case SINGLE_HOLD:
register_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_on(_MY_LAYER)` here
break;
case DOUBLE_SINGLE_TAP: // allow nesting of 2 parens `((` within tapping term
tap_code16(KC_LPRN);
register_code16(KC_LPRN);
}
} }
void altlp_reset (qk_tap_dance_state_t *state, void *user_data) { // Handle the possible states for each tapdance keycode you define:
switch (td_state) {
case SINGLE_TAP: void altlp_finished(qk_tap_dance_state_t *state, void *user_data) {
unregister_code16(KC_LPRN); td_state = cur_dance(state);
break; switch (td_state) {
case SINGLE_HOLD: case SINGLE_TAP:
unregister_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_off(_MY_LAYER)` here register_code16(KC_LPRN);
break; break;
case DOUBLE_SINGLE_TAP: case SINGLE_HOLD:
unregister_code16(KC_LPRN); register_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_on(_MY_LAYER)` here
} break;
case DOUBLE_SINGLE_TAP: // Allow nesting of 2 parens `((` within tapping term
tap_code16(KC_LPRN);
register_code16(KC_LPRN);
}
} }
// define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions void altlp_reset(qk_tap_dance_state_t *state, void *user_data) {
switch (td_state) {
case SINGLE_TAP:
unregister_code16(KC_LPRN);
break;
case SINGLE_HOLD:
unregister_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_off(_MY_LAYER)` here
break;
case DOUBLE_SINGLE_TAP:
unregister_code16(KC_LPRN);
}
}
// Define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions
qk_tap_dance_action_t tap_dance_actions[] = { qk_tap_dance_action_t tap_dance_actions[] = {
[ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset) [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
}; };
``` ```
Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`. Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`.
### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys #### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys :id=example-6
Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this example, we will set up a key to function as `KC_QUOT` on single-tap, as `MO(_MY_LAYER)` on single-hold, and `TG(_MY_LAYER)` on double-tap. Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this example, we will set up a key to function as `KC_QUOT` on single-tap, as `MO(_MY_LAYER)` on single-hold, and `TG(_MY_LAYER)` on double-tap.
@ -426,97 +419,92 @@ The first step is to include the following code towards the beginning of your `k
```c ```c
typedef struct { typedef struct {
bool is_press_action; bool is_press_action;
int state; uint8_t state;
} tap; } tap;
//Define a type for as many tap dance states as you need // Define a type for as many tap dance states as you need
enum { enum {
SINGLE_TAP = 1, SINGLE_TAP = 1,
SINGLE_HOLD = 2, SINGLE_HOLD,
DOUBLE_TAP = 3 DOUBLE_TAP
}; };
enum { enum {
QUOT_LAYR = 0 //Our custom tap dance key; add any other tap dance keys to this enum QUOT_LAYR, // Our custom tap dance key; add any other tap dance keys to this enum
}; };
//Declare the functions to be used with your tap dance key(s) // Declare the functions to be used with your tap dance key(s)
//Function associated with all tap dances // Function associated with all tap dances
int cur_dance (qk_tap_dance_state_t *state); uint8_t cur_dance(qk_tap_dance_state_t *state);
//Functions associated with individual tap dances // Functions associated with individual tap dances
void ql_finished (qk_tap_dance_state_t *state, void *user_data); void ql_finished(qk_tap_dance_state_t *state, void *user_data);
void ql_reset (qk_tap_dance_state_t *state, void *user_data); void ql_reset(qk_tap_dance_state_t *state, void *user_data);
``` ```
Towards the bottom of your `keymap.c`, include the following code: Towards the bottom of your `keymap.c`, include the following code:
```c ```c
//Determine the current tap dance state // Determine the current tap dance state
int cur_dance (qk_tap_dance_state_t *state) { uint8_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) { if (state->count == 1) {
if (!state->pressed) { if (!state->pressed) return SINGLE_TAP;
return SINGLE_TAP; else return SINGLE_HOLD;
} else { } else if (state->count == 2) return DOUBLE_TAP;
return SINGLE_HOLD; else return 8;
}
} else if (state->count == 2) {
return DOUBLE_TAP;
}
else return 8;
} }
//Initialize tap structure associated with example tap dance key // Initialize tap structure associated with example tap dance key
static tap ql_tap_state = { static tap ql_tap_state = {
.is_press_action = true, .is_press_action = true,
.state = 0 .state = 0
}; };
//Functions that control what our tap dance key does // Functions that control what our tap dance key does
void ql_finished (qk_tap_dance_state_t *state, void *user_data) { void ql_finished(qk_tap_dance_state_t *state, void *user_data) {
ql_tap_state.state = cur_dance(state); ql_tap_state.state = cur_dance(state);
switch (ql_tap_state.state) { switch (ql_tap_state.state) {
case SINGLE_TAP: case SINGLE_TAP:
tap_code(KC_QUOT); tap_code(KC_QUOT);
break; break;
case SINGLE_HOLD: case SINGLE_HOLD:
layer_on(_MY_LAYER); layer_on(_MY_LAYER);
break; break;
case DOUBLE_TAP: case DOUBLE_TAP:
//check to see if the layer is already set // Check to see if the layer is already set
if (layer_state_is(_MY_LAYER)) { if (layer_state_is(_MY_LAYER)) {
//if already set, then switch it off // If already set, then switch it off
layer_off(_MY_LAYER);
} else {
// If not already set, then switch the layer on
layer_on(_MY_LAYER);
}
break;
}
}
void ql_reset(qk_tap_dance_state_t *state, void *user_data) {
// If the key was held down and now is released then switch off the layer
if (ql_tap_state.state == SINGLE_HOLD) {
layer_off(_MY_LAYER); layer_off(_MY_LAYER);
} else { }
//if not already set, then switch the layer on ql_tap_state.state = 0;
layer_on(_MY_LAYER);
}
break;
}
} }
void ql_reset (qk_tap_dance_state_t *state, void *user_data) { // Associate our tap dance key with its functionality
//if the key was held down and now is released then switch off the layer
if (ql_tap_state.state==SINGLE_HOLD) {
layer_off(_MY_LAYER);
}
ql_tap_state.state = 0;
}
//Associate our tap dance key with its functionality
qk_tap_dance_action_t tap_dance_actions[] = { qk_tap_dance_action_t tap_dance_actions[] = {
[QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275) [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
}; };
``` ```
The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is( layer )` function which returns `true` if the given `layer` is active. The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is(layer)` function which returns `true` if the given `layer` is active.
The use of `cur_dance()` and `ql_tap_state` mirrors the above examples. The use of `cur_dance()` and `ql_tap_state` mirrors the above examples.
The `case:SINGLE_TAP` in `ql_finished` is similar to the above examples. The `case:SINGLE_HOLD` works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `case:DOUBLE_TAP` works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`. The `case:SINGLE_TAP` in `ql_finished` is similar to the above examples. The `SINGLE_HOLD` case works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `DOUBLE_TAP` case works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`.
`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here. `tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here.
Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`. Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`.