diff --git a/docs/docs/behavior/key-press.md b/docs/docs/behavior/key-press.md index 8a69c4f8..08296bb9 100644 --- a/docs/docs/behavior/key-press.md +++ b/docs/docs/behavior/key-press.md @@ -2,4 +2,60 @@ title: Key Presses --- -TODO: Docs on key press behavior +## Summary + +The most basic of behaiors, is the ability to send certain keycode presses and releases in response to activating +a certain key. + +For reference on keycode values, see the [USB HID Usage Tables](https://www.usb.org/document-library/hid-usage-tables-12). + +## Keycode Defines + +To make it easier to encode the HID keycode numeric values, most keymaps include +the [`dt-bindings/zmk/keys.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/keys.h) header +provided by ZMK near the top: + +``` +#include +``` + +Doing so makes a set of defines such as `A`, `NUM_1`, etc. available for use with these behaviors + +:::note +There is an [open issue](https://github.com/zmkfirmware/zmk/issues/21) to provide a more comprehensive, and +complete set of defines for the full keypad and consumer usage pages in the future for ZMK. +::: + +## Keypad Key Press + +The "keypad key press" behavior sends standard keypad keycodes on press/release. + +### Behavior Binding + +- Reference: `&kp` +- Parameter: The keycode usage ID from the keypad usage page, e.g. `4` or `A` + +Example: + +``` +&kp A +``` + +## Consumer Key Press + +The "consumer key press" behavior allows you to send "consumer" usage page keycodes on press/release. +These are mostly used for media and power related keycodes, such as sending "Pause", "Scan Track Next", +"Scan Track Previous", etc. + +There are a subset of the full consumer usage IDs found in the `keys.h` include, prefixed with `M_`, e.g. `M_PREV`. + +### Behavior Binding + +- Reference: `&cp` +- Parameter: The keycode usage ID from the consumer usage page, e.g. `M_PREV` or `M_EJCT` + +Example: + +``` +&cp M_PREV +```