diff --git a/docs/docs/behaviors/layers.md b/docs/docs/behaviors/layers.md index 7cfb4df7..525cd692 100644 --- a/docs/docs/behaviors/layers.md +++ b/docs/docs/behaviors/layers.md @@ -149,6 +149,43 @@ Example: It is possible to use "toggle layer" to have keys that raise and lower the layers as well. +## 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`. + +`&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. + +### Behavior Binding + +- Reference: `&molock` + +Example: + +```dts +&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): + +```dts +&molock { + bindings = <&to 1>; +}; +``` + +You can also create any number of custom `&molock` behaviors by using `compatible = "zmk,behavior-momentary-layer-lock"` like so: + +```dts +// Presses F if triggered while no momentary layers are active +kp_molock: kp_molock { + compatible = "zmk,behavior-momentary-layer-lock"; + label = "KP_MOLOCK"; + bindings = <&kp F>; +}; +``` + ## Conditional Layers The "conditional layers" feature enables a particular layer when all layers in a specified set are active. diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index c31de5dd..afd9dd64 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -210,6 +210,30 @@ Definition files: With `compatible = "zmk,behavior-sensor-rotate-var"`, this behavior forwards the first parameter it receives to the parameter of the first behavior specified in `bindings`, and second parameter to the parameter of the second behavior. +## Momentary Layer Lock + +Creates a custom behavior that locks any active momentary layers or—if none are active—triggers the fallback behavior specified in `bindings`. + +See the [momentary layer lock](../behaviors/layers.md#momentary-layer-lock) documentation for more details and examples. + +### Devicetree + +Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-momentary-layer-lock.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-momentary-layer-lock.yaml) + +Applies to: `compatible = "zmk,behavior-momentary-layer-lock"` + +| Property | Type | Description | +| ---------------- | ------------- | ------------------------------------------------------- | +| `label` | string | Unique label for the node | +| `#binding-cells` | int | Must be `0` | +| `bindings` | phandle array | A behavior to trigger if no momentary layers are active | + +You can use the following nodes to tweak the default behaviors: + +| Node | Behavior | +| --------- | ------------------------------------------------------------------- | +| `&molock` | [Momentary Layer Lock](../behaviors/layers.md#momentary-layer-lock) | + ## Sticky Key Creates a custom behavior that triggers a behavior and keeps it pressed it until another key is pressed and released.