diff options
Diffstat (limited to 'docs/feature_layers.md')
-rw-r--r-- | docs/feature_layers.md | 36 |
1 files changed, 19 insertions, 17 deletions
diff --git a/docs/feature_layers.md b/docs/feature_layers.md index e57642071f..77b6ef9531 100644 --- a/docs/feature_layers.md +++ b/docs/feature_layers.md @@ -1,25 +1,25 @@ -# Layers :id=layers +# Layers {#layers} One of the most powerful and well used features of QMK Firmware is the ability to use layers. For most people, this amounts to a function key that allows for different keys, much like what you would see on a laptop or tablet keyboard. -For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap.md#keymap-and-layers). +For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap#keymap-and-layers). -## Switching and Toggling Layers :id=switching-and-toggling-layers +## Switching and Toggling Layers {#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. 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).) +* `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#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. The modifiers this keycode accept are prefixed with `MOD_`, not `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.md) for details and additional functionality. +* `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. -### Caveats :id=caveats +### Caveats {#caveats} -Currently, the `layer` argument of `LT()` is limited to layers 0-15, and the `kc` argument to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 4 bits are used for the function identifier and 4 bits for the layer, leaving only 8 bits for the keycode. +Currently, the `layer` argument of `LT()` is limited to layers 0-15, and the `kc` argument to the [Basic Keycode set](keycodes_basic), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. This is because QMK uses 16-bit keycodes, of which 4 bits are used for the function identifier and 4 bits for the layer, leaving only 8 bits for the keycode. For a similar reason, the `layer` argument of `LM()` is also limited to layers 0-15 and the `mod` argument must fit within 5 bits. As a consequence, although left and right modifiers are supported by `LM()`, it is impossible to mix and match left and right modifiers. Specifying at least one right-hand modifier in a combination such as `MOD_RALT|MOD_LSFT` will convert *all* the listed modifiers to their right-hand counterpart. So, using the aforementionned mod-mask will actually send <kbd>Right Alt</kbd>+<kbd>Right Shift</kbd>. Make sure to use the `MOD_xxx` constants over alternative ways of specifying modifiers when defining your layer-mod key. @@ -27,13 +27,13 @@ For a similar reason, the `layer` argument of `LM()` is also limited to layers 0 |:---------------:|:----------------------:|:------------------------:|:----------------:| | ❌ | ❌ | ❌ | ✅ | -Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. +Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. -## Working with Layers :id=working-with-layers +## Working with Layers {#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 :id=beginners +### 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: @@ -41,11 +41,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 :id=intermediate-users +### 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 :id=advanced-users +### 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. @@ -53,7 +53,7 @@ Layers stack on top of each other in numerical order. When determining what a ke 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/quantum/action_layer.h). -## Functions :id=functions +## Functions {#functions} There are a number of functions (and variables) related to how you can use or manipulate the layers. @@ -87,7 +87,9 @@ In addition to the functions that you can call, there are a number of callback f | `default_layer_state_set_kb(layer_state_t state)` | Callback for default layer functions, for keyboard. Called on keyboard initialization. | | `default_layer_state_set_user(layer_state_t state)` | Callback for default layer functions, for users. Called on keyboard initialization. | -?> For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions.md#layer-change-code) document. +::: tip +For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions#layer-change-code) document. +::: It is also possible to check the state of a particular layer using the following functions and macros. @@ -96,13 +98,13 @@ It is also possible to check the state of a particular layer using the following | `layer_state_is(layer)` | Checks if the specified `layer` is enabled globally. | `IS_LAYER_ON(layer)`, `IS_LAYER_OFF(layer)` | | `layer_state_cmp(state, layer)` | Checks `state` to see if the specified `layer` is enabled. Intended for use in layer callbacks. | `IS_LAYER_ON_STATE(state, layer)`, `IS_LAYER_OFF_STATE(state, layer)` | -## Layer Change Code :id=layer-change-code +## Layer Change Code {#layer-change-code} This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. ### Example `layer_state_set_*` Implementation -This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example. +This example shows how to set the [RGB Underglow](feature_rgblight) lights based on the layer, using the Planck as an example. ```c layer_state_t layer_state_set_user(layer_state_t state) { @@ -185,4 +187,4 @@ Outside of `layer_state_set_*` functions, you can use the `IS_LAYER_ON(layer)` a * Keymap: `layer_state_t layer_state_set_user(layer_state_t state)` -The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status) +The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap#keymap-layer-status) |