Skip to content

Commit

Permalink
docs: documented toggle mode changes
Browse files Browse the repository at this point in the history
  • Loading branch information
Nick-Munnich committed Dec 11, 2024
1 parent fb85840 commit 334cbe4
Show file tree
Hide file tree
Showing 3 changed files with 98 additions and 0 deletions.
54 changes: 54 additions & 0 deletions docs/docs/config/behaviors.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,14 @@ See the [zmk/app/dts/behaviors/](https://github.com/zmkfirmware/zmk/tree/main/ap
| --------------------------------- | ---- | ------------------------------------------------------------------------------------ | ------- |
| `CONFIG_ZMK_BEHAVIORS_QUEUE_SIZE` | int | Maximum number of behaviors to allow queueing from a macro or other complex behavior | 64 |

### Devicetree

Definition file: [zmk/app/dts/bindings/behaviors/behavior-metadata.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/behavior-metadata.yaml)

| Property | Type | Description | Default |
| -------------- | ------ | -------------------------------------------------------------------------------- | ------- |
| `display-name` | string | Name of the layer, for use with a display or [ZMK Studio](../features/studio.md) | |

## Caps Word

Creates a custom behavior that behaves similar to a caps lock but deactivates when any key not in a continue list is pressed.
Expand Down Expand Up @@ -123,6 +131,52 @@ You can use the following nodes to tweak the default behaviors:
| ------------- | ------------------------------------------------ |
| `&key_repeat` | [Key repeat](../keymaps/behaviors/key-repeat.md) |

## Key Toggle

Creates a custom behavior that toggles a key code on, off, or switches between the two states.

See the [key toggle behavior](../keymaps/behaviors/key-toggle.md) documentation for more details and examples.

### Devicetree

Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-key-toggle.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-key-toggle.yaml)

Applies to: `compatible = "zmk,behavior-key-toggle"`

| Property | Type | Description | Default |
| ---------------- | ---- | ------------------------------ | ------- |
| `#binding-cells` | int | Must be `<1>` | |
| `toggle-mode` | | One of `on`, `off`, and `flip` | `flip` |

You can use the following node to tweak the default behavior:

| Node | Behavior |
| ----- | ------------------------------------------------ |
| `&kt` | [Key toggle](../keymaps/behaviors/key-toggle.md) |

## Layer Toggle

Creates a custom behavior that toggles a layer on, off, or switches between the two states.

See the [layer toggle behavior](../keymaps/behaviors/layers.md#toggle-layer) documentation for more details and examples.

### Devicetree

Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-layer-toggle.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-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` |

You can use the following node to tweak the default behavior:

| Node | Behavior |
| ------ | ----------------------------------------------------------- |
| `&tog` | [Layer toggle](../keymaps/behaviors/layers.md#toggle-layer) |

## Macro

Creates a custom behavior which triggers a sequence of other behaviors.
Expand Down
22 changes: 22 additions & 0 deletions docs/docs/keymaps/behaviors/key-toggle.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,25 @@ Example:

You can use any keycode that works for `&kp` as parameter to `&kt`, however, [modified keys](../modifiers.mdx#modifier-functions) such as `LA(A)` will be toggled based on the status of the base keycode (in this case `A`).
In other words, modifiers are ignored when determining whether or not the key is currently pressed.

### Configuration

#### Toggle mode

If you wish to ensure that a key is pressed or released, rather than merely toggling, then you can do so with the `toggle-mode` property.
Define a new behavior and assign `"on"` or `"off"` to `toggle-mode`:

```dts
/ {
behaviors {
kt_on: key_toggle_on_only {
compatible = "zmk,behavior-key-toggle";
#binding-cells = <1>;
display-name = "Key Toggle On";
toggle-mode = "on";
};
};
};
```

You can then use `&kt_on` in place of `&kt` whenever you wish to only toggle a key on, and not toggle it off. An `"off"` version of the behavior can be defined similarly.
22 changes: 22 additions & 0 deletions docs/docs/keymaps/behaviors/layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,28 @@ Example:
&tog 3
```

### Configuration

#### Toggle mode

If you wish to ensure that a layer is toggled on or off specifically, rather than switching between the two states, then you can do so with the `toggle-mode` property.
Define a new behavior and assign `"on"` or `"off"` to `toggle-mode`:

```dts
/ {
behaviors {
tog_on: toggle_layer_on_only {
compatible = "zmk,behavior-toggle-layer";
#binding-cells = <1>;
display-name = "Toggle Layer On";
toggle-mode = "on";
};
};
};
```

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.

## Conditional Layers

The "conditional layers" feature enables a particular layer when all layers in a specified set are active.
Expand Down

0 comments on commit 334cbe4

Please sign in to comment.