docs/feature_leader_key.md

   1 # The Leader Key: A New Kind of Modifier
   2
   3 If you've ever used Vim, you know what a Leader key is. If not, you're about to discover a wonderful concept. :) Instead of hitting Alt+Shift+W for example (holding down three keys at the same time), what if you could hit a _sequence_ of keys instead? So you'd hit our special modifier (the Leader key), followed by W and then C (just a rapid succession of keys), and something would happen.
   4
   5 That's what `KC_LEAD` does. Here's an example:
   6
   7 1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
   8 2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key.  Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence.  The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low. .
   9    * By default, this timeout is how long after pressing `KC_LEAD` to complete your entire sequence. This may be very low for some people. So you may want to increase this timeout.  Optionally, you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.  This allows you to maintain a low value here, but still be able to use the longer sequences.   To enable this option, add `#define LEADER_PER_KEY_TIMING` to your `config.h`.
  10 3. Within your `matrix_scan_user` function, add something like this:
  11
  12 ```c
  13 LEADER_EXTERNS();
  14
  15 void matrix_scan_user(void) {
  16   LEADER_DICTIONARY() {
  17     leading = false;
  18     leader_end();
  19
  20     SEQ_ONE_KEY(KC_F) {
  21       // Anything you can do in a macro.
  22       SEND_STRING("QMK is awesome.");
  23     }
  24     SEQ_TWO_KEYS(KC_D, KC_D) {
  25       SEND_STRING(SS_LCTRL("a")SS_LCTRL("c"));
  26     }
  27     SEQ_THREE_KEYS(KC_D, KC_D, KC_S) {
  28       SEND_STRING("https://start.duckduckgo.com"SS_TAP(X_ENTER));
  29     }
  30     SEQ_TWO_KEYS(KC_A, KC_S) {
  31       register_code(KC_LGUI);
  32       register_code(KC_S);
  33       unregister_code(KC_S);
  34       unregister_code(KC_LGUI);
  35     }
  36   }
  37 }
  38 ```
  39
  40 As you can see, you have a few function. You can use `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS`, `SEQ_THREE_KEYS` up to `SEQ_FIVE_KEYS` for longer sequences.
  41
  42 Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously.
  43
  44 ## Adding Leader Key Support in the `rules.mk`
  45
  46 To add support for Leader Key you simply need to add a single line to your keymap's `rules.mk`:
  47
  48 ```make
  49 LEADER_ENABLE = yes
  50 ```
  51
  52 ## Per Key Timing on Leader keys
  53
  54 Rather than relying on an incredibly high timeout for long leader key strings or those of us without 200wpm typing skills, we can enable per key timing to ensure that each key pressed provides us with more time to finish our stroke. This is incredibly helpful with leader key emulation of tap dance (read: multiple taps of the same key like C, C, C).
  55
  56 In order to enable this, place this in your `config.h`:
  57 ```c
  58 #define LEADER_PER_KEY_TIMING
  59 ```
  60
  61 After this, it's recommended that you lower your `LEADER_TIMEOUT` to something less that 300ms.
  62
  63 ```c
  64 #define LEADER_TIMEOUT 250
  65 ```
  66
  67 Now, something like this won't seem impossible to do without a 1000MS leader key timeout:
  68
  69 ```c
  70 SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
  71   SEND_STRING("Per key timing is great!!!");
  72 }
  73 ```
  74
  75 ## Strict Key Processing
  76
  77 By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](feature_advanced_keycodes.md#mod-tap) and [`Layer Tap`](feature_advanced_keycodes.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
  78
  79 While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file.  This well then disable the filtering, and you'll need to specify the whole keycode.
  80
  81 ## Customization
  82
  83 The Leader Key feature has some additional customization to how the Leader Key feature works.  It has two functions that can be called at certain parts of the process.  Namely `leader_start()` and `leader_end()`.
  84
  85 The `leader_start()` function is called when you tap the `KC_LEAD` key, and the `leader_end()` function is called when either the leader sequence is completed, or the leader timeout is hit.
  86
  87 You can add these functions to your code (`keymap.c` usually) to add feedback to the Leader sequences (such as beeping or playing music).
  88
  89 ```c
  90 void leader_start(void) {
  91   // sequence started
  92 }
  93
  94 void leader_end(void) {
  95   // sequence ended (no success/failuer detection)
  96 }
  97 ```
  98
  99 ### Example
 100
 101 This example will play the Mario "One Up" sound when you hit `KC_LEAD` to start the Leader Sequence, and will play "All Star" if it completes successfully or "Rick Roll" you if it fails.
 102
 103 ```c
 104 bool did_leader_succeed;
 105 #ifdef AUDIO_ENABLE
 106 float leader_start[][2] = SONG(ONE_UP_SOUND );
 107 float leader_succeed[][2] = SONG(ALL_STAR);
 108 float leader_fail[][2] = SONG(RICK_ROLL);
 109 #endif
 110 LEADER_EXTERNS();
 111
 112 void matrix_scan_user(void) {
 113   LEADER_DICTIONARY() {
 114     did_leader_succeed = leading = false;
 115
 116     SEQ_ONE_KEY(KC_E) {
 117       // Anything you can do in a macro.
 118       SEND_STRING(SS_LCTRL(SS_LSFT("t")));
 119       did_leader_succeed = true;
 120     } else
 121     SEQ_TWO_KEYS(KC_E, KC_D) {
 122       SEND_STRING(SS_LGUI("r")"cmd"SS_TAP(KC_ENTER)SS_LCTRL("c"));
 123       did_leader_succeed = true;
 124     }
 125     leader_end();
 126   }
 127 }
 128
 129 void leader_start(void) {
 130 #ifdef AUDIO_ENABLE
 131     PLAY_SONG(leader_start);
 132 #endif
 133 }
 134
 135 void leader_end(void) {
 136   if (did_leader_succeed) {
 137 #ifdef AUDIO_ENABLE
 138     PLAY_SONG(leader_succeed);
 139 #endif
 140   } else {
 141 #ifdef AUDIO_ENABLE
 142     PLAY_SONG(leader_fail);
 143 #endif
 144   }
 145 }
 146 ```