diff --git a/app/dts/behaviors/key_tap.dtsi b/app/dts/behaviors/key_tap.dtsi index 9a8067efb..6126469af 100644 --- a/app/dts/behaviors/key_tap.dtsi +++ b/app/dts/behaviors/key_tap.dtsi @@ -7,7 +7,7 @@ #include / { - behaviors { + macros { #if ZMK_BEHAVIOR_OMIT(KTAP) /omit-if-no-ref/ #endif @@ -16,6 +16,7 @@ #binding-cells = <1>; display-name = "Key Tap"; bindings = <¯o_param_1to1>, <&kp MACRO_PLACEHOLDER>; + tap-ms = <30>; }; }; }; diff --git a/docs/docs/keymaps/behaviors/index.mdx b/docs/docs/keymaps/behaviors/index.mdx index 5eb5668b3..8228a48af 100644 --- a/docs/docs/keymaps/behaviors/index.mdx +++ b/docs/docs/keymaps/behaviors/index.mdx @@ -11,15 +11,18 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors ## Key Press Behaviors -| Binding | Behavior | Description | -| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `&kp` | [Key Press](key-press.md) | Send keycodes to the connected host when a key is pressed | -| `&mt` | [Mod Tap](hold-tap.mdx#mod-tap) | Sends a different key press depending on whether a key is held or tapped | -| `&kt` | [Key Toggle](key-toggle.md) | Toggles the press of a key. If the key is not currently pressed, key toggle will press it, holding it until the key toggle is pressed again or the key is released in some other way. If the key is currently pressed, key toggle will release it | -| `&sk` | [Sticky Key](sticky-key.md) | Stays pressed until another key is pressed, then is released. It is often used for modifier keys like shift, which allows typing capital letters without holding it down | -| `&gresc` | [Grave Escape](mod-morph.md#behavior-binding) | Sends Grave Accent `` ` `` keycode if shift or GUI is held, sends Escape keycode otherwise | -| `&caps_word` | [Caps Word](caps-word.md) | Behaves similar to caps lock, but automatically deactivates when any key not in a continue list is pressed, or if the caps word key is pressed again | -| `&key_repeat` | [Key Repeat](key-repeat.md) | Sends again whatever keycode was last sent | +| Binding | Behavior | Description | +| ------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `&kp` | [Key Press](key-press.md) | Send keycodes to the connected host when a key is pressed or released | +| `&ktap` | [Key Tap](key-press.md#key-tap) | Send keycodes to the connected host when a key is pressed | +| `&mt` | [Mod Tap](hold-tap.mdx#mod-tap) | Sends a different key press depending on whether a key is held or tapped | +| `&kt` | [Key Toggle](key-toggle.md) | Toggles the press of a key. If the key is not currently pressed, key toggle will press it, holding it until the key toggle is pressed again or the key is released in some other way. If the key is currently pressed, key toggle will release it | +| `&kt_on` | [Key Toggle](key-toggle.md#toggle-on-and-toggle-off) | Toggles on a key (sends keycode press event) on press | +| `&kt_off` | [Key Toggle](key-toggle.md#toggle-on-and-toggle-off) | Toggles off a key (sends keycode release event) on press | +| `&sk` | [Sticky Key](sticky-key.md) | Stays pressed until another key is pressed, then is released. It is often used for modifier keys like shift, which allows typing capital letters without holding it down | +| `&gresc` | [Grave Escape](mod-morph.md#behavior-binding) | Sends Grave Accent `` ` `` keycode if shift or GUI is held, sends Escape keycode otherwise | +| `&caps_word` | [Caps Word](caps-word.md) | Behaves similar to caps lock, but automatically deactivates when any key not in a continue list is pressed, or if the caps word key is pressed again | +| `&key_repeat` | [Key Repeat](key-repeat.md) | Sends again whatever keycode was last sent | ## Miscellaneous Behaviors @@ -30,13 +33,15 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors ## Layer Navigation Behaviors -| Binding | Behavior | Description | -| ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `&mo` | [Momentary Layer](layers.md#momentary-layer) | Enables a layer while a key is pressed | -| `<` | [Layer-tap](layers.md#layer-tap) | Enables a layer when a key is held, and outputs a key press when the key is only tapped for a short time | -| `&to` | [To Layer](layers.md#to-layer) | Enables a layer and disables all other layers except the default layer | -| `&tog` | [Toggle Layer](layers.md#toggle-layer) | Enables a layer until the layer is manually disabled | -| `&sl` | [Sticky Layer](sticky-layer.md) | Activates a layer until another key is pressed, then deactivates it | +| Binding | Behavior | Description | +| ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `&mo` | [Momentary Layer](layers.md#momentary-layer) | Enables a layer while a key is pressed | +| `<` | [Layer-tap](layers.md#layer-tap) | Enables a layer when a key is held, and outputs a key press when the key is only tapped for a short time | +| `&to` | [To Layer](layers.md#to-layer) | Enables a layer and disables all other layers except the default layer | +| `&tog` | [Toggle Layer](layers.md#toggle-layer) | Enables a layer until the layer is manually disabled | +| `&tog_on` | [Toggle Layer](layers.md#toggle-on-and-toggle-off) | Enables a layer even if the layer is already enabled | +| `&tog_off` | [Toggle Layer](layers.md#toggle-on-and-toggle-off) | Disables a layer even if the layer is already disabled | +| `&sl` | [Sticky Layer](sticky-layer.md) | Activates a layer until another key is pressed, then deactivates it | ## Mouse Emulation Behaviors diff --git a/docs/docs/keymaps/behaviors/key-press.md b/docs/docs/keymaps/behaviors/key-press.md index f60c17761..d46a67e0c 100644 --- a/docs/docs/keymaps/behaviors/key-press.md +++ b/docs/docs/keymaps/behaviors/key-press.md @@ -47,3 +47,32 @@ Example: ```dts &kp A ``` + +## Key Tap + +The "key tap" behavior will send a press followed by a release when you press the behavior, and will do nothing when you release the behavior. + +### Behavior Binding + +- Reference: `&ktap` +- Parameter: The keycode usage ID from the usage page, e.g. `N4` or `A` + +Example: + +```dts +&ktap A +``` + +#### Configuration + +You can adjust the tap duration, i.e. the time between press and release of the key, by changing the `tap-ms` property: + +```dts +&ktap { + tap-ms = <30>; // This is the value already set by default +}; +``` + +:::info +Internally, the key tap behavior is a very simple [macro](./macros.md#defining-parameterized-macros). +::: diff --git a/docs/docs/keymaps/behaviors/key-toggle.md b/docs/docs/keymaps/behaviors/key-toggle.md index 173087cad..d700811b3 100644 --- a/docs/docs/keymaps/behaviors/key-toggle.md +++ b/docs/docs/keymaps/behaviors/key-toggle.md @@ -25,24 +25,11 @@ Example: You can use any keycode that works for `&kp` as parameter to `&kt`, however, [modified keys](../modifiers.mdx#modifier-functions) such as `LA(A)` will be toggled based on the status of the base keycode (in this case `A`). In other words, modifiers are ignored when determining whether or not the key is currently pressed. -### Configuration +### Toggle On and Toggle Off -#### Toggle mode +For state-independent toggles, there exist two further behaviors: -If you wish to ensure that a key is pressed or released, rather than merely toggling, then you can do so with the `toggle-mode` property. -Define a new behavior and assign `"on"` or `"off"` to `toggle-mode`: +- `&kt_on`: Toggles a keycode on, even if it is already on. +- `&kt_off`: Toggles a keycode off, even if it is already off. -```dts -/ { - behaviors { - kt_on: key_toggle_on_only { - compatible = "zmk,behavior-key-toggle"; - #binding-cells = <1>; - display-name = "Key Toggle On"; - toggle-mode = "on"; - }; - }; -}; -``` - -You can then use `&kt_on` in place of `&kt` whenever you wish to only toggle a key on, and not toggle it off. An `"off"` version of the behavior can be defined similarly. +Use these just as you would use `&kt`. diff --git a/docs/docs/keymaps/behaviors/layers.md b/docs/docs/keymaps/behaviors/layers.md index 66501fccd..95c1d30b0 100644 --- a/docs/docs/keymaps/behaviors/layers.md +++ b/docs/docs/keymaps/behaviors/layers.md @@ -67,27 +67,14 @@ Example: &tog 3 ``` -### Configuration +### Toggle On and Toggle Off -#### Toggle mode +For state-independent toggles, there exist two further behaviors: -If you wish to ensure that a layer is toggled on or off specifically, rather than switching between the two states, then you can do so with the `toggle-mode` property. -Define a new behavior and assign `"on"` or `"off"` to `toggle-mode`: +- `&tog_on`: Toggles a layer on, even if it is already on. +- `&tog_off`: Toggles a layer off, even if it is already off. -```dts -/ { - behaviors { - tog_on: toggle_layer_on_only { - compatible = "zmk,behavior-toggle-layer"; - #binding-cells = <1>; - display-name = "Toggle Layer On"; - toggle-mode = "on"; - }; - }; -}; -``` - -You can then use `&tog_on` in place of `&tog` whenever you wish to only toggle a layer on, and not toggle it off. An `"off"` version of the behavior can be defined similarly. +Use these just as you would use `&tog`. ## Conditional Layers diff --git a/docs/docs/keymaps/behaviors/macros.md b/docs/docs/keymaps/behaviors/macros.md index a06efaf37..47decea5d 100644 --- a/docs/docs/keymaps/behaviors/macros.md +++ b/docs/docs/keymaps/behaviors/macros.md @@ -192,6 +192,25 @@ Parameterized macros must be defined using specific values for the `compatible` }; ``` +An example of a simple parameterized macro is `&ktap`, which is defined as: + +```dts +/ { + macros { + ktap: key_tap { + compatible = "zmk,behavior-macro-one-param"; + #binding-cells = <1>; + display-name = "Key Tap"; + bindings = <¯o_param_1to1>, <&kp MACRO_PLACEHOLDER>; + tap-ms = <30>; + }; + }; +}; + +``` + +This behavior is already pre-defined as `&ktap`, so you don't need to define it in your keymap to use it. + ### Parameters, Bindings and Controls There are special macro controls which must be used in order to forward received parameters to the macro's `bindings`. These controls are "one shot" and will determine how received parameters are used on the very next (non-macro control) behavior in the macro's `bindings` list.