qmk

Unnamed repository; edit this file 'description' to name the repository.
git clone git://git.z3bra.org/qmk.git
Log | Files | Refs | Submodules | LICENSE

feature_tap_dance.md (22482B)


      1 # Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things
      2 
      3 ## Introduction
      4 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:
      5 
      6 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.
      7 
      8 ## Explanatory Comparison with `ACTION_FUNCTION_TAP`
      9 `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.
     10 
     11 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`.
     12 
     13 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.
     14 
     15 ## How to Use Tap Dance
     16 But enough of the generalities; lets look at how to actually use Tap Dance!
     17 
     18 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. 
     19 
     20 Optionally, you might want to set a custom `TAPPING_TERM` time by adding something like this in you `config.h`:
     21 
     22 ```
     23 #define TAPPING_TERM 175
     24 ```
     25 
     26 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. 
     27 
     28 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. 
     29 
     30 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:
     31 
     32 * `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.
     33 * `ACTION_TAP_DANCE_DUAL_ROLE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode).
     34 * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
     35 * `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
     36 * `ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`.
     37 
     38 The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. 
     39 
     40 !> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported.
     41 
     42 Similar to the first option, the second option is good for simple layer-switching cases.
     43 
     44 For more complicated cases, use the third or fourth options (examples of each are listed below). 
     45 
     46 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.
     47 
     48 ## Implementation Details
     49 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!
     50 
     51 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.
     52 
     53 This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness.
     54 
     55 Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-dance keys.
     56 
     57 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.
     58 
     59 # Examples
     60 
     61 ## Simple Example
     62 
     63 Here's a simple example for a single definition:
     64 
     65 1. In your `rules.mk`, add `TAP_DANCE_ENABLE = yes`
     66 2. In your `config.h` (which you can copy from `qmk_firmware/keyboards/planck/config.h` to your keymap directory), add `#define TAPPING_TERM 200`
     67 3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
     68 
     69 ```c
     70 //Tap Dance Declarations
     71 enum {
     72   TD_ESC_CAPS = 0
     73 };
     74 
     75 //Tap Dance Definitions
     76 qk_tap_dance_action_t tap_dance_actions[] = {
     77   //Tap once for Esc, twice for Caps Lock
     78   [TD_ESC_CAPS]  = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS)
     79 // Other declarations would go here, separated by commas, if you have them
     80 };
     81 
     82 //In Layer declaration, add tap dance item in place of a key code
     83 TD(TD_ESC_CAPS)
     84 ```
     85 
     86 ## Complex Examples
     87 
     88 This section details several complex tap dance examples.
     89 All the enums used in the examples are declared like this:
     90 
     91 ```c
     92 // Enums defined for all examples:
     93 enum {
     94  CT_SE = 0,
     95  CT_CLN,
     96  CT_EGG,
     97  CT_FLSH,
     98  X_TAP_DANCE
     99 };
    100 ```
    101 ### Example 1: Send `:` on Single Tap, `;` on Double Tap
    102 ```c
    103 void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
    104   if (state->count == 1) {
    105     register_code (KC_RSFT);
    106     register_code (KC_SCLN);
    107   } else {
    108     register_code (KC_SCLN);
    109   }
    110 }
    111 
    112 void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
    113   if (state->count == 1) {
    114     unregister_code (KC_RSFT);
    115     unregister_code (KC_SCLN);
    116   } else {
    117     unregister_code (KC_SCLN);
    118   }
    119 }
    120 
    121 //All tap dance functions would go here. Only showing this one.
    122 qk_tap_dance_action_t tap_dance_actions[] = {
    123  [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
    124 };
    125 ```
    126 ### Example 2: Send "Safety Dance!" After 100 Taps
    127 ```c
    128 void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
    129   if (state->count >= 100) {
    130     SEND_STRING ("Safety dance!");
    131     reset_tap_dance (state);
    132   }
    133 }
    134 
    135 qk_tap_dance_action_t tap_dance_actions[] = {
    136  [CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
    137 };
    138 ```
    139 
    140 ### Example 3: Turn LED Lights On Then Off, One at a Time
    141 
    142 ```c
    143 // on each tap, light up one led, from right to left
    144 // on the forth tap, turn them off from right to left
    145 void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
    146   switch (state->count) {
    147   case 1:
    148     ergodox_right_led_3_on();
    149     break;
    150   case 2:
    151     ergodox_right_led_2_on();
    152     break;
    153   case 3:
    154     ergodox_right_led_1_on();
    155     break;
    156   case 4:
    157     ergodox_right_led_3_off();
    158     _delay_ms(50);
    159     ergodox_right_led_2_off();
    160     _delay_ms(50);
    161     ergodox_right_led_1_off();
    162   }
    163 }
    164 
    165 // on the fourth tap, set the keyboard on flash state
    166 void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
    167   if (state->count >= 4) {
    168     reset_keyboard();
    169     reset_tap_dance(state);
    170   }
    171 }
    172 
    173 // if the flash state didn't happen, then turn off LEDs, left to right
    174 void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
    175   ergodox_right_led_1_off();
    176   _delay_ms(50);
    177   ergodox_right_led_2_off();
    178   _delay_ms(50);
    179   ergodox_right_led_3_off();
    180 }
    181 
    182 //All tap dances now put together. Example 3 is "CT_FLASH"
    183 qk_tap_dance_action_t tap_dance_actions[] = {
    184   [CT_SE]  = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
    185  ,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
    186  ,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
    187  ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
    188 };
    189 ```
    190 
    191 ### Example 4: 'Quad Function Tap-Dance'
    192 
    193 By [DanielGGordon](https://github.com/danielggordon)
    194 
    195 Allow one key to have 4 (or more) functions, depending on number of presses, and if the key is held or tapped.
    196 Below is a specific example:
    197 *  Tap = Send `x`
    198 *  Hold = Send `Control`
    199 *  Double Tap = Send `Escape`
    200 *  Double Tap and Hold = Send `Alt`
    201 
    202 ## Setup
    203 
    204 You will need a few things that can be used for 'Quad Function Tap-Dance'. 
    205 
    206 You'll need to add these to the top of your `keymap.c` file, before your keymap. 
    207 
    208 ```c
    209 typedef struct {
    210   bool is_press_action;
    211   int state;
    212 } tap;
    213 
    214 enum {
    215   SINGLE_TAP = 1,
    216   SINGLE_HOLD = 2,
    217   DOUBLE_TAP = 3,
    218   DOUBLE_HOLD = 4,
    219   DOUBLE_SINGLE_TAP = 5, //send two single taps
    220   TRIPLE_TAP = 6,
    221   TRIPLE_HOLD = 7
    222 };
    223 
    224 //Tap dance enums
    225 enum {
    226   X_CTL = 0,
    227   SOME_OTHER_DANCE
    228 };
    229 
    230 int cur_dance (qk_tap_dance_state_t *state);
    231 
    232 //for the x tap dance. Put it here so it can be used in any keymap
    233 void x_finished (qk_tap_dance_state_t *state, void *user_data);
    234 void x_reset (qk_tap_dance_state_t *state, void *user_data);
    235 
    236 ```
    237 
    238 Now, at the bottom of your `keymap.c` file, you'll need to add the following: 
    239 
    240 ```c
    241 /* Return an integer that corresponds to what kind of tap dance should be executed.
    242  *
    243  * How to figure out tap dance state: interrupted and pressed.
    244  *
    245  * Interrupted: If the state of a dance dance is "interrupted", that means that another key has been hit
    246  *  under the tapping term. This is typically indicitive that you are trying to "tap" the key.
    247  *
    248  * Pressed: Whether or not the key is still being pressed. If this value is true, that means the tapping term
    249  *  has ended, but the key is still being pressed down. This generally means the key is being "held".
    250  *
    251  * One thing that is currenlty not possible with qmk software in regards to tap dance is to mimic the "permissive hold"
    252  *  feature. In general, advanced tap dances do not work well if they are used with commonly typed letters.
    253  *  For example "A". Tap dances are best used on non-letter keys that are not hit while typing letters.
    254  *
    255  * Good places to put an advanced tap dance:
    256  *  z,q,x,j,k,v,b, any function key, home/end, comma, semi-colon
    257  *
    258  * Criteria for "good placement" of a tap dance key:
    259  *  Not a key that is hit frequently in a sentence
    260  *  Not a key that is used frequently to double tap, for example 'tab' is often double tapped in a terminal, or
    261  *    in a web form. So 'tab' would be a poor choice for a tap dance.
    262  *  Letters used in common words as a double. For example 'p' in 'pepper'. If a tap dance function existed on the
    263  *    letter 'p', the word 'pepper' would be quite frustating to type.
    264  *
    265  * For the third point, there does exist the 'DOUBLE_SINGLE_TAP', however this is not fully tested
    266  *
    267  */
    268 int cur_dance (qk_tap_dance_state_t *state) {
    269   if (state->count == 1) {
    270     if (state->interrupted || !state->pressed)  return SINGLE_TAP;
    271     //key has not been interrupted, but they key is still held. Means you want to send a 'HOLD'.
    272     else return SINGLE_HOLD;
    273   }
    274   else if (state->count == 2) {
    275     /*
    276      * DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap
    277      * action when hitting 'pp'. Suggested use case for this return value is when you want to send two
    278      * keystrokes of the key, and not the 'double tap' action/macro.
    279     */
    280     if (state->interrupted) return DOUBLE_SINGLE_TAP;
    281     else if (state->pressed) return DOUBLE_HOLD;
    282     else return DOUBLE_TAP;
    283   }
    284   //Assumes no one is trying to type the same letter three times (at least not quickly).
    285   //If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add
    286   //an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP'
    287   if (state->count == 3) {
    288     if (state->interrupted || !state->pressed)  return TRIPLE_TAP;
    289     else return TRIPLE_HOLD;
    290   }
    291   else return 8; //magic number. At some point this method will expand to work for more presses
    292 }
    293 
    294 //instanalize an instance of 'tap' for the 'x' tap dance.
    295 static tap xtap_state = {
    296   .is_press_action = true,
    297   .state = 0
    298 };
    299 
    300 void x_finished (qk_tap_dance_state_t *state, void *user_data) {
    301   xtap_state.state = cur_dance(state);
    302   switch (xtap_state.state) {
    303     case SINGLE_TAP: register_code(KC_X); break;
    304     case SINGLE_HOLD: register_code(KC_LCTRL); break;
    305     case DOUBLE_TAP: register_code(KC_ESC); break;
    306     case DOUBLE_HOLD: register_code(KC_LALT); break;
    307     case DOUBLE_SINGLE_TAP: register_code(KC_X); unregister_code(KC_X); register_code(KC_X);
    308     //Last case is for fast typing. Assuming your key is `f`:
    309     //For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`.
    310     //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.
    311   }
    312 }
    313 
    314 void x_reset (qk_tap_dance_state_t *state, void *user_data) {
    315   switch (xtap_state.state) {
    316     case SINGLE_TAP: unregister_code(KC_X); break;
    317     case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
    318     case DOUBLE_TAP: unregister_code(KC_ESC); break;
    319     case DOUBLE_HOLD: unregister_code(KC_LALT);
    320     case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
    321   }
    322   xtap_state.state = 0;
    323 }
    324 
    325 qk_tap_dance_action_t tap_dance_actions[] = {
    326   [X_CTL]     = ACTION_TAP_DANCE_FN_ADVANCED(NULL,x_finished, x_reset)
    327 };
    328 ```
    329 
    330 And then simply use `TD(X_CTL)` anywhere in your keymap.
    331 
    332 If you want to implement this in your userspace, then you may want to check out how [DanielGGordon](https://github.com/qmk/qmk_firmware/tree/master/users/gordon) has implemented this in their userspace.
    333 
    334 ### Example 5: Using tap dance for advanced mod-tap and layer-tap keys
    335 
    336 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`.
    337 
    338 Below your layers and custom keycodes, add the following:
    339 
    340 ```c
    341 // tapdance keycodes
    342 enum td_keycodes {
    343   ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance.
    344 };
    345 
    346 // define a type containing as many tapdance states as you need
    347 typedef enum {
    348   SINGLE_TAP,
    349   SINGLE_HOLD,
    350   DOUBLE_SINGLE_TAP
    351 } td_state_t;
    352 
    353 // create a global instance of the tapdance state type
    354 static td_state_t td_state;
    355 
    356 // declare your tapdance functions:
    357 
    358 // function to determine the current tapdance state
    359 int cur_dance (qk_tap_dance_state_t *state);
    360 
    361 // `finished` and `reset` functions for each tapdance keycode
    362 void altlp_finished (qk_tap_dance_state_t *state, void *user_data);
    363 void altlp_reset (qk_tap_dance_state_t *state, void *user_data);
    364 ```
    365 
    366 Below your `LAYOUT`, define each of the tapdance functions:
    367 
    368 ```c
    369 // determine the tapdance state to return
    370 int cur_dance (qk_tap_dance_state_t *state) {
    371   if (state->count == 1) {
    372     if (state->interrupted || !state->pressed) { return SINGLE_TAP; }
    373     else { return SINGLE_HOLD; }
    374   }
    375   if (state->count == 2) { return DOUBLE_SINGLE_TAP; }
    376   else { return 3; } // any number higher than the maximum state value you return above
    377 }
    378  
    379 // handle the possible states for each tapdance keycode you define:
    380 
    381 void altlp_finished (qk_tap_dance_state_t *state, void *user_data) {
    382   td_state = cur_dance(state);
    383   switch (td_state) {
    384     case SINGLE_TAP:
    385       register_code16(KC_LPRN);
    386       break;
    387     case SINGLE_HOLD:
    388       register_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_on(_MY_LAYER)` here
    389       break;
    390     case DOUBLE_SINGLE_TAP: // allow nesting of 2 parens `((` within tapping term
    391       tap_code16(KC_LPRN);
    392       register_code16(KC_LPRN);
    393   }
    394 }
    395 
    396 void altlp_reset (qk_tap_dance_state_t *state, void *user_data) {
    397   switch (td_state) {
    398     case SINGLE_TAP:
    399       unregister_code16(KC_LPRN);
    400       break;
    401     case SINGLE_HOLD:
    402       unregister_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_off(_MY_LAYER)` here
    403       break;
    404     case DOUBLE_SINGLE_TAP:
    405       unregister_code16(KC_LPRN);
    406   }
    407 }
    408 
    409 // define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions
    410 qk_tap_dance_action_t tap_dance_actions[] = {
    411   [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
    412 };
    413 ```
    414 
    415 Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`.
    416 
    417 ### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys
    418 
    419 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.
    420 
    421 The first step is to include the following code towards the beginning of your `keymap.c`:
    422 
    423 ```
    424 typedef struct {
    425   bool is_press_action;
    426   int state;
    427 } tap;
    428 
    429 //Define a type for as many tap dance states as you need
    430 enum {
    431   SINGLE_TAP = 1,
    432   SINGLE_HOLD = 2,
    433   DOUBLE_TAP = 3
    434 };
    435 
    436 enum {
    437   QUOT_LAYR = 0     //Our custom tap dance key; add any other tap dance keys to this enum 
    438 };
    439 
    440 //Declare the functions to be used with your tap dance key(s)
    441 
    442 //Function associated with all tap dances
    443 int cur_dance (qk_tap_dance_state_t *state);
    444 
    445 //Functions associated with individual tap dances
    446 void ql_finished (qk_tap_dance_state_t *state, void *user_data);
    447 void ql_reset (qk_tap_dance_state_t *state, void *user_data);
    448 
    449 //Declare variable to track which layer is active
    450 int active_layer;
    451 ```
    452 
    453 The above code is similar to that used in previous examples. The one point to note is that you need to declare a variable to keep track of what layer is currently the active layer. We'll see why shortly.
    454 
    455 Towards the bottom of your `keymap.c`, include the following code:
    456 
    457 ```
    458 //Update active_layer
    459 uint32_t layer_state_set_user(uint32_t state) {
    460   switch (biton32(state)) {
    461     case 1:
    462       active_layer = 1;
    463       break;
    464     case 2:
    465       active_layer = 2;
    466       break;
    467     case 3:
    468       active_layer = 3;
    469       break;
    470     default:
    471       active_layer = 0;
    472       break;
    473   }
    474   return state;
    475 }
    476 
    477 //Determine the current tap dance state
    478 int cur_dance (qk_tap_dance_state_t *state) {
    479   if (state->count == 1) {
    480     if (!state->pressed) {return SINGLE_TAP;}
    481     else return SINGLE_HOLD;
    482   } else if (state->count == 2) {return DOUBLE_TAP;}
    483   else return 8;
    484 }
    485 
    486 //Initialize tap structure associated with example tap dance key
    487 static tap ql_tap_state = {
    488   .is_press_action = true,
    489   .state = 0
    490 };
    491 
    492 //Functions that control what our tap dance key does
    493 void ql_finished (qk_tap_dance_state_t *state, void *user_data) {
    494   ql_tap_state.state = cur_dance(state);
    495   switch (ql_tap_state.state) {
    496     case SINGLE_TAP: tap_code(KC_QUOT); break;
    497     case SINGLE_HOLD: layer_on(_MY_LAYER); break;
    498     case DOUBLE_TAP: 
    499       if (active_layer==_MY_LAYER) {layer_off(_MY_LAYER);}
    500       else layer_on(_MY_LAYER);
    501   }
    502 }
    503 
    504 void ql_reset (qk_tap_dance_state_t *state, void *user_data) {
    505   if (ql_tap_state.state==SINGLE_HOLD) {layer_off(_MY_LAYER);}
    506   ql_tap_state.state = 0;
    507 }
    508 
    509 //Associate our tap dance key with its functionality
    510 qk_tap_dance_action_t tap_dance_actions[] = {
    511   [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
    512 };
    513 ```
    514 
    515 The is where the real logic of our tap dance key gets worked out. Since `layer_state_set_user()` is called on any layer switch, we use it to update `active_layer`. Our example is assuming that your `keymap.c` includes 4 layers, so adjust the switch statement here to fit your actual number of layers.
    516 
    517 The use of `cur_dance()` and `ql_tap_state` mirrors the above examples.
    518 
    519 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)`.
    520 
    521 `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.
    522 
    523 Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`.