Skip to content

Commit

Permalink
docs: Update caps word documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@joelspadin
joelspadin committed Apr 11, 2023
1 parent ac5fee7 commit a33d657
Show file tree
Hide file tree
Showing 2 changed files with 58 additions and 14 deletions.
52 changes: 47 additions & 5 deletions docs/docs/behaviors/caps-word.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 = <UNDERSCORE MINUS>;
continue-list = <UNDERSCORE BACKSPACE DELETE LEFT RIGHT>;
};
/ {
Expand All @@ -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 {
Expand Down Expand Up @@ -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 = <N0 N1 N2 N3 N4 N5 N6 N7 N8 N9 DV_UNDER BACKSPACE DELETE>;
shift-list = <DV_A DV_B DV_C ... DV_Z DV_MINUS>;
};
```

### 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:
Expand Down
20 changes: 11 additions & 9 deletions docs/docs/config/behaviors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 | `<UNDERSCORE BACKSPACE DELETE>` |
| `mods` | int | A bit field of modifiers to apply | `<MOD_LSFT>` |
| `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 | `<UNDERSCORE BACKSPACE DELETE>` |
| `shift-list` | array | List of [key codes](/docs/codes) which should have `mods` applied | `<MINUS>` |
| `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 | `<MOD_LSFT>` |
| `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.

Expand Down

0 comments on commit a33d657

Please sign in to comment.