From 3fe439b4aa79ad15e8d2da5572b3affd3651e6bb Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Sun, 18 Aug 2024 00:50:46 +0200 Subject: [PATCH] All Codes and now Keycodes --- docs/blog/2020-11-09-zmk-sotf-3.md | 2 +- docs/blog/2023-10-05-zmk-sotf-6.md | 2 +- docs/docs/codes/_keyboard-consumer.md | 8 -------- docs/docs/config/behaviors.md | 10 +++++----- docs/docs/intro.md | 4 ++-- docs/docs/keymaps/behaviors/key-press.md | 18 +++++++++--------- docs/docs/keymaps/behaviors/key-toggle.md | 2 +- docs/docs/keymaps/behaviors/layers.md | 2 +- docs/docs/keymaps/behaviors/mod-tap.md | 2 +- docs/docs/keymaps/behaviors/tap-dance.mdx | 2 +- ...{list-of-codes.mdx => list-of-keycodes.mdx} | 2 +- docs/docs/keymaps/modifiers.mdx | 8 ++++---- docs/sidebars.js | 2 +- 13 files changed, 28 insertions(+), 36 deletions(-) delete mode 100644 docs/docs/codes/_keyboard-consumer.md rename docs/docs/keymaps/{list-of-codes.mdx => list-of-keycodes.mdx} (98%) diff --git a/docs/blog/2020-11-09-zmk-sotf-3.md b/docs/blog/2020-11-09-zmk-sotf-3.md index 82cd7b6c..1d2acc45 100644 --- a/docs/blog/2020-11-09-zmk-sotf-3.md +++ b/docs/blog/2020-11-09-zmk-sotf-3.md @@ -22,7 +22,7 @@ Tons of activity related to keymaps, so we'll go into more detail this time. #### Codes Overhaul [innovaker] _completely_ overhauled the set of available codes for keymaps, and simultaneously has created -_beautiful_ [documentation](/docs/keymaps/list-of-codes) to help users visualize the codes, and also understand if they are supported on their particular operating system. +_beautiful_ [documentation](/docs/keymaps/list-of-keycodes) to help users visualize the codes, and also understand if they are supported on their particular operating system. This also laid the foundation for the other keymap related changes that are now available. diff --git a/docs/blog/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md index 93cb33ba..5de59407 100644 --- a/docs/blog/2023-10-05-zmk-sotf-6.md +++ b/docs/blog/2023-10-05-zmk-sotf-6.md @@ -75,7 +75,7 @@ Please see the documentation page linked above for usage and more examples. #### Apple Globe key -[ReFil] added support for the `C_AC_NEXT_KEYBOARD_LAYOUT_SELECT` keycode with alias `GLOBE` which acts as the Globe key in macOS and iOS in [#1938](https://github.com/zmkfirmware/zmk/pull/1938). Note that this keycode doesn't exactly behave like a Globe key that is present on an Apple keyboard and its limitations are documented in [this comment](https://github.com/zmkfirmware/zmk/pull/1938#issuecomment-1744579039) thanks to testing by [SethMilliken](https://github.com/SethMilliken). These limitations will be noted in the official [keycodes documentation](/docs/keymaps/list-of-codes) shortly. +[ReFil] added support for the `C_AC_NEXT_KEYBOARD_LAYOUT_SELECT` keycode with alias `GLOBE` which acts as the Globe key in macOS and iOS in [#1938](https://github.com/zmkfirmware/zmk/pull/1938). Note that this keycode doesn't exactly behave like a Globe key that is present on an Apple keyboard and its limitations are documented in [this comment](https://github.com/zmkfirmware/zmk/pull/1938#issuecomment-1744579039) thanks to testing by [SethMilliken](https://github.com/SethMilliken). These limitations will be noted in the official [keycodes documentation](/docs/keymaps/list-of-keycodes) shortly. #### Bug fixes and other improvements diff --git a/docs/docs/codes/_keyboard-consumer.md b/docs/docs/codes/_keyboard-consumer.md deleted file mode 100644 index 2f50ea4b..00000000 --- a/docs/docs/codes/_keyboard-consumer.md +++ /dev/null @@ -1,8 +0,0 @@ -:::info[Keyboard vs. Consumer keycodes] -In the below tables, there are keycode pairs with similar names where one variant has a `K_` prefix and another `C_`. -These variants correspond to similarly named usages from different [HID usage pages](https://usb.org/sites/default/files/hut1_2.pdf#page=16), -namely the "keyboard/keypad" and "consumer" ones respectively. - -In practice, some OS and applications might listen to only one of the variants. -You can use the values in the compatibility columns below to assist you in selecting which one to use. -::: diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index 95b746f7..6914495f 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -29,11 +29,11 @@ Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-caps-word.yaml](ht Applies to: `compatible = "zmk,behavior-caps-word"` -| Property | Type | Description | Default | -| ---------------- | ----- | ---------------------------------------------------------------------------------- | ------------------------------- | -| `#binding-cells` | int | Must be `<0>` | | -| `continue-list` | array | List of [key codes](/docs/keymaps/list-of-codes) which do not deactivate caps lock | `` | -| `mods` | int | A bit field of modifiers to apply | `` | +| Property | Type | Description | Default | +| ---------------- | ----- | ------------------------------------------------------------------------------------ | ------------------------------- | +| `#binding-cells` | int | Must be `<0>` | | +| `continue-list` | array | List of [keycodes](/docs/keymaps/list-of-keycodes) 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). diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 22e17d43..d8d992e7 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -24,8 +24,8 @@ ZMK is currently missing some features found in other popular firmware. This tab | [Keymaps and Layers](keymaps/behaviors/layers.md) | ✅ | ✅ | ✅ | | [Hold-Tap](keymaps/behaviors/hold-tap.mdx) (which includes [Mod-Tap](keymaps/behaviors/mod-tap.md) and [Layer-Tap](keymaps/behaviors/layers.md#layer-tap)) | ✅ | ✅ | ✅ | | [Tap-Dance](keymaps/behaviors/tap-dance.mdx) | ✅ | ✅[^2] | ✅ | -| [Keyboard Codes](keymaps/list-of-codes.mdx#keyboard) | ✅ | ✅ | ✅ | -| [Media](keymaps/list-of-codes.mdx#media-controls) & [Consumer](keymaps/list-of-codes.mdx#consumer-controls) Codes | ✅ | ✅ | ✅ | +| [Keyboard Keycodes](keymaps/list-of-keycodes.mdx#keyboard) | ✅ | ✅ | ✅ | +| [Media](keymaps/list-of-keycodes.mdx#media-controls) & [Consumer](keymaps/list-of-keycodes.mdx#consumer-controls) Codes | ✅ | ✅ | ✅ | | [Encoders](features/encoders.md) | ✅ | ✅ | ✅ | | [Display Support](features/displays.md)[^1] | 🚧 | 🚧 | ✅ | | [RGB Underglow](features/underglow.md) | ✅ | ✅ | ✅ | diff --git a/docs/docs/keymaps/behaviors/key-press.md b/docs/docs/keymaps/behaviors/key-press.md index 2d357fb3..f60c1776 100644 --- a/docs/docs/keymaps/behaviors/key-press.md +++ b/docs/docs/keymaps/behaviors/key-press.md @@ -8,16 +8,16 @@ sidebar_label: Key Press The most basic of behaviors, is the ability to send certain keycode presses and releases in response to activating a certain key. -The categories of supported codes are: +The categories of supported keycodes are: -- [Keyboard](../list-of-codes.mdx#keyboard) -- [Modifiers](../list-of-codes.mdx#modifiers) -- [Keypad](../list-of-codes.mdx#keypad) -- [Editing](../list-of-codes.mdx#editing) -- [Media](../list-of-codes.mdx#media) -- [Applications](../list-of-codes.mdx#applications) -- [Input Assist](../list-of-codes.mdx#input-assist) -- [Power & Lock](../list-of-codes.mdx#power--lock) +- [Keyboard](../list-of-keycodes.mdx#keyboard) +- [Modifiers](../list-of-keycodes.mdx#modifiers) +- [Keypad](../list-of-keycodes.mdx#keypad) +- [Editing](../list-of-keycodes.mdx#editing) +- [Media](../list-of-keycodes.mdx#media) +- [Applications](../list-of-keycodes.mdx#applications) +- [Input Assist](../list-of-keycodes.mdx#input-assist) +- [Power & Lock](../list-of-keycodes.mdx#power--lock) For advanced users, user-defined HID usages are also supported but must be encoded, please see [`dt-bindings/zmk/keys.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/keys.h) for further insight. diff --git a/docs/docs/keymaps/behaviors/key-toggle.md b/docs/docs/keymaps/behaviors/key-toggle.md index a5d27d28..8200b455 100644 --- a/docs/docs/keymaps/behaviors/key-toggle.md +++ b/docs/docs/keymaps/behaviors/key-toggle.md @@ -14,7 +14,7 @@ Example uses for key toggle include shift lock, or `ALT-TAB` window switching wi ### Behavior Binding - Reference: `&kt` -- Parameter: The [keycode](../list-of-codes.mdx), e.g. `LALT` or `DOWN_ARROW` +- Parameter: The [keycode](../list-of-keycodes.mdx), e.g. `LALT` or `DOWN_ARROW` Example: diff --git a/docs/docs/keymaps/behaviors/layers.md b/docs/docs/keymaps/behaviors/layers.md index 2d0e5cad..0dbb0057 100644 --- a/docs/docs/keymaps/behaviors/layers.md +++ b/docs/docs/keymaps/behaviors/layers.md @@ -80,7 +80,7 @@ You can configure a different tapping term or tweak other properties noted in th :::info Functionally, the layer-tap is a [hold-tap](hold-tap.mdx) of the ["tap-preferred" flavor](hold-tap.mdx#flavors) and a [`tapping-term-ms`](hold-tap.mdx#tapping-term-ms) of 200 that takes in a [`momentary layer`](#momentary-layer) and a [keypress](key-press.md) as its "hold" and "tap" parameters, respectively. -For users who want to send a different [keycode](../list-of-codes.mdx) depending on if the same key is held or tapped, see [Mod-Tap](mod-tap.md). +For users who want to send a different [keycode](../list-of-keycodes.mdx) depending on if the same key is held or tapped, see [Mod-Tap](mod-tap.md). Similarly, for users looking to create a keybind like the layer-tap that depending on how long the key is held, invokes behaviors like [sticky keys](sticky-key.md) or [key toggles](key-toggle.md), see [Hold-Tap](hold-tap.mdx). diff --git a/docs/docs/keymaps/behaviors/mod-tap.md b/docs/docs/keymaps/behaviors/mod-tap.md index b4e0c063..5aa73f6b 100644 --- a/docs/docs/keymaps/behaviors/mod-tap.md +++ b/docs/docs/keymaps/behaviors/mod-tap.md @@ -45,7 +45,7 @@ You can configure a different tapping term in your keymap: ``` :::info -Under the hood, the mod-tap is simply a [hold-tap](hold-tap.mdx) of the ["hold-preferred" flavor](hold-tap.mdx#flavors) with a [`tapping-term-ms`](hold-tap.mdx#tapping-term-ms) of 200 that takes in two [keypresses](key-press.md) as its "hold" and "tap" parameters. This means that the mod-tap can be used to invoke **any** [keycode](../list-of-codes.mdx), and is not limited to only activating [modifier keys](../modifiers.mdx) when it is held. +Under the hood, the mod-tap is simply a [hold-tap](hold-tap.mdx) of the ["hold-preferred" flavor](hold-tap.mdx#flavors) with a [`tapping-term-ms`](hold-tap.mdx#tapping-term-ms) of 200 that takes in two [keypresses](key-press.md) as its "hold" and "tap" parameters. This means that the mod-tap can be used to invoke **any** [keycode](../list-of-keycodes.mdx), and is not limited to only activating [modifier keys](../modifiers.mdx) when it is held. For users who want to momentarily access a specific [layer](../index.mdx#layers) while a key is held and send a keycode when the same key is tapped, see [Layer-Tap](layers.md#layer-tap). diff --git a/docs/docs/keymaps/behaviors/tap-dance.mdx b/docs/docs/keymaps/behaviors/tap-dance.mdx index 8e515c88..64bf500e 100644 --- a/docs/docs/keymaps/behaviors/tap-dance.mdx +++ b/docs/docs/keymaps/behaviors/tap-dance.mdx @@ -20,7 +20,7 @@ Defines the maximum elapsed time after the last tap-dance keybind press before a #### `bindings` -An array of one or more keybinds. This list can include [any ZMK keycode](../list-of-codes.mdx) and any listed ZMK behavior, like [hold-taps](hold-tap.mdx), or [sticky keys](sticky-key.md). The index of a keybind in the `bindings` array corresponds to the number of times the tap-dance binding is pressed. For example, in the [basic tap-dance counter](#basic-example-counter) shown below, `&kp N2` is the second binding in the array of `bindings`: we then see an output of `2` when the `td0` binding is pressed twice. +An array of one or more keybinds. This list can include [any ZMK keycode](../list-of-keycodes.mdx) and any listed ZMK behavior, like [hold-taps](hold-tap.mdx), or [sticky keys](sticky-key.md). The index of a keybind in the `bindings` array corresponds to the number of times the tap-dance binding is pressed. For example, in the [basic tap-dance counter](#basic-example-counter) shown below, `&kp N2` is the second binding in the array of `bindings`: we then see an output of `2` when the `td0` binding is pressed twice. The number of bindings in this array also determines the tap-dance's maximum number of keypresses. When a tap-dance reaches its maximum number of keypresses, it will immediately invoke the last behavior in its list of `bindings`, rather than waiting for [`tapping-term-ms`](#tapping-term-ms) to expire before the output is displayed. diff --git a/docs/docs/keymaps/list-of-codes.mdx b/docs/docs/keymaps/list-of-keycodes.mdx similarity index 98% rename from docs/docs/keymaps/list-of-codes.mdx rename to docs/docs/keymaps/list-of-keycodes.mdx index c2e24da7..37619891 100644 --- a/docs/docs/keymaps/list-of-codes.mdx +++ b/docs/docs/keymaps/list-of-keycodes.mdx @@ -1,6 +1,6 @@ --- title: List of Keycodes -sidebar_label: List of Codes +sidebar_label: List of Keycodes --- import OsLegend from "@site/src/components/codes/OsLegend"; diff --git a/docs/docs/keymaps/modifiers.mdx b/docs/docs/keymaps/modifiers.mdx index b368b684..a434c4e2 100644 --- a/docs/docs/keymaps/modifiers.mdx +++ b/docs/docs/keymaps/modifiers.mdx @@ -3,12 +3,12 @@ title: Modifiers sidebar_label: Modifiers --- -Modifiers are the special keyboard keys: _shift_, _alt_, _control_ & _GUI_. Their keycodes can be found in the [list of codes](./list-of-codes.mdx#modifiers). +Modifiers are the special keyboard keys: _shift_, _alt_, _control_ & _GUI_. Their keycodes can be found in the [list of keycodes](./list-of-keycodes.mdx#modifiers). Modifiers can be used both as [keys](#modifier-keys) and as [functions](#modifier-functions). ### Modifier Keys -These act like any other key code. +These act like any other keycode. - e.g. `&kp LEFT_GUI` pushes and releases the left GUI key. @@ -24,9 +24,9 @@ These functions take the form: `XX(code)` - `&kp LC(RA(B))` = `LEFT_CONTROL`+`RIGHT_ALT`+`B` - They can be applied to a modifier keycode to create combined modifier keys: - `&kp LS(LALT)` = `LEFT_SHIFT` + `LEFT_ALT` -- Some basic codes already include a modifier function in their definition: +- Some basic keycodes already include a modifier function in their definition: - `DOLLAR` = `LS(NUMBER_4)` -- There are left- and right-handed versions of each modifier (also see [table in the list of codes](./list-of-codes.mdx#modifiers)): +- There are left- and right-handed versions of each modifier (also see [table in the list of keycodes](./list-of-keycodes.mdx#modifiers)): - `LS(x)`, `LC(x)`, `LA(x)`, `LG(x)`, `RS(x)`, `RC(x)`, `RA(x)`, `RG(x)` - Modified keys can safely be rolled-over. Modifier functions are released when another key is pressed. - Press `&kp LS(A)`, then press `&kp B`, release `&kp LS(A)` and release `&kp B` results in **Ab**. Only the A is capitalized. diff --git a/docs/sidebars.js b/docs/sidebars.js index ac4ddc30..c52d6f09 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -88,7 +88,7 @@ module.exports = { "keymaps/modifiers", "keymaps/combos", "keymaps/conditional-layers", - "keymaps/list-of-codes", + "keymaps/list-of-keycodes", ], }, {