leader_key.md (9484B)
1 # The Leader Key: A New Kind of Modifier {#the-leader-key} 2 3 If you're a Vim user, you probably know what a Leader key is. In contrast to [Combos](combo), the Leader key allows you to hit a *sequence* of up to five keys instead, which triggers some custom functionality once complete. 4 5 ## Usage {#usage} 6 7 Add the following to your `rules.mk`: 8 9 ```make 10 LEADER_ENABLE = yes 11 ``` 12 13 Then add the `QK_LEAD` keycode to your keymap. 14 15 ## Callbacks {#callbacks} 16 17 These callbacks are invoked when the leader sequence begins and ends. In the latter you can implement your custom functionality based on the contents of the sequence buffer. 18 19 ```c 20 void leader_start_user(void) { 21 // Do something when the leader key is pressed 22 } 23 24 void leader_end_user(void) { 25 if (leader_sequence_one_key(KC_F)) { 26 // Leader, f => Types the below string 27 SEND_STRING("QMK is awesome."); 28 } else if (leader_sequence_two_keys(KC_D, KC_D)) { 29 // Leader, d, d => Ctrl+A, Ctrl+C 30 SEND_STRING(SS_LCTL("a") SS_LCTL("c")); 31 } else if (leader_sequence_three_keys(KC_D, KC_D, KC_S)) { 32 // Leader, d, d, s => Types the below string 33 SEND_STRING("https://start.duckduckgo.com\n"); 34 } else if (leader_sequence_two_keys(KC_A, KC_S)) { 35 // Leader, a, s => GUI+S 36 tap_code16(LGUI(KC_S)); 37 } 38 } 39 ``` 40 41 ## Basic Configuration {#basic-configuration} 42 43 ### Timeout {#timeout} 44 45 This is the amount of time you have to complete a sequence once the leader key has been pressed. The default value is 300 milliseconds, but you can change this by adding the following to your `config.h`: 46 47 ```c 48 #define LEADER_TIMEOUT 350 49 ``` 50 51 ### Per-Key Timeout {#per-key-timeout} 52 53 Rather than relying on an incredibly high timeout for long leader key strings or those of us without 200 wpm typing skills, you can enable per-key timing to ensure that each key pressed provides you with more time to finish the sequence. This is incredibly helpful with leader key emulation of tap dance (such as multiple taps of the same key like C, C, C). 54 55 To enable this, add the following to your `config.h`: 56 57 ```c 58 #define LEADER_PER_KEY_TIMING 59 ``` 60 61 After this, it's recommended that you lower your timeout below 300 ms: 62 63 ```c 64 #define LEADER_TIMEOUT 250 65 ``` 66 67 Now, something like this won't seem impossible to do without a 1000 millisecond timeout: 68 69 ```c 70 if (leader_sequence_three_keys(KC_C, KC_C, KC_C)) { 71 SEND_STRING("Per key timing is great!!!"); 72 } 73 ``` 74 75 ### Disabling Initial Timeout {#disabling-initial-timeout} 76 77 Sometimes your leader key may be too far away from the rest of the keys in the sequence. Imagine that your leader key is one of your outer top right keys - you may need to reposition your hand just to reach your leader key. This can make typing the entire sequence on time hard difficult if you are able to type most of the sequence fast. For example, if your sequence is `Leader + asd`, typing `asd` fast is very easy once you have your hands in your home row, but starting the sequence in time after moving your hand out of the home row to reach the leader key and back is not. 78 79 To remove the stress this situation produces to your hands, you can disable the timeout just for the leader key. Add the following to your `config.h`: 80 81 ```c 82 #define LEADER_NO_TIMEOUT 83 ``` 84 85 Now, after you hit the leader key, you will have an infinite amount of time to start the rest of the sequence, allowing you to properly position your hands to type the rest of the sequence comfortably. This way you can configure a very short `LEADER_TIMEOUT`, but still have plenty of time to position your hands. 86 87 ### Strict Key Processing {#strict-key-processing} 88 89 By default, only the "tap keycode" portions of [Mod-Taps](../mod_tap) and [Layer Taps](../feature_layers#switching-and-toggling-layers) are added to the sequence buffer. This means if you press eg. `LT(3, KC_A)` as part of a sequence, `KC_A` will be added to the buffer, rather than the entire `LT(3, KC_A)` keycode. 90 91 This gives a more expected behaviour for most users, however you may want to change this. 92 93 To enable this, add the following to your `config.h`: 94 95 ```c 96 #define LEADER_KEY_STRICT_KEY_PROCESSING 97 ``` 98 99 ## Example {#example} 100 101 This example will play the Mario "One Up" sound when you hit `QK_LEAD` to start the leader sequence. When the sequence ends, it will play "All Star" if it completes successfully or "Rick Roll" you if it fails (in other words, no sequence matched). 102 103 ```c 104 #ifdef AUDIO_ENABLE 105 float leader_start_song[][2] = SONG(ONE_UP_SOUND); 106 float leader_succeed_song[][2] = SONG(ALL_STAR); 107 float leader_fail_song[][2] = SONG(RICK_ROLL); 108 #endif 109 110 void leader_start_user(void) { 111 #ifdef AUDIO_ENABLE 112 PLAY_SONG(leader_start_song); 113 #endif 114 } 115 116 void leader_end_user(void) { 117 bool did_leader_succeed = false; 118 119 if (leader_sequence_one_key(KC_E)) { 120 SEND_STRING(SS_LCTL(SS_LSFT("t"))); 121 did_leader_succeed = true; 122 } else if (leader_sequence_two_keys(KC_E, KC_D)) { 123 SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c")); 124 did_leader_succeed = true; 125 } 126 127 #ifdef AUDIO_ENABLE 128 if (did_leader_succeed) { 129 PLAY_SONG(leader_succeed_song); 130 } else { 131 PLAY_SONG(leader_fail_song); 132 } 133 #endif 134 } 135 ``` 136 137 ## Keycodes {#keycodes} 138 139 |Key |Aliases |Description | 140 |-----------------------|---------|-------------------------| 141 |`QK_LEADER` |`QK_LEAD`|Begin the leader sequence| 142 143 ## API {#api} 144 145 ### `void leader_start_user(void)` {#api-leader-start-user} 146 147 User callback, invoked when the leader sequence begins. 148 149 --- 150 151 ### `void leader_end_user(void)` {#api-leader-end-user} 152 153 User callback, invoked when the leader sequence ends. 154 155 --- 156 157 ### `bool leader_add_user(uint16_t keycode)` {#api-leader-add-user} 158 159 User callback, invoked when a keycode is added to the leader sequence. 160 161 #### Arguments {#api-leader-add-user-arguments} 162 163 - `uint16_t keycode` 164 The keycode to added to the leader sequence. 165 166 #### Return Value {#api-leader-add-user-return} 167 168 `true` to finish the key sequence, `false` to continue. 169 170 --- 171 172 ### `void leader_start(void)` {#api-leader-start} 173 174 Begin the leader sequence, resetting the buffer and timer. 175 176 --- 177 178 ### `void leader_end(void)` {#api-leader-end} 179 180 End the leader sequence. 181 182 --- 183 184 ### `bool leader_sequence_active(void)` {#api-leader-sequence-active} 185 186 Whether the leader sequence is active. 187 188 --- 189 190 ### `bool leader_sequence_add(uint16_t keycode)` {#api-leader-sequence-add} 191 192 Add the given keycode to the sequence buffer. 193 194 If `LEADER_NO_TIMEOUT` is defined, the timer is reset if the buffer is empty. 195 196 #### Arguments {#api-leader-sequence-add-arguments} 197 198 - `uint16_t keycode` 199 The keycode to add. 200 201 #### Return Value {#api-leader-sequence-add-return} 202 203 `true` if the keycode was added, `false` if the buffer is full. 204 205 --- 206 207 ### `bool leader_sequence_timed_out(void)` {#api-leader-sequence-timed-out} 208 209 Whether the leader sequence has reached the timeout. 210 211 If `LEADER_NO_TIMEOUT` is defined, the buffer must also contain at least one key. 212 213 --- 214 215 ### `bool leader_reset_timer(void)` {#api-leader-reset-timer} 216 217 Reset the leader sequence timer. 218 219 --- 220 221 ### `bool leader_sequence_one_key(uint16_t kc)` {#api-leader-sequence-one-key} 222 223 Check the sequence buffer for the given keycode. 224 225 #### Arguments {#api-leader-sequence-one-key-arguments} 226 227 - `uint16_t kc` 228 The keycode to check. 229 230 #### Return Value {#api-leader-sequence-one-key-return} 231 232 `true` if the sequence buffer matches. 233 234 --- 235 236 ### `bool leader_sequence_two_keys(uint16_t kc1, uint16_t kc2)` {#api-leader-sequence-two-keys} 237 238 Check the sequence buffer for the given keycodes. 239 240 #### Arguments {#api-leader-sequence-two-keys-arguments} 241 242 - `uint16_t kc1` 243 The first keycode to check. 244 - `uint16_t kc2` 245 The second keycode to check. 246 247 #### Return Value {#api-leader-sequence-two-keys-return} 248 249 `true` if the sequence buffer matches. 250 251 --- 252 253 ### `bool leader_sequence_three_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3)` {#api-leader-sequence-three-keys} 254 255 Check the sequence buffer for the given keycodes. 256 257 #### Arguments {#api-leader-sequence-three-keys-arguments} 258 259 - `uint16_t kc1` 260 The first keycode to check. 261 - `uint16_t kc2` 262 The second keycode to check. 263 - `uint16_t kc3` 264 The third keycode to check. 265 266 #### Return Value {#api-leader-sequence-three-keys-return} 267 268 `true` if the sequence buffer matches. 269 270 --- 271 272 ### `bool leader_sequence_four_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3, uint16_t kc4)` {#api-leader-sequence-four-keys} 273 274 Check the sequence buffer for the given keycodes. 275 276 #### Arguments {#api-leader-sequence-four-keys-arguments} 277 278 - `uint16_t kc1` 279 The first keycode to check. 280 - `uint16_t kc2` 281 The second keycode to check. 282 - `uint16_t kc3` 283 The third keycode to check. 284 - `uint16_t kc4` 285 The fourth keycode to check. 286 287 #### Return Value {#api-leader-sequence-four-keys-return} 288 289 `true` if the sequence buffer matches. 290 291 --- 292 293 ### `bool leader_sequence_five_keys(uint16_t kc1, uint16_t kc2, uint16_t kc3, uint16_t kc4, uint16_t kc5)` {#api-leader-sequence-five-keys} 294 295 Check the sequence buffer for the given keycodes. 296 297 #### Arguments {#api-leader-sequence-five-keys-arguments} 298 299 - `uint16_t kc1` 300 The first keycode to check. 301 - `uint16_t kc2` 302 The second keycode to check. 303 - `uint16_t kc3` 304 The third keycode to check. 305 - `uint16_t kc4` 306 The fourth keycode to check. 307 - `uint16_t kc5` 308 The fifth keycode to check. 309 310 #### Return Value {#api-leader-sequence-five-keys-return} 311 312 `true` if the sequence buffer matches.