From a33d6570f9cbe35eb765aeacb329c7f20d3ce89f Mon Sep 17 00:00:00 2001 From: Joel Spadin Date: Tue, 11 Apr 2023 15:36:22 -0500 Subject: [PATCH] docs: Update caps word documentation --- docs/docs/behaviors/caps-word.md | 52 +++++++++++++++++++++++++++++--- docs/docs/config/behaviors.md | 20 ++++++------ 2 files changed, 58 insertions(+), 14 deletions(-) diff --git a/docs/docs/behaviors/caps-word.md b/docs/docs/behaviors/caps-word.md index 0475807c6bae..b46698117aff 100644 --- a/docs/docs/behaviors/caps-word.md +++ b/docs/docs/behaviors/caps-word.md @@ -5,9 +5,9 @@ sidebar_label: Caps Word ## Summary -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 caps word behavior behaves similar to a caps lock, but it will automatically deactivate at the end of a word. This is useful for typing single words in all capitals, such as abbreviations or identifiers in code. This is especially useful for smaller keyboards using [mod-taps](/docs/behaviors/mod-tap), where it 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. +When caps word is active, Shift is added to capitalize letters and change `-` to `_`. Caps word deactivates at the end of a word, that is when any key is pressed other than alphanumeric characters, `MINUS`, `UNDERSCORE`, `BACKSPACE`, or `DELETE`. It also deactivates if the caps word key is pressed again, or when the keyboard is idle for 5 seconds. ### Behavior Binding @@ -21,13 +21,35 @@ Example: ### Configuration +#### Shift List + +By default, caps word will apply the Shift modifier to alpha keys and `MINUS`. If you would like to override this, you can set a new array of keys in the `shift-list` property in your keymap. Any keys added to this list will both continue the word and be shifted. + +For example, to remove `MINUS` from the list so it isn't changed to `UNDERSCORE`, add: + +``` +&caps_word { + shift-list = <>; +}; + +/ { + keymap { + ... + }; +}; +``` + +Alpha keys are automatically included in the list. This can be disabled by adding a [`no-default-keys`](#non-us-layouts) property. + #### Continue List -By default, the caps word will remain active when any alphanumeric character or underscore (`UNDERSCORE`), backspace (`BACKSPACE`), or delete (`DELETE`) characters are pressed. Any other non-modifier keycode sent will turn off caps word. If you would like to override this, you can set a new array of keys in the `continue-list` property in your keymap: +By default, caps word will remain active when any alphanumeric key, modifier key, key listed in `shift-list`, or `UNDERSCORE`, `BACKSPACE`, or `DELETE` is pressed. Any other key will turn off caps word. If you would like to override this, you can set a new array of keys in the `continue-list` property in your keymap. Any keys added to this list will continue a word but not be shifted. + +For example, to add left/right arrow keys to the default list, add: ``` &caps_word { - continue-list = ; + continue-list = ; }; / { @@ -37,9 +59,11 @@ By default, the caps word will remain active when any alphanumeric character or }; ``` +Alphanumeric keys are automatically included in the list. This can be disabled by adding a [`no-default-keys`](#non-us-layouts) property. + #### Applied Modifier(s) -In addition, if you would like _multiple_ modifiers, instead of just `MOD_LSFT`, you can override the `mods` property: +In addition, if you would like caps word to apply different or _multiple_ modifiers instead of just `MOD_LSFT`, you can override the `mods` property: ``` &caps_word { @@ -67,6 +91,24 @@ For example, this would change the timeout to 10 seconds: Setting the timeout to 0 configures caps word to never time out. It will remain active until you press a key that turns off caps word. + +### Non-US Layouts + +Alphanumeric keys (A-Z, 0-9) are automatically included in `continue-list`, and alpha keys (A-Z) are automatically included in `shift-list`. This may result in unexpected behaviors for some OS keyboard layouts, for example in Dvorak where the quote key sends the Q keycode, and therefore is treated as continuing a word. You can disable this and manually specify the full lists by adding a `no-default-keys` property: + +``` +// Keycodes for Dvorak layout +#define DV_A A +#define DV_B N +... + +&caps_word { + no-default-keys; + continue-list = ; + shift-list = ; +}; +``` + ### Multiple Caps Breaks If you want to use multiple caps breaks with different codes to break the caps, you can add additional caps words instances to use in your keymap: diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index 3e0145c94c29..df30e0f8506d 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -29,15 +29,17 @@ Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-caps-word.yaml](ht 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 | `` | -| `idle-timeout-ms` | int | Caps word turns off if no key is pressed for this time in milliseconds. 0 = no timeout. | 5000 | - -`continue-list` is treated as if it always includes alphanumeric characters (A-Z, 0-9). +| 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 word | `` | +| `shift-list` | array | List of [key codes](/docs/codes) which should have `mods` applied | `` | +| `no-default-keys` | bool | Do not automatically include alphanumeric keys in `continue-list` and `shift-list` | false | +| `mods` | int | A bit field of modifiers to apply | `` | +| `idle-timeout-ms` | int | Caps word turns off if no key is pressed for this time in milliseconds. 0 = no timeout. | 5000 | + +`continue-list` is treated as if it always includes A-Z and 0-9, and `shift-list` is treated as if it always includes A-Z unless `no-default-keys` is set. 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.