docs/key_functions.md

   1 # Quick Aliases To Common Actions
   2
   3 Your keymap can include shortcuts to common operations (called "function actions" in tmk).
   4
   5 These functions work the same way that their `ACTION_*` functions do - they're just quick aliases. To dig into all of the tmk `ACTION_*` functions, please see the [TMK documentation](keymap.md#2-action).
   6
   7 Instead of using `FNx` when defining `ACTION_*` functions, you can use `F(x)` - the benefit here is being able to use more than 32 function actions (up to 4096), if you happen to need them.
   8
   9 ### Limits of these aliases
  10
  11 Currently, the keycodes able to used with these functions are limited to the TMK ones, 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 this list](keycode.md).
  12
  13 ### Switching and toggling layers
  14
  15 `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. When you apply this to a key, that same key must be set as `KC_TRNS` on the destination layer. Otherwise, you won't make it back to the original layer when you release the key (and you'll get a keycode sent). You can only switch to layers *above* your current layer. If you're on layer 0 and you use `MO(1)`, that will switch to layer 1 just fine. But if you include `MO(3)` on layer 5, that won't do anything for you -- because layer 3 is lower than layer 5 on the stack.
  16
  17 `OSL(layer)` - momentary switch to *layer*, as a one-shot operation. So if you have a key that's defined as `OSL(1)`, and you tap that key, then only the very next keystroke would come from layer 1. You would drop back to layer zero immediately after that one keystroke. That's handy if you have a layer full of custom shortcuts -- for example, a dedicated key for closing a window. So you tap your one-shot layer mod, then tap that magic 'close window' key, and keep typing like a boss. Layer 1 would remain active as long as you hold that key down, too (so you can use it like a momentary toggle-layer key with extra powers).
  18
  19 `LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped. Like `MO()`, this only works upwards in the layer stack (`layer` must be higher than the current layer).
  20
  21 `TG(layer)` - toggles a layer on or off. As with `MO()`, you should set this key as `KC_TRNS` in the destination layer so that tapping it again actually toggles back to the original layer. Only works upwards in the layer stack.
  22
  23 `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).
  24
  25 `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 1` for just one tap.
  26
  27
  28 ### Fun with modifier keys
  29
  30 * `LSFT(kc)` - applies left Shift to *kc* (keycode) - `S(kc)` is an alias
  31 * `RSFT(kc)` - applies right Shift to *kc*
  32 * `LCTL(kc)` - applies left Control to *kc*
  33 * `RCTL(kc)` - applies right Control to *kc*
  34 * `LALT(kc)` - applies left Alt to *kc*
  35 * `RALT(kc)` - applies right Alt to *kc*
  36 * `LGUI(kc)` - applies left GUI (command/win) to *kc*
  37 * `RGUI(kc)` - applies right GUI (command/win) to *kc*
  38 * `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
  39 * `MEH(kc)`  - applies Meh (all modifiers except Win/Cmd) to *kc*
  40 * `LCAG(kc)` - applies CtrlAltGui to *kc*
  41
  42 You can also chain these, like this:
  43
  44     LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
  45
  46 The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols. Their long names are also available and documented in `quantum/quantum_keycodes.h`.
  47
  48     KC_TILD  ~
  49     KC_EXLM  !
  50     KC_QUES  ?
  51     KC_AT    @
  52     KC_HASH  #
  53     KC_DLR   $
  54     KC_PERC  %
  55     KC_CIRC  ^
  56     KC_AMPR  &
  57     KC_ASTR  *
  58     KC_LPRN  (
  59     KC_RPRN  )
  60     KC_UNDS  _
  61     KC_PLUS  +
  62     KC_DQUO  "
  63     KC_LCBR  {
  64     KC_RCBR  }
  65     KC_LABK  <
  66     KC_RABK  >
  67     KC_PIPE  |
  68     KC_COLN  :
  69
  70 `OSM(mod)` - this is a "one shot" modifier. So let's say you have your left Shift key defined as `OSM(MOD_LSFT)`. Tap it, let go, and Shift is "on" -- but only for the next character you'll type. So to write "The", you don't need to hold down Shift -- you tap it, tap t, and move on with life. And if you hold down the left Shift key, it just works as a left Shift key, as you would expect (so you could type THE). There's also a magical, secret way to "lock" a modifier by tapping it multiple times. If you want to learn more about that, open an issue. :)
  71
  72 `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.
  73
  74 These are the values you can use for the `mod` in `MT()` and `OSM()`:
  75
  76   * MOD_LCTL
  77   * MOD_LSFT
  78   * MOD_LALT
  79   * MOD_LGUI
  80   * MOD_RCTL
  81   * MOD_RSFT
  82   * MOD_RALT
  83   * MOD_RGUI
  84   * MOD_HYPR
  85   * MOD_MEH
  86
  87 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.
  88
  89 We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
  90
  91   * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
  92   * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
  93   * `ALT_T(kc)` - is LALT when held and *kc* when tapped
  94   * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
  95   * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
  96   * `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/)
  97   * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
  98   * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
  99
 100 ##### Permissive Hold
 101
 102 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
 103
 104 ```
 105 #define PERMISSIVE_HOLD
 106 ```
 107
 108 This makes it easier for fast typists to use dual-function keys. As described in the PR:
 109
 110 Without this, if you let go of a held key inside the tapping term, it won't register.
 111
 112 Example: (Tapping Term = 200)
 113
 114 - SHFT_T(KC_A) Down
 115 - KC_X Down
 116 - KC_X Up
 117 - SHFT_T(KC_A) Up
 118
 119 With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
 120
 121 With defaults, if above is typed within tapping term, this will emit `ax`, which I doubt is what anyone really wants