From d263b27c9a998e31084d7960724b3c243311c4cf Mon Sep 17 00:00:00 2001 From: fauxpark Date: Mon, 6 Aug 2018 13:08:26 +1000 Subject: Dedupe shifted keycodes listing --- docs/feature_advanced_keycodes.md | 30 +----------------------------- 1 file changed, 1 insertion(+), 29 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 493a99fd73..f93b8033a5 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -1,6 +1,6 @@ # 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 @@ -73,34 +73,6 @@ 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` | ||| -|`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. -- cgit v1.2.3 From 097f1a299f2d0e0e5afe174b8cfc1eea1b00c7cf Mon Sep 17 00:00:00 2001 From: fauxpark Date: Thu, 30 Aug 2018 11:05:02 +1000 Subject: Mask off keycode/layer/mod where possible in LT(), MT(), etc. (#3430) * Mask off keycode/layer/mod where possible in LT(), MT(), etc. * Don't need these parentheses * Put back parentheses for order of operations --- docs/feature_advanced_keycodes.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index f93b8033a5..5713234be1 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -13,9 +13,11 @@ People often define custom names using `#define`. For example: 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 @@ -103,10 +105,6 @@ We've added shortcuts to make common modifier/tap (mod-tap) mappings more compac * `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. -?> 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-handed modifier, any other modifiers in a chain of functions will turn into their right-handed equivalents, so it is not possible to "mix and match" the two. - # One Shot Keys One shot keys are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys". -- cgit v1.2.3 From ce3ccd3f4a5e8ff8ac391887f3357dd8e985a452 Mon Sep 17 00:00:00 2001 From: fauxpark Date: Fri, 31 Aug 2018 02:37:05 +1000 Subject: Docs: Tabulate Modifier & Mod-Tap keycode listings in advanced keycodes docs (#3799) --- docs/feature_advanced_keycodes.md | 114 ++++++++++++++++++++++---------------- 1 file changed, 67 insertions(+), 47 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 5713234be1..5f30359e0d 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -57,53 +57,73 @@ Sometimes, you might want to switch between layers in a macro or as part of a ta # 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. - -# 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. +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 -- cgit v1.2.3 From 04e28470bcf22b05ca2bd52746c2254cae281836 Mon Sep 17 00:00:00 2001 From: Brian Choromanski Date: Mon, 8 Oct 2018 09:48:44 -0400 Subject: Added OSL to list of layer toggles --- docs/feature_advanced_keycodes.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 5f30359e0d..0f5b8618a8 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -27,6 +27,7 @@ These functions allow you to activate layers in various ways. Note that layers a * `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. +* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. * `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. -- cgit v1.2.3 From 7f6bb82b9daf51fb79972871e9f85696f783aa7a Mon Sep 17 00:00:00 2001 From: Brian Choromanski Date: Tue, 9 Oct 2018 13:20:09 -0400 Subject: Added link to One Shot Keys --- docs/feature_advanced_keycodes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 0f5b8618a8..2ca533a282 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -27,7 +27,7 @@ These functions allow you to activate layers in various ways. Note that layers a * `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. -* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. +* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys.](#one-shot-keys) * `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. -- cgit v1.2.3 From f2965e1eeaf1769e106145a9d19f102fcd8fe4d4 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Wed, 10 Oct 2018 08:00:41 -0700 Subject: Specify max layers supported in layer keycodes --- docs/feature_advanced_keycodes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 2ca533a282..15109e5459 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -26,8 +26,8 @@ These functions allow you to activate layers in various ways. Note that layers a * `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. -* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys.](#one-shot-keys) +* `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. -- cgit v1.2.3 From 9374c0c9db317932d78356b2f92a7993145ea9a2 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Mon, 22 Oct 2018 11:57:15 -0700 Subject: Add caveats for shifted characters (#4192) * Add caveats for shifted characters And some formatting and grammar corrections. Closes #1037 * Fix spelling of remote * Fix spelling error * Remote not Remove * Remote not Remove --- docs/feature_advanced_keycodes.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 15109e5459..85f4fa1bfc 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -2,7 +2,7 @@ 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: @@ -13,7 +13,7 @@ People often define custom names using `#define`. For example: This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable. -### Caveats +## Caveats 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. @@ -36,7 +36,7 @@ These functions allow you to activate layers in various ways. Note that layers a 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: @@ -44,11 +44,11 @@ If you are just getting started with QMK you will want to keep everything simple * 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. * 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. @@ -126,6 +126,14 @@ For convenience, QMK includes some Mod-Tap shortcuts to make common combinations |`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 | +## 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 are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys". @@ -146,7 +154,7 @@ You can control the behavior of one shot keys by defining these in `config.h`: 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`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L429). -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. +If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by clicking on "Show Options", going to the "Local Resources" tab, 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. # Permissive Hold -- cgit v1.2.3 From 73e92ef0c06de389d39d3ca0a8c98da2196ebec7 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Fri, 26 Oct 2018 21:22:47 -0700 Subject: Docs: Add references to One Shot functions, and clean up formatting (#4189) * Docs: Add references to One Shot functions, and clean up formatting * Update PR based on @mechmerlin's recommendations --- docs/feature_advanced_keycodes.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 85f4fa1bfc..f2e4909d86 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -142,6 +142,8 @@ For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A ch 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 @@ -152,15 +154,20 @@ You can control the behavior of one shot keys by defining these in `config.h`: * `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`](https://github.com/qmk/qmk_firmware/blob/master/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. -If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by clicking on "Show Options", going to the "Local Resources" tab, 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. # 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 ``` @@ -205,6 +212,6 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo # 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. +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. -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`. +For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With `RETRO_TAPPING` defined in your `config.h`, it will send `KC_SPACE`. -- cgit v1.2.3 From 4636f0f623c71f1eda8628cbae4784fe08a8faf7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Konstantin=20=C4=90or=C4=91evi=C4=87?= Date: Tue, 6 Nov 2018 06:34:54 +0100 Subject: Remove ALTG(kc) as it's misleading and is not actually AltGr (#4338) * Remove ALTG(kc) as it's misleading and is not actually AltGr * Add temporary alias for ALGR in keyboards/planck/keymaps/pevecyan/keymap.c --- docs/feature_advanced_keycodes.md | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index f2e4909d86..f9a5c39806 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -73,7 +73,6 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown |`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` | -- cgit v1.2.3 From 672926562519c1ee7370b3ef188c11525de326e5 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Mon, 5 Nov 2018 21:35:16 -0800 Subject: Clarify the Mod Tap defines in documentation (#4352) * Fix up Mod Tap settings keys * Change link names * permissive hold wordsmith Co-Authored-By: drashna * ignore mod tap wordsmithing Co-Authored-By: drashna * grammar fix Co-Authored-By: drashna * wordsmithing Co-Authored-By: drashna * word smithing Co-Authored-By: drashna --- docs/feature_advanced_keycodes.md | 62 +++++++++++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 15 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index f9a5c39806..bb5cb7419b 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -170,30 +170,56 @@ As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new #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. -Example: (Tapping Term = 200ms) +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. -- SHFT_T(KC_A) Down -- KC_X Down -- KC_X Up -- SHFT_T(KC_A) Up +For Instance: + +- `SHFT_T(KC_A)` Down +- `KC_X` Down +- `KC_X` Up +- `SHFT_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 +``` -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). +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. -# Mod tap interrupt +Setting `Ignore Mod Tap Interrupt` requires holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod). -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 Instance: -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. +- `SHFT_T(KC_A)` Down +- `KC_X` Down +- `SHFT_T(KC_A)` Up +- `KC_X` Up -You can disable this behavior by defining `IGNORE_MOD_TAP_INTERRUPT` in `config.h`. +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`). -Note that this only concerns modifiers and not layer switching keys. -# Hold after tap +?> __Note__: This only concerns modifiers and not layer switching keys. -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`. +?> 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: @@ -211,6 +237,12 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo # 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. -For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With `RETRO_TAPPING` defined in your `config.h`, it will send `KC_SPACE`. +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. -- cgit v1.2.3 From 28fbf84cc5ff52f545011ea4198a6cc6d054f896 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Konstantin=20=C4=90or=C4=91evi=C4=87?= Date: Wed, 12 Dec 2018 19:17:19 +0100 Subject: Add standard definitions for ALGR and KC_ALGR (#4389) * Add standard ALGR defition, remove (re)definitions from language files * Use ALGR(kc) consistently in ALTGR(kc) aliases * Non-Nordic keymaps should not use NO_ALGR * Add standard KC_ALGR definition * Update docs with ALGR and KC_ALGR * Update SS_ALGR and ALGR_T aliases --- docs/feature_advanced_keycodes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index bb5cb7419b..e5f241f7f1 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -68,7 +68,7 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown |`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` | +|`RALT(kc)`|`ALGR(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` | @@ -92,7 +92,7 @@ The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_ |`MOD_LGUI`|Left GUI (Windows/Command/Meta key) | |`MOD_RCTL`|Right Control | |`MOD_RSFT`|Right Shift | -|`MOD_RALT`|Right Alt | +|`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) | -- cgit v1.2.3 From 6c6bbff600cd37416bdf067ac67971c58136129f Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Fri, 14 Dec 2018 07:37:27 -0800 Subject: Enhance documentation for Tap-Hold functions (#4628) --- docs/feature_advanced_keycodes.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index e5f241f7f1..bda4972331 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -161,8 +161,13 @@ For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear !> 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. +# Tap-Hold Configuration Options -# Permissive Hold +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: @@ -185,7 +190,7 @@ Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this wil ?> 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 +## Ignore Mod Tap Interrupt To enable this setting, add this to your `config.h`: @@ -211,7 +216,7 @@ Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` ena ?> 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 +## Tapping Force Hold To enable `tapping force hold`, add the following to your `config.h`: @@ -235,7 +240,7 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo !> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle). -# Retro Tapping +## Retro Tapping To enable `retro tapping`, add the following to your `config.h`: -- cgit v1.2.3 From fbcbf4492685108a7f257df4e06871abd9def4d7 Mon Sep 17 00:00:00 2001 From: Kyle Brown Date: Fri, 28 Dec 2018 10:31:15 -0800 Subject: Update feature_advanced_keycodes.md (#3672) * Update feature_advanced_keycodes.md Probably a better way to word it, but I've solved this issue on reddit several times, had to solve this for friends, ect. It's something worth being in the docs as it's a common issue, and not always intuitive. I have offered this change as I was told by several people "It was never mentioned in the docs". * Update feature_advanced_keycodes.md Clear up what was meant to be said. --- docs/feature_advanced_keycodes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/feature_advanced_keycodes.md') diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index bda4972331..8c0a22fc67 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -21,7 +21,7 @@ Additionally, if at least one right-handed modifier is specified in a Mod Tap or # Switching and Toggling Layers -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) +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. * `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. -- cgit v1.2.3