# Tap Dance: A single key can do 3, 5, or 100 different things
+<!-- FIXME: Break this up into multiple sections -->
+
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.
But lets start with how to use it, first!
-First, you will need `TAP_DANCE_ENABLE=yes` in your `Makefile`, 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.
+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.
This array specifies what actions shall be taken when a tap-dance key is in action. Currently, there are three possible options:
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
+
+## Simple Example
Here's a simple example for a single definition:
-1. In your `makefile`, add `TAP_DANCE_ENABLE = yes`
+1. In your `rules.mk`, add `TAP_DANCE_ENABLE = yes`
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`
3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
TD(TD_ESC_CAPS)
```
-Here's a more complex example involving custom actions:
+## Complex Examples
+
+This section details several complex tap dance examples.
+All the enums used in the examples are declared like this:
```c
+// Enums defined for all examples:
enum {
CT_SE = 0,
CT_CLN,
CT_EGG,
CT_FLSH,
+ X_TAP_DANCE
};
-
-/* Have the above three on the keymap, TD(CT_SE), etc... */
-
+```
+### Example 1: Send `:` on single tap, `;` on double tap
+```c
void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
if (state->count == 1) {
register_code (KC_RSFT);
}
}
+//All tap dance functions would go here. Only showing this one.
+qk_tap_dance_action_t tap_dance_actions[] = {
+ [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
+};
+```
+### Example 2: Send "Safety Dance!" after 100 taps
+```c
void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
if (state->count >= 100) {
SEND_STRING ("Safety dance!");
}
}
+qk_tap_dance_action_t tap_dance_actions[] = {
+ [CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
+};
+```
+
+### Example 3: Turn LED lights on then off, one at a time
+
+```c
// on each tap, light up one led, 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 *user_data) {
ergodox_right_led_3_off();
}
+//All tap dances now put together. Example 3 is "CT_FLASH"
qk_tap_dance_action_t tap_dance_actions[] = {
[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_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
};
```
+
+### Example 4: 'Quad Function Tap-Dance'
+
+By [DanielGGordon](https://github.com/danielggordon)
+
+Allow one key to have 4 (or more) functions, depending on number of presses, and if the key is held or tapped.
+Below is a specific example:
+* Tap = Send `x`
+* Hold = Send `Control`
+* Double Tap = Send `Escape`
+* Double Tap and Hold = Send `Alt`
+
+The following example can be easily expanded to more than 4 quite easily:
+```c
+//**************** Definitions needed for quad function to work *********************//
+//Enums used to clearly convey the state of the tap dance
+enum {
+ SINGLE_TAP = 1,
+ SINGLE_HOLD = 2,
+ DOUBLE_TAP = 3,
+ DOUBLE_HOLD = 4,
+ DOUBLE_SINGLE_TAP = 5 //send SINGLE_TAP twice - NOT DOUBLE_TAP
+ // Add more enums here if you want for triple, quadruple, etc.
+};
+
+typedef struct {
+ bool is_press_action;
+ int state;
+} tap;
+
+int cur_dance (qk_tap_dance_state_t *state) {
+ if (state->count == 1) {
+ //If count = 1, and it has been interrupted - it doesn't matter if it is pressed or not: Send SINGLE_TAP
+ if (state->interrupted || state->!pressed) return SINGLE_TAP;
+ else return SINGLE_HOLD;
+ }
+ //If count = 2, and it has been interrupted - assume that user is trying to type the letter associated
+ //with single tap. In example below, that means to send `xx` instead of `Escape`.
+ else if (state->count = 2) {
+ if (state->interrupted) return DOUBLE_SINGLE_TAP;
+ else if (state->pressed) return DOUBLE_HOLD;
+ else return DOUBLE_TAP;
+ }
+ else return 6; //magic number. At some point this method will expand to work for more presses
+}
+
+//**************** Definitions needed for quad function to work *********************//
+
+//instanalize an instance of 'tap' for the 'x' tap dance.
+static tap xtap_state = {
+ .is_press_action = true,
+ .state = 0
+};
+
+void x_finished (qk_tap_dance_state_t *state, void *user_data) {
+ xtap_state.state = cur_dance(state);
+ switch (xtap_state.state) {
+ case SINGLE_TAP: register_code(KC_X); break;
+ case SINGLE_HOLD: register_code(KC_LCTRL); break;
+ case DOUBLE_TAP: register_code(KC_ESC); 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`:
+ //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.
+ }
+}
+
+void x_reset (qk_tap_dance_state_t *state, void *user_data) {
+ switch (xtap_state.state) {
+ case SINGLE_TAP: unregister_code(KC_X); break;
+ case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
+ case DOUBLE_TAP: unregister_code(KC_ESC); break;
+ case DOUBLE_HOLD: unregister_code(KC_LALT);
+ case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
+ }
+ xtap_state.state = 0;
+}
+```
+And then simply add this to your list of tap dance functions:
+`[X_TAP_DANCE] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset)`
projects / qmk_firmware.git / blobdiff