docs/feature_tap_dance.md

   1 # Tap Dance: A single key can do 3, 5, or 100 different things
   2
   3 <!-- FIXME: Break this up into multiple sections -->
   4
   5 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:
   6
   7 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.
   8
   9 To make it clear how this is different from `ACTION_FUNCTION_TAP`, lets 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 send first. Thus, `SPC a` will result in `a SPC` being sent, if they are typed within `TAPPING_TERM`. With the tap dance feature, that'll come out as `SPC a`, correctly.
  12
  13 The implementation hooks into two parts of the system, to achieve this: into `process_record_quantum()`, and the matrix scan. We need the latter to be able to time out a tap sequence even when a key is not being pressed, so `SPC` alone will time out and register after `TAPPING_TERM` time.
  14
  15 But lets start with how to use it, first!
  16
  17 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. 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.
  18
  19 This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options:
  20
  21 * `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.
  22 * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
  23 * `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 on when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
  24
  25 The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise.
  26
  27 And that's the bulk of it!
  28
  29 And now, on to the explanation of how it works!
  30
  31 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.
  32
  33 This means that you have `TAPPING_TERM` time to tap the key again, you do not have to input all the taps within that timeframe. This allows for longer tap counts, with minimal impact on responsiveness.
  34
  35 Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-dance keys.
  36
  37 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.
  38
  39 # Examples
  40
  41 ## Simple Example
  42
  43 Here's a simple example for a single definition:
  44
  45 1. In your `rules.mk`, add `TAP_DANCE_ENABLE = yes`
  46 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`
  47 3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
  48
  49 ```c
  50 //Tap Dance Declarations
  51 enum {
  52   TD_ESC_CAPS = 0
  53 };
  54
  55 //Tap Dance Definitions
  56 qk_tap_dance_action_t tap_dance_actions[] = {
  57   //Tap once for Esc, twice for Caps Lock
  58   [TD_ESC_CAPS]  = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS)
  59 // Other declarations would go here, separated by commas, if you have them
  60 };
  61
  62 //In Layer declaration, add tap dance item in place of a key code
  63 TD(TD_ESC_CAPS)
  64 ```
  65
  66 ## Complex Examples
  67
  68 This section details several complex tap dance examples.
  69 All the enums used in the examples are declared like this:
  70
  71 ```c
  72 // Enums defined for all examples:
  73 enum {
  74  CT_SE = 0,
  75  CT_CLN,
  76  CT_EGG,
  77  CT_FLSH,
  78  X_TAP_DANCE
  79 };
  80 ```
  81 ### Example 1: Send `:` on single tap, `;` on double tap
  82 ```c
  83 void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
  84   if (state->count == 1) {
  85     register_code (KC_RSFT);
  86     register_code (KC_SCLN);
  87   } else {
  88     register_code (KC_SCLN);
  89   }
  90 }
  91
  92 void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
  93   if (state->count == 1) {
  94     unregister_code (KC_RSFT);
  95     unregister_code (KC_SCLN);
  96   } else {
  97     unregister_code (KC_SCLN);
  98   }
  99 }
 100
 101 //All tap dance functions would go here. Only showing this one.
 102 qk_tap_dance_action_t tap_dance_actions[] = {
 103  [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
 104 };
 105 ```
 106 ### Example 2: Send "Safety Dance!" after 100 taps
 107 ```c
 108 void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
 109   if (state->count >= 100) {
 110     SEND_STRING ("Safety dance!");
 111     reset_tap_dance (state);
 112   }
 113 }
 114
 115 qk_tap_dance_action_t tap_dance_actions[] = {
 116  [CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
 117 };
 118 ```
 119
 120 ### Example 3: Turn LED lights on then off, one at a time
 121
 122 ```c
 123 // on each tap, light up one led, from right to left
 124 // on the forth tap, turn them off from right to left
 125 void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
 126   switch (state->count) {
 127   case 1:
 128     ergodox_right_led_3_on();
 129     break;
 130   case 2:
 131     ergodox_right_led_2_on();
 132     break;
 133   case 3:
 134     ergodox_right_led_1_on();
 135     break;
 136   case 4:
 137     ergodox_right_led_3_off();
 138     _delay_ms(50);
 139     ergodox_right_led_2_off();
 140     _delay_ms(50);
 141     ergodox_right_led_1_off();
 142   }
 143 }
 144
 145 // on the fourth tap, set the keyboard on flash state
 146 void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
 147   if (state->count >= 4) {
 148     reset_keyboard();
 149     reset_tap_dance(state);
 150   }
 151 }
 152
 153 // if the flash state didnt happen, then turn off leds, left to right
 154 void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
 155   ergodox_right_led_1_off();
 156   _delay_ms(50);
 157   ergodox_right_led_2_off();
 158   _delay_ms(50);
 159   ergodox_right_led_3_off();
 160 }
 161
 162 //All tap dances now put together. Example 3 is "CT_FLASH"
 163 qk_tap_dance_action_t tap_dance_actions[] = {
 164   [CT_SE]  = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
 165  ,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
 166  ,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
 167  ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
 168 };
 169 ```
 170
 171 ### Example 4: 'Quad Function Tap-Dance'
 172
 173 By [DanielGGordon](https://github.com/danielggordon)
 174
 175 Allow one key to have 4 (or more) functions, depending on number of presses, and if the key is held or tapped.
 176 Below is a specific example:
 177 *  Tap = Send `x`
 178 *  Hold = Send `Control`
 179 *  Double Tap = Send `Escape`
 180 *  Double Tap and Hold = Send `Alt`
 181
 182 The following example can be easily expanded to more than 4 quite easily:
 183 ```c
 184 //**************** Definitions needed for quad function to work *********************//
 185 //Enums used to clearly convey the state of the tap dance
 186 enum {
 187   SINGLE_TAP = 1,
 188   SINGLE_HOLD = 2,
 189   DOUBLE_TAP = 3,
 190   DOUBLE_HOLD = 4,
 191   DOUBLE_SINGLE_TAP = 5 //send SINGLE_TAP twice - NOT DOUBLE_TAP
 192   // Add more enums here if you want for triple, quadruple, etc.
 193 };
 194
 195 typedef struct {
 196   bool is_press_action;
 197   int state;
 198 } tap;
 199
 200 int cur_dance (qk_tap_dance_state_t *state) {
 201   if (state->count == 1) {
 202     //If count = 1, and it has been interrupted - it doesn't matter if it is pressed or not: Send SINGLE_TAP
 203     if (state->interrupted || state->pressed==0) return SINGLE_TAP;
 204     else return SINGLE_HOLD;
 205   }
 206   //If count = 2, and it has been interrupted - assume that user is trying to type the letter associated
 207   //with single tap. In example below, that means to send `xx` instead of `Escape`.
 208   else if (state->count == 2) {
 209     if (state->interrupted) return DOUBLE_SINGLE_TAP;
 210     else if (state->pressed) return DOUBLE_HOLD;
 211     else return DOUBLE_TAP;
 212   }
 213   else return 6; //magic number. At some point this method will expand to work for more presses
 214 }
 215
 216 //**************** Definitions needed for quad function to work *********************//
 217
 218 //instanalize an instance of 'tap' for the 'x' tap dance.
 219 static tap xtap_state = {
 220   .is_press_action = true,
 221   .state = 0
 222 };
 223
 224 void x_finished (qk_tap_dance_state_t *state, void *user_data) {
 225   xtap_state.state = cur_dance(state);
 226   switch (xtap_state.state) {
 227     case SINGLE_TAP: register_code(KC_X); break;
 228     case SINGLE_HOLD: register_code(KC_LCTRL); break;
 229     case DOUBLE_TAP: register_code(KC_ESC); break;
 230     case DOUBLE_HOLD: register_code(KC_LALT); break;
 231     case DOUBLE_SINGLE_TAP: register_code(KC_X); unregister_code(KC_X); register_code(KC_X);
 232     //Last case is for fast typing. Assuming your key is `f`:
 233     //For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`.
 234     //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.
 235   }
 236 }
 237
 238 void x_reset (qk_tap_dance_state_t *state, void *user_data) {
 239   switch (xtap_state.state) {
 240     case SINGLE_TAP: unregister_code(KC_X); break;
 241     case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
 242     case DOUBLE_TAP: unregister_code(KC_ESC); break;
 243     case DOUBLE_HOLD: unregister_code(KC_LALT);
 244     case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
 245   }
 246   xtap_state.state = 0;
 247 }
 248 ```
 249 And then simply add this to your list of tap dance functions:
 250 `[X_TAP_DANCE] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset)`