docs/feature_common_shortcuts.md

   1 # Common Keymap Shortcuts
   2
   3 Your keymap can include shortcuts to common operations, for example shifted keys. This page documents the functions that are available to you.
   4
   5 People often define custom names using `#define`. For example:
   6
   7 ```c
   8 #define FN_CAPS LT(_FL, KC_CAPSLOCK)
   9 #define ALT_TAB LALT(KC_TAB)
  10 ```
  11
  12 This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
  13
  14 ### Limits of these aliases
  15
  16 Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes.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 [Keycodes](keycodes.html).
  17
  18 ## Switching and toggling layers
  19
  20 These functions allow you to activate layers in various ways.
  21
  22 Care must be taken when switching layers, it's possible to lock yourself in a layer with no way to deactivate that layer (without unplugging your keyboard.) Always make sure that the layer you're switching into has the same key set to `KC_TRNS`.
  23
  24 Layers stack on top of each other in numerical order, and as a result you can only activate a layer that is "above" your current layer. For example, on layer 2 you can't use `MO(1)`, the behavior will be undefined.
  25
  26 * `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.
  27 * `LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped.
  28 * `TG(layer)` - toggles a layer on or off.
  29 * `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).
  30 * `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.
  31
  32 ## Modifier keys
  33
  34 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.
  35
  36 * `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
  37 * `RSFT(kc)` - applies right Shift to *kc*
  38 * `LCTL(kc)` - applies left Control to *kc*
  39 * `RCTL(kc)` - applies right Control to *kc*
  40 * `LALT(kc)` - applies left Alt to *kc*
  41 * `RALT(kc)` - applies right Alt to *kc*
  42 * `LGUI(kc)` - applies left GUI (command/win) to *kc*
  43 * `RGUI(kc)` - applies right GUI (command/win) to *kc*
  44 * `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
  45 * `MEH(kc)`  - applies Meh (all modifiers except Win/Cmd) to *kc*
  46 * `LCAG(kc)` - applies CtrlAltGui to *kc*
  47
  48 You can also chain these, like this:
  49
  50     LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
  51
  52 ## Shifted Keycodes
  53
  54 The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols.
  55
  56 |Name|Description|
  57 |----|-----------|
  58 | KC_TILD | ~ |
  59 | KC_EXLM | ! |
  60 | KC_QUES | ? |
  61 | KC_AT | @ |
  62 | KC_HASH | # |
  63 | KC_DLR  | $ |
  64 | KC_PERC | % |
  65 | KC_CIRC | ^ |
  66 | KC_AMPR | & |
  67 | KC_ASTR | * |
  68 | KC_LPRN | ( |
  69 | KC_RPRN | ) |
  70 | KC_UNDS | _ |
  71 | KC_PLUS | + |
  72 | KC_DQUO | " |
  73 | KC_LCBR | { |
  74 | KC_RCBR | } |
  75 | KC_LABK | < |
  76 | KC_RABK | > |
  77 | KC_PIPE | | |
  78 | KC_COLN | : |
  79
  80 ## Mod Tap
  81
  82 `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.
  83
  84 These are the values you can use for the `mod` in `MT()` and `OSM()`:
  85
  86   * MOD_LCTL
  87   * MOD_LSFT
  88   * MOD_LALT
  89   * MOD_LGUI
  90   * MOD_RCTL
  91   * MOD_RSFT
  92   * MOD_RALT
  93   * MOD_RGUI
  94   * MOD_HYPR
  95   * MOD_MEH
  96
  97 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.
  98
  99 We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
 100
 101   * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
 102   * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
 103   * `ALT_T(kc)` - is LALT when held and *kc* when tapped
 104   * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
 105   * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
 106   * `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/)
 107   * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
 108   * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
 109
 110 ## One Shot Keys
 111
 112 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.
 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 * `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
 119 * `OSL(layer)` - momentary switch to *layer*.
 120
 121
 122 ## Permissive Hold
 123
 124 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
 125
 126 ```
 127 #define PERMISSIVE_HOLD
 128 ```
 129
 130 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.
 131
 132 Example: (Tapping Term = 200ms)
 133
 134 - SHFT_T(KC_A) Down
 135 - KC_X Down
 136 - KC_X Up
 137 - SHFT_T(KC_A) Up
 138
 139 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).