ahoneybun/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More Tap Dance docs improvements (#12358)

Browse source
This commit is contained in:
Ryan 2021-03-25 06:46:22 +11:00 • committed by GitHub
parent b7870ae78c
commit 653ecf91c2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 84 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

162
docs/feature_tap_dance.md
View file

@ -76,7 +76,7 @@ qk_tap_dance_action_t tap_dance_actions[] = {
[TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS), [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS),
}; };
// Add tap dance item in place of a key code // Add tap dance item to your keymap in place of a keycode
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
// ... // ...
TD(TD_ESC_CAPS) TD(TD_ESC_CAPS)
@ -206,20 +206,22 @@ 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 enum {
TD_NONE,
TD_UNKNOWN,
TD_SINGLE_TAP,
TD_SINGLE_HOLD,
TD_DOUBLE_TAP,
TD_DOUBLE_HOLD,
TD_DOUBLE_SINGLE_TAP, // Send two single taps
TD_TRIPLE_TAP,
TD_TRIPLE_HOLD
} td_state_t;
typedef struct { typedef struct {
bool is_press_action; bool is_press_action;
uint8_t state; td_state_t state;
} tap; } td_tap_t;
enum {
SINGLE_TAP = 1,
SINGLE_HOLD,
DOUBLE_TAP,
DOUBLE_HOLD,
DOUBLE_SINGLE_TAP, // Send two single taps
TRIPLE_TAP,
TRIPLE_HOLD
};
// Tap dance enums // Tap dance enums
enum { enum {
@ -227,7 +229,7 @@ enum {
SOME_OTHER_DANCE SOME_OTHER_DANCE
}; };
uint8_t cur_dance(qk_tap_dance_state_t *state); td_state_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 // 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_finished(qk_tap_dance_state_t *state, void *user_data);
@ -261,61 +263,61 @@ Now, at the bottom of your `keymap.c` file, you'll need to add the following:
* Letters used in common words as a double. For example 'p' in 'pepper'. If a tap dance function existed on the * Letters used in common words as a double. For example 'p' in 'pepper'. If a tap dance function existed on the
* letter 'p', the word 'pepper' would be quite frustating to type. * letter 'p', the word 'pepper' would be quite frustating to type.
* *
* 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 'TD_DOUBLE_SINGLE_TAP', however this is not fully tested
* *
*/ */
uint8_t cur_dance(qk_tap_dance_state_t *state) { td_state_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 TD_SINGLE_TAP;
// Key has not been interrupted, but the 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 TD_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 // TD_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 // action when hitting 'pp'. Suggested use case for this return value is when you want to send two
// keystrokes of the key, and not the 'double tap' action/macro. // keystrokes of the key, and not the 'double tap' action/macro.
if (state->interrupted) return DOUBLE_SINGLE_TAP; if (state->interrupted) return TD_DOUBLE_SINGLE_TAP;
else if (state->pressed) return DOUBLE_HOLD; else if (state->pressed) return TD_DOUBLE_HOLD;
else return DOUBLE_TAP; else return TD_DOUBLE_TAP;
} }
// Assumes no one is trying to type the same letter three times (at least not quickly). // 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 // If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add
// an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP' // an exception here to return a 'TD_TRIPLE_SINGLE_TAP', and define that enum just like 'TD_DOUBLE_SINGLE_TAP'
if (state->count == 3) { if (state->count == 3) {
if (state->interrupted || !state->pressed) return TRIPLE_TAP; if (state->interrupted || !state->pressed) return TD_TRIPLE_TAP;
else return TRIPLE_HOLD; else return TD_TRIPLE_HOLD;
} else return 8; // Magic number. At some point this method will expand to work for more presses } else return TD_UNKNOWN;
} }
// Create an instance of 'tap' for the 'x' tap dance. // Create an instance of 'td_tap_t' for the 'x' tap dance.
static tap xtap_state = { static td_tap_t xtap_state = {
.is_press_action = true, .is_press_action = true,
.state = 0 .state = TD_NONE
}; };
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 TD_SINGLE_TAP: register_code(KC_X); break;
case SINGLE_HOLD: register_code(KC_LCTRL); break; case TD_SINGLE_HOLD: register_code(KC_LCTRL); break;
case DOUBLE_TAP: register_code(KC_ESC); break; case TD_DOUBLE_TAP: register_code(KC_ESC); break;
case DOUBLE_HOLD: register_code(KC_LALT); break; case TD_DOUBLE_HOLD: register_code(KC_LALT); break;
// 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); case TD_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 TD_SINGLE_TAP: unregister_code(KC_X); break;
case SINGLE_HOLD: unregister_code(KC_LCTRL); break; case TD_SINGLE_HOLD: unregister_code(KC_LCTRL); break;
case DOUBLE_TAP: unregister_code(KC_ESC); break; case TD_DOUBLE_TAP: unregister_code(KC_ESC); break;
case DOUBLE_HOLD: unregister_code(KC_LALT); case TD_DOUBLE_HOLD: unregister_code(KC_LALT);
case DOUBLE_SINGLE_TAP: unregister_code(KC_X); case TD_DOUBLE_SINGLE_TAP: unregister_code(KC_X);
} }
xtap_state.state = 0; xtap_state.state = TD_NONE;
} }
qk_tap_dance_action_t tap_dance_actions[] = { qk_tap_dance_action_t tap_dance_actions[] = {
@ -343,9 +345,11 @@ enum td_keycodes {
// 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, TD_NONE,
SINGLE_HOLD, TD_UNKNOWN,
DOUBLE_SINGLE_TAP TD_SINGLE_TAP,
TD_SINGLE_HOLD,
TD_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
@ -354,7 +358,7 @@ 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
uint8_t cur_dance(qk_tap_dance_state_t *state); td_state_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);
@ -365,14 +369,14 @@ Below your `LAYOUT`, define each of the tapdance functions:
```c ```c
// Determine the tapdance state to return // Determine the tapdance state to return
uint8_t cur_dance(qk_tap_dance_state_t *state) { td_state_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 TD_SINGLE_TAP;
else return SINGLE_HOLD; else return TD_SINGLE_HOLD;
} }
if (state->count == 2) return DOUBLE_SINGLE_TAP; if (state->count == 2) return TD_DOUBLE_SINGLE_TAP;
else return 3; // Any number higher than the maximum state value you return above else return TD_UNKNOWN; // Any number higher than the maximum state value you return above
} }
// Handle the possible states for each tapdance keycode you define: // Handle the possible states for each tapdance keycode you define:
@ -380,13 +384,13 @@ uint8_t cur_dance(qk_tap_dance_state_t *state) {
void altlp_finished(qk_tap_dance_state_t *state, void *user_data) { void altlp_finished(qk_tap_dance_state_t *state, void *user_data) {
td_state = cur_dance(state); td_state = cur_dance(state);
switch (td_state) { switch (td_state) {
case SINGLE_TAP: case TD_SINGLE_TAP:
register_code16(KC_LPRN); register_code16(KC_LPRN);
break; break;
case SINGLE_HOLD: case TD_SINGLE_HOLD:
register_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_on(_MY_LAYER)` here register_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_on(_MY_LAYER)` here
break; break;
case DOUBLE_SINGLE_TAP: // Allow nesting of 2 parens `((` within tapping term case TD_DOUBLE_SINGLE_TAP: // Allow nesting of 2 parens `((` within tapping term
tap_code16(KC_LPRN); tap_code16(KC_LPRN);
register_code16(KC_LPRN); register_code16(KC_LPRN);
} }
@ -394,13 +398,13 @@ 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) {
switch (td_state) { switch (td_state) {
case SINGLE_TAP: case TD_SINGLE_TAP:
unregister_code16(KC_LPRN); unregister_code16(KC_LPRN);
break; break;
case SINGLE_HOLD: case TD_SINGLE_HOLD:
unregister_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_off(_MY_LAYER)` here unregister_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_off(_MY_LAYER)` here
break; break;
case DOUBLE_SINGLE_TAP: case TD_DOUBLE_SINGLE_TAP:
unregister_code16(KC_LPRN); unregister_code16(KC_LPRN);
} }
} }
@ -420,17 +424,19 @@ Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this e
The first step is to include the following code towards the beginning of your `keymap.c`: The first step is to include the following code towards the beginning of your `keymap.c`:
```c ```c
// Define a type for as many tap dance states as you need
typedef enum {
TD_NONE,
TD_UNKNOWN,
TD_SINGLE_TAP,
TD_SINGLE_HOLD,
TD_DOUBLE_TAP
} td_state_t;
typedef struct { typedef struct {
bool is_press_action; bool is_press_action;
uint8_t state; td_state_t state;
} tap; } td_tap_t;
// Define a type for as many tap dance states as you need
enum {
SINGLE_TAP = 1,
SINGLE_HOLD,
DOUBLE_TAP
};
enum { enum {
QUOT_LAYR, // 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
@ -439,7 +445,7 @@ 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
uint8_t cur_dance(qk_tap_dance_state_t *state); td_state_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);
@ -450,31 +456,31 @@ 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
uint8_t cur_dance(qk_tap_dance_state_t *state) { td_state_t cur_dance(qk_tap_dance_state_t *state) {
if (state->count == 1) { if (state->count == 1) {
if (!state->pressed) return SINGLE_TAP; if (!state->pressed) return TD_SINGLE_TAP;
else return SINGLE_HOLD; else return TD_SINGLE_HOLD;
} else if (state->count == 2) return DOUBLE_TAP; } else if (state->count == 2) return TD_DOUBLE_TAP;
else return 8; else return TD_UNKNOWN;
} }
// Initialize tap structure associated with example tap dance key // Initialize tap structure associated with example tap dance key
static tap ql_tap_state = { static td_tap_t ql_tap_state = {
.is_press_action = true, .is_press_action = true,
.state = 0 .state = TD_NONE
}; };
// 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 TD_SINGLE_TAP:
tap_code(KC_QUOT); tap_code(KC_QUOT);
break; break;
case SINGLE_HOLD: case TD_SINGLE_HOLD:
layer_on(_MY_LAYER); layer_on(_MY_LAYER);
break; break;
case DOUBLE_TAP: case TD_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
@ -489,10 +495,10 @@ 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) {
// If the key was held down and now is released then switch off the layer // If the key was held down and now is released then switch off the layer
if (ql_tap_state.state == SINGLE_HOLD) { if (ql_tap_state.state == TD_SINGLE_HOLD) {
layer_off(_MY_LAYER); layer_off(_MY_LAYER);
} }
ql_tap_state.state = 0; ql_tap_state.state = TD_NONE;
} }
// Associate our tap dance key with its functionality // Associate our tap dance key with its functionality
@ -505,7 +511,7 @@ The above code is similar to that used in previous examples. The one point to no
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 `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)`. The `case: TD_SINGLE_TAP` in `ql_finished` is similar to the above examples. The `TD_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 `TD_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.