From bf84481b47fd64bedbfcf665b1dbc09aab5d5029 Mon Sep 17 00:00:00 2001 From: Joel Spadin Date: Fri, 29 Apr 2022 20:20:21 -0500 Subject: [PATCH] feat(docs): Update behavior config docs --- docs/docs/behaviors/caps-word.md | 2 +- docs/docs/config/behaviors.md | 151 +++++++++++++++++++++++++++---- 2 files changed, 135 insertions(+), 18 deletions(-) diff --git a/docs/docs/behaviors/caps-word.md b/docs/docs/behaviors/caps-word.md index 479e350f..1b743a59 100644 --- a/docs/docs/behaviors/caps-word.md +++ b/docs/docs/behaviors/caps-word.md @@ -5,7 +5,7 @@ sidebar_label: Caps Word ## Summary -The caps word behavior behaves similar to a caps lock, but will automatically deactivate when one of the configured "break keycodes" is pressed, or if the caps word key is pressed again. For smaller keyboards, using [mod-taps](/docs/behaviors/mod-tap), this can help avoid repeated alternating holds when typing words in all caps. +The caps word behavior behaves similar to a caps lock, but will automatically deactivate when any key not in a continue list is pressed, or if the caps word key is pressed again. For smaller keyboards using [mod-taps](/docs/behaviors/mod-tap), this can help avoid repeated alternating holds when typing words in all caps. The modifiers are applied only to to the alphabetic (`A` to `Z`) keycodes, to avoid automatically appliying them to numeric values, etc. diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index f8a0df7d..726f2bb2 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -9,6 +9,35 @@ See [Configuration Overview](/docs/config/index) for instructions on how to chan See the [zmk/app/dts/behaviors/](https://github.com/zmkfirmware/zmk/tree/main/app/dts/behaviors) folder for all default behaviors. +## 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. + +See the [caps word behavior](/docs/behaviors/caps-word) documentation for more details and examples. + +### Devicetree + +Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-caps-word.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-caps-word.yaml) + +Applies to: `compatible = "zmk,behavior-caps-word"` + +| Property | Type | Description | Default | +| ---------------- | ------ | ------------------------------------------------------------------ | -------------- | +| `label` | string | Unique label for the node | | +| `#binding-cells` | int | Must be `<0>` | | +| `continue-list` | array | List of [key codes](/docs/codes) which do not deactivate caps lock | `` | +| `mods` | int | A bit field of modifiers to apply | `` | + +`continue-list` is treated as if it always includes alphanumeric characters (A-Z, 0-9). + +See [dt-bindings/zmk/modifiers.h](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/modifiers.h) for a list of modifiers. + +You can use the following nodes to tweak the default behaviors: + +| Node | Behavior | +| ------------ | -------------------------------------- | +| `&caps_word` | [Caps Word](/docs/behaviors/caps-word) | + ## Hold-Tap Creates a custom behavior that triggers one behavior when a key is held or a different one when the key is tapped. @@ -17,45 +46,113 @@ See the [hold-tap behavior documentation](/docs/behaviors/hold-tap) for more det ### Devicetree +Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-hold-tap.yaml) + Applies to: `compatible = "zmk,behavior-hold-tap"` -| Property | Type | Description | Default | -| ----------------- | ------------- | ------------------------------------------------------------------------------ | ------------------ | -| `label` | string | Unique label for the node | | -| `#binding-cells` | int | Must be `<2>` | | -| `bindings` | phandle array | A list of two behaviors: one for hold and one for tap | | -| `tapping-term-ms` | int | How long in milliseconds the key must be held to trigger a hold | | -| `quick-tap-ms` | int | Tap twice within this period in milliseconds to trigger a tap, even when held | -1 | -| `flavor` | string | Adjusts how the behavior chooses between hold and tap | `"hold-preferred"` | -| `retro-tap` | bool | Triggers the tap behavior on release if no other key was pressed during a hold | false | +| Property | Type | Description | Default | +| ---------------------------- | ------------- | ----------------------------------------------------------------------------------------- | ------------------ | +| `label` | string | Unique label for the node | | +| `#binding-cells` | int | Must be `<2>` | | +| `bindings` | phandle array | A list of two behaviors (without parameters): one for hold and one for tap | | +| `flavor` | string | Adjusts how the behavior chooses between hold and tap | `"hold-preferred"` | +| `tapping-term-ms` | int | How long in milliseconds the key must be held to trigger a hold | | +| `quick-tap-ms` | int | Tap twice within this period (in milliseconds) to trigger a tap, even when held | -1 (disabled) | +| `global-quick-tap` | bool | If enabled, `quick-tap-ms` also applies when tapping another key and then this one. | false | +| `retro-tap` | bool | Triggers the tap behavior on release if no other key was pressed during a hold | false | +| `hold-trigger-key-positions` | array | If set, pressing the hold-tap and then any key position _not_ in the list triggers a tap. | | The `flavor` property may be one of: - `"hold-preferred"` - `"balanced"` - `"tap-preferred"` +- `"tap-unless-interrupted"` See the [hold-tap behavior documentation](/docs/behaviors/hold-tap) for an explanation of each flavor. +`hold-trigger-key-positions` is an array of zero-based key position indices. + +You can use the following nodes to tweak the default behaviors: + | Node | Behavior | | ----- | --------------------------------------------- | | `<` | [Layer-tap](/docs/behaviors/layers#layer-tap) | | `&mt` | [Mod-tap](/docs/behaviors/mod-tap) | -## Mod-Morph +## Key Repeat -Creates a custom behavior that triggers one behavior when a key is pressed without certain modifiers held or a different one if certain modifiers are held. +Creates a custom behavior that repeats the whatever key code was last sent. + +See the [key repeat behavior](/docs/behaviors/key-repeat) documentation for more details and examples. ### Devicetree +Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-key-repeat.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-key-repeat.yaml) + +Applies to: `compatible = "zmk,behavior-key-repeat"` + +| Property | Type | Description | Default | +| ---------------- | ------ | -------------------------------- | ----------------- | +| `label` | string | Unique label for the node | | +| `#binding-cells` | int | Must be `<0>` | | +| `usage-pages` | array | List of HID usage pages to track | `` | + +For the `usage-pages` property, use the `HID_USAGE_*` defines from [dt-bindings/zmk/hid_usage_pages.h](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/hid_usage_pages.h). + +You can use the following nodes to tweak the default behaviors: + +| Node | Behavior | +| ------------- | ---------------------------------------- | +| `&key_repeat` | [Key repeat](/docs/behaviors/key-repeat) | + +## Macro + +Creates a custom behavior which triggers a sequence of other behaviors. + +See the [macro behavior](/docs/behaviors/macros) documentation for more details and examples. + +### Devicetree + +Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-macro.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-macro.yaml) + +Applies to: `compatible = "zmk,behavior-macro"` + +| Property | Type | Description | Default | +| ---------------- | ------------- | ----------------------------------------------------------------------------------------------------- | ------- | +| `label` | string | Unique label for the node | | +| `#binding-cells` | int | Must be `<0>` | | +| `bindings` | phandle array | List of behaviors to trigger | | +| `wait-ms` | int | The default time to wait (in milliseconds) before triggering the next behavior. | 100 | +| `tap-ms` | int | The default time to wait (in milliseconds) between the press and release events of a tapped behavior. | 100 | + +The following macro-specific behaviors can be added at any point in the `bindings` list to change how the macro triggers subsequent behaviors. + +| Behavior | Description | +| -------------------------- | ----------------------------------------------------------------------------------------------------- | +| `¯o_tap` | Switches to tap mode | +| `¯o_press` | Switches to press mode | +| `¯o_release` | Switches to release mode | +| `¯o_pause_for_release` | Pauses the macro until the macro key itself is released | +| `¯o_wait_time TIME` | Changes the time to wait (in milliseconds) before triggering the next behavior. | +| `¯o_tap_time TIME` | Changes the time to wait (in milliseconds) between the press and release events of a tapped behavior. | + +## Mod-Morph + +Creates a custom behavior that triggers one of two behaviors depending on whether certain modifiers are held. + +### Devicetree + +Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-mod-morph.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-mod-morph.yaml) + Applies to: `compatible = "zmk,behavior-mod-morph"` -| Property | Type | Description | -| ---------------- | ------------- | ----------------------------------------------------------------------------------- | -| `label` | string | Unique label for the node | -| `#binding-cells` | int | Must be `<0>` | -| `bindings` | phandle array | A list of two behaviors: one for normal press and one for mod morphed press | -| `mods` | int | A bit field of modifiers which will switch to the morph behavior if any are pressed | +| Property | Type | Description | +| ---------------- | ------------- | --------------------------------------------------------------------------------- | +| `label` | string | Unique label for the node | +| `#binding-cells` | int | Must be `<0>` | +| `bindings` | phandle array | A list of two behaviors: one for normal press and one for mod morphed press | +| `mods` | int | A bit field of modifiers. The morph behavior is used if any of these are pressed. | See [dt-bindings/zmk/modifiers.h](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/modifiers.h) for a list of modifiers. @@ -73,6 +170,8 @@ See the [sticky key behavior](/docs/behaviors/sticky-key) and [sticky layer beha ### Devicetree +Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-sticky-key.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-sticky-key.yaml) + Applies to: `compatible = "zmk,behavior-sticky-key"` | Property | Type | Description | Default | @@ -82,6 +181,7 @@ Applies to: `compatible = "zmk,behavior-sticky-key"` | `bindings` | phandle array | A behavior (without parameters) to trigger | | | `release-after-ms` | int | Releases the key after this many milliseconds if no other key is pressed | 1000 | | `quick-release` | bool | Release the sticky key on the next key press instead of release | false | +| `ignore-modifiers` | bool | If enabled, pressing a modifier key does not cancel the sticky key | true | You can use the following nodes to tweak the default behaviors: @@ -89,3 +189,20 @@ You can use the following nodes to tweak the default behaviors: | ----- | -------------------------------------------- | | `&sk` | [Sticky key](/docs/behaviors/sticky-key) | | `&sl` | [Sticky layer](/docs/behaviors/sticky-layer) | + +## Tap Dance + +Creates a custom behavior that triggers a different behavior corresponding to the number of times the key is tapped. + +### Devicetree + +Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-tap-dance.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-tap-dance.yaml) + +Applies to: `compatible = "zmk,behavior-tap-dance"` + +| Property | Type | Description | Default | +| ----------------- | ------------- | -------------------------------------------------------------------------------------------- | ------- | +| `label` | string | Unique label for the node | | +| `#binding-cells` | int | Must be `<0>` | | +| `bindings` | phandle array | A list of behaviors from which to select | | +| `tapping-term-ms` | int | The maximum time (in milliseconds) between taps before an item from `bindings` is triggered. | 200 |