docs/feature_advanced_keycodes.md

   1 # Advanced Keycodes
   2
   3 Your keymap can include keycodes that are more advanced than normal, for example keys that switch layers or send modifiers when held, but send regular keycodes when tapped. This page documents the functions that are available to you.
   4
   5 ### Assigning Custom Names
   6
   7 People often define custom names using `#define`. For example:
   8
   9 ```c
  10 #define FN_CAPS LT(_FL, KC_CAPSLOCK)
  11 #define ALT_TAB LALT(KC_TAB)
  12 ```
  13
  14 This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
  15
  16 ### Limits of These Aliases
  17
  18 Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.md), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.md).
  19
  20 # Switching and Toggling Layers
  21
  22 These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers)
  23
  24 * `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
  25 * `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated.
  26 * `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
  27 * `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped.
  28 * `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
  29 * `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
  30 * `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
  31
  32 # Working with Layers
  33
  34 Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
  35
  36 ### Beginners
  37
  38 If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
  39
  40 * Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number).
  41 * Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
  42 * In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
  43
  44 ### Intermediate Users
  45
  46 Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
  47
  48 ### Advanced Users
  49
  50 Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
  51
  52 Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem.
  53
  54 Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
  55
  56 # Modifier Keys
  57
  58 These functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then *kc* will be sent. When released the keyup for *kc* will be sent and then the mod will be sent.
  59
  60 * `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
  61 * `RSFT(kc)` - applies right Shift to *kc*
  62 * `LCTL(kc)` - applies left Control to *kc*
  63 * `RCTL(kc)` - applies right Control to *kc*
  64 * `LALT(kc)` - applies left Alt to *kc*
  65 * `RALT(kc)` - applies right Alt to *kc*
  66 * `LGUI(kc)` - applies left GUI (command/win) to *kc*
  67 * `RGUI(kc)` - applies right GUI (command/win) to *kc*
  68 * `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
  69 * `MEH(kc)`  - applies Meh (all modifiers except Win/Cmd) to *kc*
  70 * `LCAG(kc)` - applies CtrlAltGui to *kc*
  71
  72 You can also chain these, like this:
  73
  74     LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
  75
  76 # Mod Tap
  77
  78 `MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down.
  79
  80 These are the values you can use for the `mod` in `MT()` and `OSM()`:
  81
  82   * MOD_LCTL
  83   * MOD_LSFT
  84   * MOD_LALT
  85   * MOD_LGUI
  86   * MOD_RCTL
  87   * MOD_RSFT
  88   * MOD_RALT
  89   * MOD_RGUI
  90   * MOD_HYPR
  91   * MOD_MEH
  92
  93 These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped.
  94
  95 We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
  96
  97   * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
  98   * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
  99   * `ALT_T(kc)` - is LALT when held and *kc* when tapped
 100   * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
 101   * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
 102   * `ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
 103   * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
 104   * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
 105
 106 ?> Due to the way that keycodes are structured, any modifiers specified as part of `kc`, such as `LCTL()` or `KC_LPRN`, will only activate when held instead of tapped.
 107
 108 ?> Additionally, if there is at least one right-handed modifier, any other modifiers in a chain of functions will turn into their right-handed equivalents, so it is not possible to "mix and match" the two.
 109
 110 # One Shot Keys
 111
 112 One shot keys are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys".
 113
 114 For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A character by first pressing and releasing shift, and then pressing and releasing A. Your computer will see the shift key being held the moment shift is pressed, and it will see the shift key being released immediately after A is released.
 115
 116 One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.
 117
 118 You can control the behavior of one shot keys by defining these in `config.h`:
 119
 120 ```c
 121 #define ONESHOT_TAP_TOGGLE 5  /* Tapping this number of times holds the key until tapped this number of times again. */
 122 #define ONESHOT_TIMEOUT 5000  /* Time (in ms) before the one shot key is released */
 123 ```
 124
 125 * `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
 126 * `OSL(layer)` - momentary switch to *layer*.
 127
 128 Sometimes, you want to activate a one-shot layer as part of a macro or tap dance routine. To do this, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. For more complicated actions, take a look at the oneshot implementation in [`process_record`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L429).
 129
 130 If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
 131
 132 # Permissive Hold
 133
 134 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
 135
 136 ```
 137 #define PERMISSIVE_HOLD
 138 ```
 139
 140 This makes it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.
 141
 142 Example: (Tapping Term = 200ms)
 143
 144 - SHFT_T(KC_A) Down
 145 - KC_X Down
 146 - KC_X Up
 147 - SHFT_T(KC_A) Up
 148
 149 With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
 150
 151 # Mod tap interrupt
 152
 153 When a dual role key used for a modifier is quickly followed by another keys, it is interpreted as held even before the tapping term elapsed.  This is a problem if a key is used for example inside a rolling combo because the second key will be pressed before the first key is released.
 154
 155 For example, when trying to type the rolling combo "zx" and z being configured to send Ctrl when hold, z rapidly followed by x actually sends Ctrl-x. That's bad.
 156
 157 You can disable this behavior by defining `IGNORE_MOD_TAP_INTERRUPT` in `config.h`.
 158
 159 Note that this only concerns modifiers and not layer switching keys.
 160
 161 # Hold after tap
 162
 163 When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key.  This allows to use auto repeat for the tapped key.  If you prefer to hold a modifier instead, define `TAPPING_FORCE_HOLD` in `config.h`.
 164
 165 Example:
 166
 167 - SHFT_T(KC_A) Down
 168 - SHFT_T(KC_A) Up
 169 - SHFT_T(KC_A) Down
 170 - wait more than tapping term...
 171 - SHFT_T(KC_A) Up
 172
 173 With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto repeat function.
 174
 175 With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allowing to use it as a modifier shortly after having used it as a tap.
 176
 177 !> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
 178
 179 # Retro Tapping
 180
 181 When you hold a dual function key, and haven't pressed anything when you release the key, normally nothing happens.  However, if you enable this, if you release the key without pressing another key, it will send the original key, even if it is outside of the tapping term.
 182
 183 For instance, if you're using `LT(2, KC_SPACE)`, if you hold the key, don't hit anything else and then release it, normally, nothing happens. But with `RETRO_TAPPING` defined in your `config.h`, it will send `KC_SPACE`.