# 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
+## Assigning Custom Names
People often define custom names using `#define`. For example:
#define ALT_TAB LALT(KC_TAB)
```
-This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
+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. If you need to apply modifiers to your tapped keycode, [Tap Dance](https://github.com/qmk/qmk_firmware/blob/master/docs/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
+
+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). When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
-* `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: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
+* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality.
+* `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
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.
-### Beginners
+## Beginners
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
+## Intermediate Users
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.
-### Advanced Users
+## Advanced Users
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.
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.
-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](../tmk_core/common/action_layer.h).
+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).
# 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)`|`C(kc)` |Hold Left Control and press `kc` |
+|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
+|`LALT(kc)`|`A(kc)` |Hold Left Alt and press `kc` |
+|`LGUI(kc)`|`G(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)`|`ALGR(kc)` |Hold Right Alt and press `kc` |
+|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI 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` |
+|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` |
+|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` |
+|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI 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 (AltGr) |
+|`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 |
+|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped |
+|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped |
+|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped |
+|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped |
+|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped |
+|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped |
+|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped |
+|`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 |
+|`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 |
+|`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|
+|`HYPR_T(kc)`|`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/)|
+
+## Caveats
+
+Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
+
+Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
+
+To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
# One Shot Keys
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.
+Additionally, hitting keys five times in a short period will lock that key. This applies for both One Shot Modifiers and One Shot Layers, and is controlled by the `ONESHOT_TAP_TOGGLE` define.
+
You can control the behavior of one shot keys by defining these in `config.h`:
```c
-#define ONESHOT_TAP_TOGGLE 5 /* Tapping this number of times holds the key until tapped this number of times again. */
+#define ONESHOT_TAP_TOGGLE 5 /* Tapping this number of times holds the key until tapped once again. */
#define ONESHOT_TIMEOUT 5000 /* Time (in ms) before the one shot key is released */
```
* `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
* `OSL(layer)` - momentary switch to *layer*.
-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`](../tmk_core/common/action.c#L429).
+Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine.
+
+For one shot layers, 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 one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it.
+
+!> 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.
+
+## Callbacks
+
+When you'd like to perform custom logic when pressing a one shot key, there are several callbacks you can choose to implement. You could indicate changes in one shot keys by flashing an LED or making a sound, for example.
+
+There is a callback for `OSM(mod)`. It is called whenever the state of any one shot modifier key is changed: when it toggles on, but also when it is toggled off. You can use it like this:
+
+```c
+void oneshot_mods_changed_user(uint8_t mods) {
+ if (mods & MOD_MASK_SHIFT) {
+ println("Oneshot mods SHIFT");
+ }
+ if (mods & MOD_MASK_CTRL) {
+ println("Oneshot mods CTRL");
+ }
+ if (mods & MOD_MASK_ALT) {
+ println("Oneshot mods ALT");
+ }
+ if (mods & MOD_MASK_GUI) {
+ println("Oneshot mods GUI");
+ }
+ if (!mods) {
+ println("Oneshot mods off");
+ }
+}
+```
+
+The `mods` argument contains the active mods after the change, so it reflects the current state.
+
+When you use One Shot Tap Toggle (by adding `#define ONESHOT_TAP_TOGGLE 2` in your `config.h` file), you may lock a modifier key by pressing it the specified amount of times. There's a callback for that, too:
+
+```c
+void oneshot_locked_mods_changed_user(uint8_t mods) {
+ if (mods & MOD_MASK_SHIFT) {
+ println("Oneshot locked mods SHIFT");
+ }
+ if (mods & MOD_MASK_CTRL) {
+ println("Oneshot locked mods CTRL");
+ }
+ if (mods & MOD_MASK_ALT) {
+ println("Oneshot locked mods ALT");
+ }
+ if (mods & MOD_MASK_GUI) {
+ println("Oneshot locked mods GUI");
+ }
+ if (!mods) {
+ println("Oneshot locked mods off");
+ }
+}
+```
+
+Last, there is also a callback for the `OSL(layer)` one shot key:
+
+```c
+void oneshot_layer_changed_user(uint8_t layer) {
+ if (layer == 1) {
+ println("Oneshot layer 1 on");
+ }
+ if (!layer) {
+ println("Oneshot layer off");
+ }
+}
+```
+
+If any one shot layer is switched off, `layer` will be zero. When you're looking to do something on any layer change instead of one shot layer changes, `layer_state_set_user` is a better callback to use.
+
+If you are making your own keyboard, there are also `_kb` equivalent functions:
+
+```c
+void oneshot_locked_mods_changed_kb(uint8_t mods);
+void oneshot_mods_changed_kb(uint8_t mods);
+void oneshot_layer_changed_kb(uint8_t layer);
+```
+
+As with any callback, be sure to call the `_user` variant to allow for further customizability.
+
+# Tap-Hold Configuration Options
+
+While Tap-Hold options are fantastic, they are not without their issues. We have tried to configure them with reasonal defaults, but that may still cause issues for some people.
+
+These options let you modify the behavior of the Tap-Hold keys.
## Permissive Hold
As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
-```
+```c
#define PERMISSIVE_HOLD
```
-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.
+This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings.
+
+If you press a Mod Tap key, tap another key (press and release) and then release the Mod Tap key, all within the tapping term, it will output the "tapping" function for both keys.
+
+For Instance:
+
+- `SFT_T(KC_A)` Down
+- `KC_X` Down
+- `KC_X` Up
+- `SFT_T(KC_A)` Up
+
+Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`).
+
+?> If you have `Ignore Mod Tap Interrupt` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
+
+## Ignore Mod Tap Interrupt
+
+To enable this setting, add this to your `config.h`:
+
+```c
+#define IGNORE_MOD_TAP_INTERRUPT
+```
+
+Similar to Permissive Hold, this alters how the firmware processes input for fast typist. If you press a Mod Tap key, press another key, release the Mod Tap key, and then release the normal key, it would normally output the "tapping" function for both keys. This may not be desirable for rolling combo keys.
+
+Setting `Ignore Mod Tap Interrupt` requires holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod).
+
+For Instance:
+
+- `SFT_T(KC_A)` Down
+- `KC_X` Down
+- `SFT_T(KC_A)` Up
+- `KC_X` Up
+
+Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X` (`SHIFT`+`x`).
-Example: (Tapping Term = 200ms)
-- SHFT_T(KC_A) Down
-- KC_X Down
-- KC_X Up
-- SHFT_T(KC_A) Up
+?> __Note__: This only concerns modifiers and not layer switching keys.
+
+?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
+
+## Tapping Force Hold
+
+To enable `tapping force hold`, add the following to your `config.h`:
+
+```c
+#define TAPPING_FORCE_HOLD
+```
+
+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.
+
+Example:
+
+- SFT_T(KC_A) Down
+- SFT_T(KC_A) Up
+- SFT_T(KC_A) Down
+- wait more than tapping term...
+- SFT_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
+
+To enable `retro tapping`, add the following to your `config.h`:
+
+```c
+#define RETRO_TAPPING
+```
+
+Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
-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).
+For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.
projects / qmk_firmware.git / blobdiff