expand docs and give example

This commit is contained in:
Dylan MacKenzie 2024-02-12 17:31:39 -08:00
parent 16791aa0a3
commit df496393b2

View file

@ -151,9 +151,11 @@ It is possible to use "toggle layer" to have keys that raise and lower the layer
## Momentary Layer Lock
Even if you mostly use momentary layers, it's occasionally useful to permanently enable a layer without needing to hold anything down. Instead of creating a separate `&tog` or `&to` binding for each layer, you can use `&molock`.
Even if you mostly use [momentary layers](#momentary-layer) instead of `&to` or `&tog`, it's occasionally useful to permanently enable a layer without needing to hold anything down. Instead of creating an additional `&tog` or `&to` binding for each such layer, you can use `&molock`.
`&molock` causes all currently active momentary layers not to be deactivated when `&mo` is released. If no momentary layers are active, `&molock` triggers a fallback behavior, which by default returns to the base layer (`&to 0`), deactivating any locked momentary layers in the process. Alternatively, the user can deactivate a single locked momentary layer by pressing and releasing the corresponding `&mo` binding again.
If `&molock` is pressed while any number of `&mo` bindings are being held, those momentary layers will not be deactivated when the corresponding `&mo` key is released. As a result, those momentary layers become "locked" until that `&mo` key is pressed and released a second time or the layer becomes deactivated by some other means (e.g. a `&tog` binding for that layer or a `&to` binding for a lower one).
If `&molock` is pressed while no `&mo` bindings are being held, it triggers a user-configurable fallback behavior. The default fallback behavior returns to the base layer (`&to 0`), deactivating any locked momentary layers in the process.
### Behavior Binding
@ -165,6 +167,33 @@ Example:
&molock
```
Lock a symbol layer:
```dts
#define BASE 0
#define SYMS 1
/ {
keymap {
compatible = "zmk,keymap";
base_layer {
bindings = <&mo SYMS &kp Z &kp M &kp K >;
};
symbol_layer {
bindings = <&trans &kp PLUS &kp MINUS &molock>;
};
};
};
```
:::info
Holding down the leftmost key (`&mo SYMS`), then pressing and releasing the rightmost key (`&molock`), will lock the symbol layer. Even after releasing the leftmost key, the symbol layer remains active.
To return to the base layer, press and release either the leftmost key (triggering the `&mo SYMS` behavior a second time) or the rightmost key (triggering the default fallback behavior for `&molock`).
:::
### Configuration
You can configure a different fallback behavior by overriding the `bindings` property of the built-in `&molock` behavior. For example, to return to layer 1 (instead of layer 0):