kofal.net/zmk
1
0
Fork 1
mirror of https://github.com/zmkfirmware/zmk.git synced 2026-03-19 20:45:18 -05:00
Code Issues Packages Projects Releases Wiki Activity

feat: Allow layer behaviors to "lock" layers on (#2717)

Browse Source 
* refactor(core)!: Allow layer behaviors to "lock" layers on

Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>

* docs: Added documentation note on locking layers

Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>

---------

Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
This commit is contained in:
Nicolas Munnich
2025-11-14 22:13:35 +00:00
committed by GitHub
parent f9be3ed9c0
commit 5138c6fb14
34 changed files with 433 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/docs/config/behaviors.md
View File

@@ -154,6 +154,29 @@ You can use the following node to tweak the default behavior:
| ----- | ------------------------------------------------ |
| `&kt` | [Key toggle](../keymaps/behaviors/key-toggle.md) |
## Momentary Layer
Creates a custom behavior that toggles a layer on when pressed, and off when released.
See the [momentary layer behavior](../keymaps/behaviors/layers.md#momentary-layer) documentation for more details and examples.
### Devicetree
Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-momentary-layer.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-momentary-layer.yaml)
Applies to: `compatible = "zmk,behavior-momentary-layer"`
| Property | Type | Description | Default |
| ---------------- | ---- | --------------------------------------------------------------- | ------- |
| `#binding-cells` | int | Must be `<1>` | |
| `locking` | bool | Whether the behavior can lock and unlock layers in the on state | false |
You can use the following node to tweak the default behavior:
| Node | Behavior |
| ----- | ----------------------------------------------------------------- |
| `&mo` | [Momentary Layer](../keymaps/behaviors/layers.md#momentary-layer) |
## Layer Toggle
Creates a custom behavior that toggles a layer on, off, or switches between the two states.
@@ -166,10 +189,11 @@ Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-layer-toggle.yaml]
Applies to: `compatible = "zmk,behavior-layer-toggle"`
| Property | Type | Description | Default |
| ---------------- | ---- | ------------------------------ | ------- |
| `#binding-cells` | int | Must be `<1>` | |
| `toggle-mode` | | One of `on`, `off`, and `flip` | `flip` |
| Property | Type | Description | Default |
| ---------------- | ---- | --------------------------------------------------------------- | ------- |
| `#binding-cells` | int | Must be `<1>` | |
| `toggle-mode` | | One of `on`, `off`, and `flip` | `flip` |
| `locking` | bool | Whether the behavior can lock and unlock layers in the on state | false |
You can use the following node to tweak the default behavior:
@@ -177,6 +201,29 @@ You can use the following node to tweak the default behavior:
| ------ | ----------------------------------------------------------- |
| `&tog` | [Layer toggle](../keymaps/behaviors/layers.md#toggle-layer) |
## To Layer
Creates a custom behavior that toggles a layer on and toggles all other layers off, barring the default layer.
See the [to layer behavior](../keymaps/behaviors/layers.md#to-layer) documentation for more details and examples.
### Devicetree
Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-to-layer.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-to-layer.yaml)
Applies to: `compatible = "zmk,behavior-to-layer"`
| Property | Type | Description | Default |
| ---------------- | ---- | --------------------------------------------------------------- | ------- |
| `#binding-cells` | int | Must be `<1>` | |
| `locking` | bool | Whether the behavior can lock and unlock layers in the on state | false |
You can use the following node to tweak the default behavior:
| Node | Behavior |
| ----- | --------------------------------------------------- |
| `&to` | [To Layer](../keymaps/behaviors/layers.md#to-layer) |
## Macro
Creates a custom behavior which triggers a sequence of other behaviors.

9
docs/docs/keymaps/behaviors/layers.md
View File

@@ -82,6 +82,7 @@ Define a new behavior and assign `"on"` or `"off"` to `toggle-mode`:
#binding-cells = <1>;
display-name = "Toggle Layer On";
toggle-mode = "on";
locking;
};
};
};
@@ -89,6 +90,14 @@ Define a new behavior and assign `"on"` or `"off"` to `toggle-mode`:
You can then use `&tog_on` in place of `&tog` whenever you wish to only toggle a layer on, and not toggle it off. An `"off"` version of the behavior can be defined similarly.
## Layer Locking
When the behaviors `&to` and `&tog` toggle a layer on, they will "lock" the layer in the active state. This prevents the layer from being deactivated by any behavior which is not a `&to` or a `&tog`.
In particular, if you activate a layer momentarily using e.g. `&mo 1`, tapping e.g. `&tog 1` as defined above will prevent the layer from deactivating after releasing `&mo 1`. You can then press `&tog 1` again to deactivate the layer.
For custom toggle, to, and momentary layer behaviors, this can be enabled by giving your behavior the `locking;` property.
## Conditional Layers
The "conditional layers" feature enables a particular layer when all layers in a specified set are active.