# Advanced Keycodes
-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.
+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.
### Assigning Custom Names
This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
-### Limits of These Aliases
+### Caveats
-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).
+Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored.
+
+Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two.
# Switching and Toggling Layers
-These functions allow you to activate layers in various ways.
+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)
-* `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.
-* `LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped.
-* `TG(layer)` - toggles a layer on or off.
-* `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).
-* `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 repeatedly 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.
-* `LM(layer, mod)` - Momentary switch to *layer* (like MO), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
+* `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).)
+* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated.
+* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped.
+* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
+* `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).
+* `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.
# Working with Layers
If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
-* Setup layer 0 as your "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.)
+* 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).
* 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.
-* Never try to stack a higher numbered layer on top of a lower numbered layer. Doing so is tricky and error prone.
+* 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.
### Intermediate Users
# Modifier Keys
-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.
-
-* `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
-* `RSFT(kc)` - applies right Shift to *kc*
-* `LCTL(kc)` - applies left Control to *kc*
-* `RCTL(kc)` - applies right Control to *kc*
-* `LALT(kc)` - applies left Alt to *kc*
-* `RALT(kc)` - applies right Alt to *kc*
-* `LGUI(kc)` - applies left GUI (command/win) to *kc*
-* `RGUI(kc)` - applies right GUI (command/win) to *kc*
-* `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
-* `MEH(kc)` - applies Meh (all modifiers except Win/Cmd) to *kc*
-* `LCAG(kc)` - applies CtrlAltGui to *kc*
-
-You can also chain these, like this:
-
- LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
-
-# Shifted Keycodes
-
-The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols.
-
-|Key |Aliases |Description |
-|------------------------|------------------|-------------------|
-|`KC_TILDE` |`KC_TILD` |`~` |
-|`KC_EXCLAIM` |`KC_EXLM` |`!` |
-|`KC_AT` | |`@` |
-|`KC_HASH` | |`#` |
-|`KC_DOLLAR` |`KC_DLR` |`$` |
-|`KC_PERCENT` |`KC_PERC` |`%` |
-|`KC_CIRCUMFLEX` |`KC_CIRC` |`^` |
-|`KC_AMPERSAND` |`KC_AMPR` |`&` |
-|`KC_ASTERISK` |`KC_ASTR` |`*` |
-|`KC_LEFT_PAREN` |`KC_LPRN` |`(` |
-|`KC_RIGHT_PAREN` |`KC_RPRN` |`)` |
-|`KC_UNDERSCORE` |`KC_UNDS` |`_` |
-|`KC_PLUS` | |`+` |
-|`KC_LEFT_CURLY_BRACE` |`KC_LCBR` |`{` |
-|`KC_RIGHT_CURLY_BRACE` |`KC_RCBR` |`}` |
-|`KC_PIPE` | |<code>|</code>|
-|`KC_COLON` |`KC_COLN` |`:` |
-|`KC_DOUBLE_QUOTE` |`KC_DQT`/`KC_DQUO`|`"` |
-|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<` |
-|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>` |
-|`KC_QUESTION` |`KC_QUES` |`?` |
-
-# Mod Tap
-
-`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.
-
-These are the values you can use for the `mod` in `MT()` and `OSM()`:
-
- * MOD_LCTL
- * MOD_LSFT
- * MOD_LALT
- * MOD_LGUI
- * MOD_RCTL
- * MOD_RSFT
- * MOD_RALT
- * MOD_RGUI
- * MOD_HYPR
- * MOD_MEH
-
-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.
-
-We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
-
- * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
- * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
- * `ALT_T(kc)` - is LALT when held and *kc* when tapped
- * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
- * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
- * `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/)
- * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
- * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
-
-{% hint style='info' %}
-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.
-
-Additionally, if there is at least one right modifier, any other modifiers will turn into their right equivalents, so it is not possible to "mix and match" the two.
-{% endhint %}
+These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
+
+|Key |Aliases |Description |
+|----------|----------------------|----------------------------------------------------|
+|`LCTL(kc)`| |Hold Left Control and press `kc` |
+|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
+|`LALT(kc)`| |Hold Left Alt and press `kc` |
+|`LGUI(kc)`|`LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
+|`RCTL(kc)`| |Hold Right Control and press `kc` |
+|`RSFT(kc)`| |Hold Right Shift and press `kc` |
+|`RALT(kc)`| |Hold Right Alt and press `kc` |
+|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`|Hold Right GUI and press `kc` |
+|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc`|
+|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` |
+|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` |
+|`ALTG(kc)`| |Hold Right Control and Alt and press `kc` |
+|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc` |
+|`LCA(kc)` | |Hold Left Control and Alt and press `kc` |
+
+You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
+
+# Mod-Tap
+
+The Mod-Tap key `MT(mod, kc)` acts like a modifier when held, and a regular keycode when tapped. In other words, you can have a key that sends Escape when you tap it, but functions as a Control or Shift key when you hold it down.
+
+The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`:
+
+|Modifier |Description |
+|----------|----------------------------------------|
+|`MOD_LCTL`|Left Control |
+|`MOD_LSFT`|Left Shift |
+|`MOD_LALT`|Left Alt |
+|`MOD_LGUI`|Left GUI (Windows/Command/Meta key) |
+|`MOD_RCTL`|Right Control |
+|`MOD_RSFT`|Right Shift |
+|`MOD_RALT`|Right Alt |
+|`MOD_RGUI`|Right GUI (Windows/Command/Meta key) |
+|`MOD_HYPR`|Hyper (Left Control, Shift, Alt and GUI)|
+|`MOD_MEH` |Meh (Left Control, Shift, and Alt) |
+
+You can combine these by ORing them together like so:
+
+```c
+MT(MOD_LCTL | MOD_LSFT, KC_ESC)
+```
+
+This key would activate Left Control and Left Shift when held, and send Escape when tapped.
+
+For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
+
+|Key |Aliases |Description |
+|------------|---------------------------------------|-------------------------------------------------------|
+|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped |
+|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped |
+|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped |
+|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped |
+|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped |
+|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped |
+|`LGUI_T(kc)`|`LCMD_T(kc)`, `RWIN_T(kc)`, `GUI_T(kc)`|Left GUI when held, `kc` when tapped |
+|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped |
+|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped |
+|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped|
+|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped |
+|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped |
+|`ALL_T(kc)` | |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
+|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped |
+|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped |
# One Shot Keys
- SHFT_T(KC_A) Up
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).
+
+# Mod tap interrupt
+
+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.
+
+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.
+
+You can disable this behavior by defining `IGNORE_MOD_TAP_INTERRUPT` in `config.h`.
+
+Note that this only concerns modifiers and not layer switching keys.
+
+# Hold after tap
+
+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`.
+
+Example:
+
+- SHFT_T(KC_A) Down
+- SHFT_T(KC_A) Up
+- SHFT_T(KC_A) Down
+- wait more than tapping term...
+- SHFT_T(KC_A) Up
+
+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.
+
+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.
+
+!> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
+
+# Retro Tapping
+
+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.
+
+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`.
projects / qmk_firmware.git / blobdiff