From df496393b2f6d654905b3215c00d515937ddc913 Mon Sep 17 00:00:00 2001 From: Dylan MacKenzie Date: Mon, 12 Feb 2024 17:31:39 -0800 Subject: [PATCH] expand docs and give example --- docs/docs/behaviors/layers.md | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/docs/docs/behaviors/layers.md b/docs/docs/behaviors/layers.md index 525cd692..71aee959 100644 --- a/docs/docs/behaviors/layers.md +++ b/docs/docs/behaviors/layers.md @@ -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):