zmkfirmware
/
zmk
mirror of https://github.com/zmkfirmware/zmk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Document the new predefined behaviors 

Reorganising the pages of the docs can be done in a followup PR.

Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
This commit is contained in:
Nicolas Munnich 2025-05-15 21:20:11 +00:00
parent 1e56aa9259
commit b708d684a5
6 changed files with 81 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
app/dts/behaviors/key_tap.dtsi
View File

@ -7,7 +7,7 @@
#include <dt-bindings/zmk/behaviors.h>
/ {
behaviors {
macros {
#if ZMK_BEHAVIOR_OMIT(KTAP)
/omit-if-no-ref/
#endif
@ -16,6 +16,7 @@
#binding-cells = <1>;
display-name = "Key Tap";
bindings = <&macro_param_1to1>, <&kp MACRO_PLACEHOLDER>;
tap-ms = <30>;
};
};
};

37
docs/docs/keymaps/behaviors/index.mdx
View File

@ -11,15 +11,18 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
## Key Press Behaviors
| Binding | Behavior | Description |
| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `&kp` | [Key Press](key-press.md) | Send keycodes to the connected host when a key is pressed |
| `&mt` | [Mod Tap](hold-tap.mdx#mod-tap) | Sends a different key press depending on whether a key is held or tapped |
| `&kt` | [Key Toggle](key-toggle.md) | Toggles the press of a key. If the key is not currently pressed, key toggle will press it, holding it until the key toggle is pressed again or the key is released in some other way. If the key is currently pressed, key toggle will release it |
| `&sk` | [Sticky Key](sticky-key.md) | Stays pressed until another key is pressed, then is released. It is often used for modifier keys like shift, which allows typing capital letters without holding it down |
| `&gresc` | [Grave Escape](mod-morph.md#behavior-binding) | Sends Grave Accent `` ` `` keycode if shift or GUI is held, sends Escape keycode otherwise |
| `&caps_word` | [Caps Word](caps-word.md) | Behaves similar to caps lock, but automatically deactivates when any key not in a continue list is pressed, or if the caps word key is pressed again |
| `&key_repeat` | [Key Repeat](key-repeat.md) | Sends again whatever keycode was last sent |
| Binding | Behavior | Description |
| ------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `&kp` | [Key Press](key-press.md) | Send keycodes to the connected host when a key is pressed or released |
| `&ktap` | [Key Tap](key-press.md#key-tap) | Send keycodes to the connected host when a key is pressed |
| `&mt` | [Mod Tap](hold-tap.mdx#mod-tap) | Sends a different key press depending on whether a key is held or tapped |
| `&kt` | [Key Toggle](key-toggle.md) | Toggles the press of a key. If the key is not currently pressed, key toggle will press it, holding it until the key toggle is pressed again or the key is released in some other way. If the key is currently pressed, key toggle will release it |
| `&kt_on` | [Key Toggle](key-toggle.md#toggle-on-and-toggle-off) | Toggles on a key (sends keycode press event) on press |
| `&kt_off` | [Key Toggle](key-toggle.md#toggle-on-and-toggle-off) | Toggles off a key (sends keycode release event) on press |
| `&sk` | [Sticky Key](sticky-key.md) | Stays pressed until another key is pressed, then is released. It is often used for modifier keys like shift, which allows typing capital letters without holding it down |
| `&gresc` | [Grave Escape](mod-morph.md#behavior-binding) | Sends Grave Accent `` ` `` keycode if shift or GUI is held, sends Escape keycode otherwise |
| `&caps_word` | [Caps Word](caps-word.md) | Behaves similar to caps lock, but automatically deactivates when any key not in a continue list is pressed, or if the caps word key is pressed again |
| `&key_repeat` | [Key Repeat](key-repeat.md) | Sends again whatever keycode was last sent |
## Miscellaneous Behaviors
@ -30,13 +33,15 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
## Layer Navigation Behaviors
| Binding | Behavior | Description |
| ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `&mo` | [Momentary Layer](layers.md#momentary-layer) | Enables a layer while a key is pressed |
| `&lt` | [Layer-tap](layers.md#layer-tap) | Enables a layer when a key is held, and outputs a key press when the key is only tapped for a short time |
| `&to` | [To Layer](layers.md#to-layer) | Enables a layer and disables all other layers except the default layer |
| `&tog` | [Toggle Layer](layers.md#toggle-layer) | Enables a layer until the layer is manually disabled |
| `&sl` | [Sticky Layer](sticky-layer.md) | Activates a layer until another key is pressed, then deactivates it |
| Binding | Behavior | Description |
| ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `&mo` | [Momentary Layer](layers.md#momentary-layer) | Enables a layer while a key is pressed |
| `&lt` | [Layer-tap](layers.md#layer-tap) | Enables a layer when a key is held, and outputs a key press when the key is only tapped for a short time |
| `&to` | [To Layer](layers.md#to-layer) | Enables a layer and disables all other layers except the default layer |
| `&tog` | [Toggle Layer](layers.md#toggle-layer) | Enables a layer until the layer is manually disabled |
| `&tog_on` | [Toggle Layer](layers.md#toggle-on-and-toggle-off) | Enables a layer even if the layer is already enabled |
| `&tog_off` | [Toggle Layer](layers.md#toggle-on-and-toggle-off) | Disables a layer even if the layer is already disabled |
| `&sl` | [Sticky Layer](sticky-layer.md) | Activates a layer until another key is pressed, then deactivates it |
## Mouse Emulation Behaviors

29
docs/docs/keymaps/behaviors/key-press.md
View File

@ -47,3 +47,32 @@ Example:
```dts
&kp A
```
## Key Tap
The "key tap" behavior will send a press followed by a release when you press the behavior, and will do nothing when you release the behavior.
### Behavior Binding
- Reference: `&ktap`
- Parameter: The keycode usage ID from the usage page, e.g. `N4` or `A`
Example:
```dts
&ktap A
```
#### Configuration
You can adjust the tap duration, i.e. the time between press and release of the key, by changing the `tap-ms` property:
```dts
&ktap {
tap-ms = <30>; // This is the value already set by default
};
```
:::info
Internally, the key tap behavior is a very simple [macro](./macros.md#defining-parameterized-macros).
:::

23
docs/docs/keymaps/behaviors/key-toggle.md
View File

@ -25,24 +25,11 @@ 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 On and Toggle Off
#### Toggle mode
For state-independent toggles, there exist two further behaviors:
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`:
- `&kt_on`: Toggles a keycode on, even if it is already on.
- `&kt_off`: Toggles a keycode off, even if it is already off.
```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.
Use these just as you would use `&kt`.

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

@ -67,27 +67,14 @@ Example:
&tog 3
```
### Configuration
### Toggle On and Toggle Off
#### Toggle mode
For state-independent toggles, there exist two further behaviors:
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`:
- `&tog_on`: Toggles a layer on, even if it is already on.
- `&tog_off`: Toggles a layer off, even if it is already off.
```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.
Use these just as you would use `&tog`.
## Conditional Layers

19
docs/docs/keymaps/behaviors/macros.md
View File

@ -192,6 +192,25 @@ Parameterized macros must be defined using specific values for the `compatible`
};
```
An example of a simple parameterized macro is `&ktap`, which is defined as:
```dts
/ {
macros {
ktap: key_tap {
compatible = "zmk,behavior-macro-one-param";
#binding-cells = <1>;
display-name = "Key Tap";
bindings = <&macro_param_1to1>, <&kp MACRO_PLACEHOLDER>;
tap-ms = <30>;
};
};
};
```
This behavior is already pre-defined as `&ktap`, so you don't need to define it in your keymap to use it.
### Parameters, Bindings and Controls
There are special macro controls which must be used in order to forward received parameters to the macro's `bindings`. These controls are "one shot" and will determine how received parameters are used on the very next (non-macro control) behavior in the macro's `bindings` list.