From e8aa576781532e883308bf2aec3a77f68ae3f545 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Sat, 23 Jan 2021 23:50:30 -0500 Subject: refactor(docs): Move combos under Features. * Since combos aren't a behavior, but a new high level keymap feature, move under Features section. --- docs/docs/behaviors/combos.md | 52 ------------------------------------------- docs/docs/features/combos.md | 51 ++++++++++++++++++++++++++++++++++++++++++ docs/docs/intro.md | 2 +- docs/sidebars.js | 2 +- 4 files changed, 53 insertions(+), 54 deletions(-) delete mode 100644 docs/docs/behaviors/combos.md create mode 100644 docs/docs/features/combos.md (limited to 'docs') diff --git a/docs/docs/behaviors/combos.md b/docs/docs/behaviors/combos.md deleted file mode 100644 index e9b0176..0000000 --- a/docs/docs/behaviors/combos.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Combo Behavior -sidebar_label: Combos ---- - -## Summary - -Combo keys are a way to combine multiple keypresses to output a different key. For example, you can hit the Q and W keys on your keyboard to output escape. - -### Configuration - -Combos are specified like this: - -``` -/ { - combos { - compatible = "zmk,combos"; - combo_esc { - timeout-ms = <50>; - key-positions = <0 1>; - bindings = <&kp ESC>; - }; - }; -}; -``` - -- The name of the combo doesn't really matter, but convention is to start the node name with `combo_`. -- The `compatible` property should always be `"zmk,combos"` for combos. -- `timeout-ms` is the number of milliseconds that all keys of the combo must be pressed. -- `key-positions` is an array of key positions. See the info section below about how to figure out the positions on your board. -- `bindings` is the behavior that is activated when the behavior is pressed. -- (advanced) you can specify `slow-release` if you want the combo binding to be released when all key-positions are released. The default is to release the combo as soon as any of the keys in the combo is released. - -:::info - -Key positions are numbered like the keys in your keymap, starting at 0. So, if the first key in your keymap is `Q`, this key is in position `0`. The next key (possibly `W`) will have position 1, etcetera. - -::: - -### Advanced usage - -- Partially overlapping combos like `0 1` and `0 2` are supported. -- Fully overlapping combos like `0 1` and `0 1 2` are supported. -- You are not limited to `&kp` bindings. You can use all ZMK behaviors there, like `&mo`, `&bt`, `&mt`, `<` etc. - -### Advanced configuration - -There are three global combo parameters which are set through KConfig. You can set them in the `.conf` file in the same directory as your keymap file. - -- `CONFIG_ZMK_COMBO_MAX_PRESSED_COMBOS` is the number of combos that can be active at the same time. Default 4. -- `CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY` is the maximum number of combos that can be active on a key position. Defaults to 5. (So you can have 5 separate combos that use position `3` for example) -- `CONFIG_ZMK_COMBO_MAX_KEYS_PER_COMBO` is the maximum number of keys that need to be pressed to activate a combo. Default 4. If you want a combo that triggers when pressing 5 keys, you'd set this to 5 for example. diff --git a/docs/docs/features/combos.md b/docs/docs/features/combos.md new file mode 100644 index 0000000..845bb01 --- /dev/null +++ b/docs/docs/features/combos.md @@ -0,0 +1,51 @@ +--- +title: Combos +--- + +## Summary + +Combo keys are a way to combine multiple keypresses to output a different key. For example, you can hit the Q and W keys on your keyboard to output escape. + +### Configuration + +Combos configured in your `.keymap` file, but are separate from the `keymap` node found there, since they are processed before the normal keymap. They are specified like this: + +``` +/ { + combos { + compatible = "zmk,combos"; + combo_esc { + timeout-ms = <50>; + key-positions = <0 1>; + bindings = <&kp ESC>; + }; + }; +}; +``` + +- The name of the combo doesn't really matter, but convention is to start the node name with `combo_`. +- The `compatible` property should always be `"zmk,combos"` for combos. +- `timeout-ms` is the number of milliseconds that all keys of the combo must be pressed. +- `key-positions` is an array of key positions. See the info section below about how to figure out the positions on your board. +- `bindings` is the behavior that is activated when the behavior is pressed. +- (advanced) you can specify `slow-release` if you want the combo binding to be released when all key-positions are released. The default is to release the combo as soon as any of the keys in the combo is released. + +:::info + +Key positions are numbered like the keys in your keymap, starting at 0. So, if the first key in your keymap is `Q`, this key is in position `0`. The next key (possibly `W`) will have position 1, etcetera. + +::: + +### Advanced usage + +- Partially overlapping combos like `0 1` and `0 2` are supported. +- Fully overlapping combos like `0 1` and `0 1 2` are supported. +- You are not limited to `&kp` bindings. You can use all ZMK behaviors there, like `&mo`, `&bt`, `&mt`, `<` etc. + +### Advanced configuration + +There are three global combo parameters which are set through KConfig. You can set them in the `.conf` file in the same directory as your keymap file. + +- `CONFIG_ZMK_COMBO_MAX_PRESSED_COMBOS` is the number of combos that can be active at the same time. Default 4. +- `CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY` is the maximum number of combos that can be active on a key position. Defaults to 5. (So you can have 5 separate combos that use position `3` for example) +- `CONFIG_ZMK_COMBO_MAX_KEYS_PER_COMBO` is the maximum number of keys that need to be pressed to activate a combo. Default 4. If you want a combo that triggers when pressing 5 keys, you'd set this to 5 for example. diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 2215291..45aadfd 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -26,7 +26,7 @@ ZMK is currently missing some features found in other popular firmware. This tab | [Display Support](features/displays)[^2] | 🚧 | 🚧 | ✅ | | [RGB Underglow](features/underglow) | ✅ | ✅ | ✅ | | One Shot Keys | ✅ | ✅ | ✅ | -| [Combo Keys](behaviors/combos) | ✅ | | ✅ | +| [Combo Keys](features/combos) | ✅ | | ✅ | | Macros | 🚧 | ✅ | ✅ | | Mouse Keys | 💡 | ✅ | ✅ | | Low Active Power Usage | ✅ | | | diff --git a/docs/sidebars.js b/docs/sidebars.js index d095a47..56de3eb 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -10,6 +10,7 @@ module.exports = { ], Features: [ "features/keymaps", + "features/combos", "features/displays", "features/encoders", "features/underglow", @@ -20,7 +21,6 @@ module.exports = { "behaviors/misc", "behaviors/hold-tap", "behaviors/mod-tap", - "behaviors/combos", "behaviors/reset", "behaviors/bluetooth", "behaviors/outputs", -- cgit v1.2.3