docs/feature_advanced_keycodes.md

   1 # Advanced Keycodes
   2
   3 Your keymap can include keycodes that are more advanced than normal, for example shifted keys. 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.html), 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.html).
  19
  20 # Switching and toggling layers
  21
  22 These functions allow you to activate layers in various ways.
  23
  24 * `MO(layer)` - momentary switch to *layer*. As soon as you let go of the key, the layer is deactivated and you pop back out to the previous layer.
  25 * `LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped.
  26 * `TG(layer)` - toggles a layer on or off.
  27 * `TO(layer)` - Goes to a layer. This code is special, because it lets you go either up or down the stack -- just goes directly to the layer you want. So while other codes only let you go _up_ the stack (from layer 0 to layer 3, for example), `TO(2)` is going to get you to layer 2, no matter where you activate it from -- even if you're currently on layer 5. This gets activated on keydown (as soon as the key is pressed).
  28 * `TT(layer)` - Layer Tap-Toggle. If you hold the key down, the layer becomes active, and then deactivates when you let go. And if you tap it, the layer simply becomes active (toggles on). It needs 5 taps by default, but you can set it by defining `TAPPING_TOGGLE`, for example, `#define TAPPING_TOGGLE 2` for just two taps.
  29
  30 # Working With Layers
  31
  32 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.
  33
  34 ### Beginners
  35
  36 If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
  37
  38 * Setup layer 0 as your "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.)
  39 * 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.
  40 * Never try to stack a higher numbered layer on top of a lower numbered layer. Doing so is tricky and error prone.
  41
  42 ### Intermediate Users
  43
  44 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.
  45
  46 ### Advanced Users
  47
  48 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.
  49
  50 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.
  51
  52 # Modifier keys
  53
  54 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.
  55
  56 * `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
  57 * `RSFT(kc)` - applies right Shift to *kc*
  58 * `LCTL(kc)` - applies left Control to *kc*
  59 * `RCTL(kc)` - applies right Control to *kc*
  60 * `LALT(kc)` - applies left Alt to *kc*
  61 * `RALT(kc)` - applies right Alt to *kc*
  62 * `LGUI(kc)` - applies left GUI (command/win) to *kc*
  63 * `RGUI(kc)` - applies right GUI (command/win) to *kc*
  64 * `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
  65 * `MEH(kc)`  - applies Meh (all modifiers except Win/Cmd) to *kc*
  66 * `LCAG(kc)` - applies CtrlAltGui to *kc*
  67
  68 You can also chain these, like this:
  69
  70     LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
  71
  72 # Shifted Keycodes
  73
  74 The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols.
  75
  76 |Name|Description|
  77 |----|-----------|
  78 | KC_TILD | ~ |
  79 | KC_EXLM | ! |
  80 | KC_QUES | ? |
  81 | KC_AT | @ |
  82 | KC_HASH | # |
  83 | KC_DLR  | $ |
  84 | KC_PERC | % |
  85 | KC_CIRC | ^ |
  86 | KC_AMPR | & |
  87 | KC_ASTR | * |
  88 | KC_LPRN | ( |
  89 | KC_RPRN | ) |
  90 | KC_UNDS | _ |
  91 | KC_PLUS | + |
  92 | KC_DQUO | " |
  93 | KC_LCBR | { |
  94 | KC_RCBR | } |
  95 | KC_LABK | < |
  96 | KC_RABK | > |
  97 | KC_PIPE | &#x7C; |
  98 | KC_COLN | : |
  99
 100 # Mod Tap
 101
 102 `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.
 103
 104 These are the values you can use for the `mod` in `MT()` and `OSM()`:
 105
 106   * MOD_LCTL
 107   * MOD_LSFT
 108   * MOD_LALT
 109   * MOD_LGUI
 110   * MOD_RCTL
 111   * MOD_RSFT
 112   * MOD_RALT
 113   * MOD_RGUI
 114   * MOD_HYPR
 115   * MOD_MEH
 116
 117 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. Note however, that you cannot mix right and left side modifiers.
 118
 119 We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
 120
 121   * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
 122   * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
 123   * `ALT_T(kc)` - is LALT when held and *kc* when tapped
 124   * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
 125   * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
 126   * `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/)
 127   * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
 128   * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
 129
 130 # One Shot Keys
 131
 132 One shot keys are keys that remain active until the next key is pressed, and then are releasd. This allows you to type keyboard combinations without pressing more than one key at a time.
 133
 134 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.
 135
 136 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.
 137
 138 You can control the behavior of one shot keys by defining these in `config.h`:
 139
 140 ```c
 141 #define ONESHOT_TAP_TOGGLE 5  /* Tapping this number of times holds the key until tapped this number of times again. */
 142 #define ONESHOT_TIMEOUT 5000  /* Time (in ms) before the one shot key is released */
 143 ```
 144
 145 * `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
 146 * `OSL(layer)` - momentary switch to *layer*.
 147
 148 ## Permissive Hold
 149
 150 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
 151
 152 ```
 153 #define PERMISSIVE_HOLD
 154 ```
 155
 156 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.
 157
 158 Example: (Tapping Term = 200ms)
 159
 160 - SHFT_T(KC_A) Down
 161 - KC_X Down
 162 - KC_X Up
 163 - SHFT_T(KC_A) Up
 164
 165 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).