mirror of
https://github.com/zmkfirmware/zmk.git
synced 2026-03-31 18:35:18 -05:00
feat(mouse): Add mouse move and scroll support (#2477)
* feat(mouse): Add mouse move and scroll support
* Use Zephyr input subsystem for all pointers.
* Input processors for modifying events, e.g. scaling, swapping
codes, temporary (mouse) layers, etc.
* Mouse move/scroll behaviors.
* Infrastructure in place for physical pointer input devices.
* feat: Add input split support.
* docs: Add initial pointer docs.
---------
Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
Co-authored-by: Alexander Krikun <krikun98@gmail.com>
Co-authored-by: Robert U <urob@users.noreply.github.com>
Co-authored-by: Shawn Meier <ftc@users.noreply.github.com>
Co-authored-by: Chris Andreae <chris@andreae.gen.nz>
Co-authored-by: Anant Thazhemadam <47104651+thazhemadam@users.noreply.github.com>
Co-authored-by: Erik Tollerud <erik.tollerud@gmail.com>
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
This commit is contained in:
Pete Johanson
GitHub
@@ -43,6 +43,8 @@ Below is a summary of pre-defined behavior bindings and user-definable behaviors
|
||||
| Binding | Behavior | Description |
|
||||
| ------- | ----------------------------------------------------------- | ------------------------------- |
|
||||
| `&mkp` | [Mouse Button Press](mouse-emulation.md#mouse-button-press) | Emulates pressing mouse buttons |
|
||||
| `&mmv` | [Mouse Move](mouse-emulation.md#mouse-move) | Emulates mouse movement |
|
||||
| `&msc` | [Mouse Scroll](mouse-emulation.md#mouse-scroll) | Emulates mouse scrolling |
|
||||
|
||||
## Reset Behaviors
|
||||
|
||||
|
||||
@@ -5,8 +5,7 @@ sidebar_label: Mouse Emulation
|
||||
|
||||
## Summary
|
||||
|
||||
Mouse emulation behaviors send mouse events. Currently, only mouse button presses are supported, but movement
|
||||
and scroll action support is planned for the future.
|
||||
Mouse emulation behaviors send mouse events, including mouse button presses, cursor movement and scrolling.
|
||||
|
||||
:::warning[Refreshing the HID descriptor]
|
||||
|
||||
@@ -17,17 +16,15 @@ The mouse functionality will not work over BLE until that is done.
|
||||
|
||||
## Configuration Option
|
||||
|
||||
This feature can be enabled or disabled explicitly via a config option:
|
||||
To use any of the behaviors documented here, the ZMK mouse feature must be enabled explicitly via a config option:
|
||||
|
||||
```
|
||||
CONFIG_ZMK_MOUSE=y
|
||||
CONFIG_ZMK_POINTING=y
|
||||
```
|
||||
|
||||
If you use the mouse key press behavior in your keymap, the feature will automatically be enabled for you.
|
||||
## Mouse Emulation Defines
|
||||
|
||||
## Mouse Button Defines
|
||||
|
||||
To make it easier to encode the HID mouse button numeric values, include
|
||||
To make it easier to encode the HID mouse button and move/scroll speed numeric values, include
|
||||
the [`dt-bindings/zmk/mouse.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/mouse.h) header
|
||||
provided by ZMK near the top:
|
||||
|
||||
@@ -35,6 +32,15 @@ provided by ZMK near the top:
|
||||
#include <dt-bindings/zmk/mouse.h>
|
||||
```
|
||||
|
||||
Should you wish to override the default movement or scrolling max velocities, you can define the defaults before including the header, e.g.:
|
||||
|
||||
```c
|
||||
#define ZMK_POINTING_DEFAULT_MOVE_VAL 1500 // default: 600
|
||||
#define ZMK_POINTING_DEFAULT_SCRL_VAL 20 // default: 10
|
||||
|
||||
#include <dt-bindings/zmk/mouse.h>
|
||||
```
|
||||
|
||||
## Mouse Button Press
|
||||
|
||||
This behavior can press/release up to 5 mouse buttons.
|
||||
@@ -69,3 +75,133 @@ This example will send press of the fourth mouse button when the binding is trig
|
||||
```
|
||||
&mkp MB4
|
||||
```
|
||||
|
||||
### Input Processors
|
||||
|
||||
If you want to apply any [input processors](../input-processors/index.md#input-processors-overview) to `&mkp` you can do so by referencing `&mkp_input_listener`, e.g.:
|
||||
|
||||
```dts
|
||||
&mkp_input_listener {
|
||||
input-processors = <&zip_temp_layer 2 2000>;
|
||||
}
|
||||
```
|
||||
|
||||
## Mouse Move
|
||||
|
||||
This behavior sends mouse X/Y movement events to the connected host.
|
||||
|
||||
### Behavior Binding
|
||||
|
||||
- Reference: `&mmv`
|
||||
- Parameter: A `uint32` with 16-bits each used for vertical and horizontal max velocity.
|
||||
|
||||
The following predefined values can be passed for the parameter:
|
||||
|
||||
| Define | Action |
|
||||
| :----------- | :--------- |
|
||||
| `MOVE_UP` | Move up |
|
||||
| `MOVE_DOWN` | Move down |
|
||||
| `MOVE_LEFT` | Move left |
|
||||
| `MOVE_RIGHT` | Move right |
|
||||
|
||||
Additionally, if you want to pass a different max speed than the default for the `MOVE_*` defines, custom X and Y velocity values can be passed with `MOVE_X` and `MOVE_Y`, e.g. `MOVE_X(100)` or `MOVE_Y(-100)`. Positive values indicate movement directions right or down. Note that the default value of the max speed depends on [the value of `ZMK_POINTING_DEFAULT_MOVE_VAL`](#mouse-emulation-defines).
|
||||
|
||||
### Examples
|
||||
|
||||
The following will send a down mouse movement event to the host when pressed/held:
|
||||
|
||||
```
|
||||
&mmv MOVE_DOWN
|
||||
```
|
||||
|
||||
The following will send a left mouse movement event to the host when pressed/held:
|
||||
|
||||
```
|
||||
&mmv MOVE_LEFT
|
||||
```
|
||||
|
||||
### Input Processors
|
||||
|
||||
If you want to apply any [input processors](../input-processors/index.md#input-processors-overview) to `&mmv` you can do so by referencing `&mmv_input_listener`, e.g.:
|
||||
|
||||
```dts
|
||||
&mmv_input_listener {
|
||||
input-processors = <&zip_temp_layer 2 2000>;
|
||||
}
|
||||
```
|
||||
|
||||
## Mouse Scroll
|
||||
|
||||
This behavior sends vertical and horizontal scroll events to the connected host.
|
||||
|
||||
### Behavior Binding
|
||||
|
||||
- Reference: `&msc`
|
||||
- Parameter: A `uint32` with 16-bits each used for vertical and horizontal velocity.
|
||||
|
||||
The following defines can be passed for the parameter:
|
||||
|
||||
| Define | Action |
|
||||
| :----------- | :----------- |
|
||||
| `SCRL_UP` | Scroll up |
|
||||
| `SCRL_DOWN` | Scroll down |
|
||||
| `SCRL_LEFT` | Scroll left |
|
||||
| `SCRL_RIGHT` | Scroll right |
|
||||
|
||||
Additionally, if you want to pass a different max speed than the default for the `SCRL_*` defines, custom X and Y velocity values can be passed with `MOVE_X` and `MOVE_Y`, e.g. `MOVE_X(5)` or `MOVE_Y(-5)`. Positive values indicate scroll directions right or up. Note that the default value of the max speed depends on [the value of `ZMK_POINTING_DEFAULT_SCRL_VAL`](#mouse-emulation-defines).
|
||||
|
||||
### Examples
|
||||
|
||||
The following will send a scroll down event to the host when pressed/held:
|
||||
|
||||
```
|
||||
&msc SCRL_DOWN
|
||||
```
|
||||
|
||||
The following will send a scroll left event to the host when pressed/held:
|
||||
|
||||
```
|
||||
&msc SCRL_LEFT
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
If you enabled [smooth scrolling](../../config/pointing.md#kconfig) then you will want to use the same `MOVE_UP`, `MOVE_DOWN`, etc values instead of the smaller `SCRL_*` parameters for more sensible scroll speeds.
|
||||
|
||||
:::
|
||||
|
||||
### Input Processors
|
||||
|
||||
If you want to apply any [input processors](../input-processors/index.md#input-processors-overview) to `&msc` you can do so by referencing `&msc_input_listener`, e.g.:
|
||||
|
||||
```dts
|
||||
&msc_input_listener {
|
||||
input-processors = <&zip_temp_layer 2 2000>;
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
Both `&mmv` and `&msc` are instances of the `"zmk,behavior-input-two-axis"` behavior and can be modified using the [two axis input behavior](../../config/behaviors.md#two-axis-input) configuration properties. The default settings are as follows:
|
||||
|
||||
### Mouse Move
|
||||
|
||||
```dts
|
||||
&mmv {
|
||||
x-input-code = <INPUT_REL_X>;
|
||||
y-input-code = <INPUT_REL_Y>;
|
||||
time-to-max-speed-ms = <300>;
|
||||
acceleration-exponent = <1>;
|
||||
};
|
||||
```
|
||||
|
||||
### Mouse Scroll
|
||||
|
||||
```dts
|
||||
&msc {
|
||||
x-input-code = <INPUT_REL_HWHEEL>;
|
||||
y-input-code = <INPUT_REL_WHEEL>;
|
||||
time-to-max-speed-ms = <300>;
|
||||
acceleration-exponent = <1>;
|
||||
};
|
||||
```
|
||||
|
||||
63
docs/docs/keymaps/input-processors/code-mapper.md
Normal file
63
docs/docs/keymaps/input-processors/code-mapper.md
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Code Mapper Input Processor
|
||||
sidebar_label: Code Mapper
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The code mapper input processor is used to map the code of an event to a new one, e.g. changing a vertical Y movement event into a scroll event.
|
||||
|
||||
## Usage
|
||||
|
||||
When used, a code mapper takes no parameters, as the code mappings are specified in the definition of the specific mapper instance, e.g.:
|
||||
|
||||
```dts
|
||||
&zip_xy_to_scroll_mapper
|
||||
```
|
||||
|
||||
## Pre-Defined Instances
|
||||
|
||||
Three pre-defined instance of the code mapper input processor are available:
|
||||
|
||||
| Reference | Description |
|
||||
| -------------------------- | ----------------------------------------------------------------------- |
|
||||
| `&zip_xy_to_scroll_mapper` | Map X/Y movement events to horizontal wheel/wheel events, respectively. |
|
||||
| `&zip_xy_swap_mapper` | Map X to Y, and Y to X for movements. |
|
||||
|
||||
Note that swapping X and Y movements can also be accomplished with the [transformer](transformer.md#pre-defined-instances) processors.
|
||||
|
||||
## User-Defined Instances
|
||||
|
||||
Users can define new instances of the code mapper input processor if they want to target different codes.
|
||||
|
||||
### Example
|
||||
|
||||
Below example maps the left mouse button code to the middle mouse button.
|
||||
|
||||
```dts
|
||||
#include <zephyr/dt-bindings/input/input-event-codes.h>
|
||||
|
||||
/ {
|
||||
input_processors {
|
||||
zip_click_to_middle_click_mapper: zip_click_to_middle_click_mapper {
|
||||
compatible = "zmk,input-processor-code-mapper";
|
||||
#input-processor-cells = <0>;
|
||||
type = <INPUT_EV_KEY>;
|
||||
map = <INPUT_BTN_0 INPUT_BTN_2>;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Compatible
|
||||
|
||||
The code mapper input processor uses a `compatible` property of `"zmk,input-processor-code-mapper"`.
|
||||
|
||||
### Standard Properties
|
||||
|
||||
- `#input-processor-cells` - required to be constant value of `<0>`.
|
||||
|
||||
### User Properties
|
||||
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events and `INPUT_EV_KEY` for key/button events.
|
||||
- `map` - The specific codes of the given type to map, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245). This list must be an even number of entries which is processed as a list of pairs of codes. The first code in the pair is the source code, and the second is the code to map it to.
|
||||
50
docs/docs/keymaps/input-processors/index.md
Normal file
50
docs/docs/keymaps/input-processors/index.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Input Processor Overview
|
||||
sidebar_label: Overview
|
||||
---
|
||||
|
||||
## Input Processors Overview
|
||||
|
||||
"Input processors" are small pieces of functionality that process and optionally modify events generated from emulated and physical pointing devices. Processors can do things like scaling movement values to make them larger or smaller for detailed work, swapping the event types to turn movements into scroll events, or temporarily enabling an extra layer while the pointer is in use.
|
||||
|
||||
## Usage
|
||||
|
||||
For information on using input processors with a given pointing device, see [input processor usage](usage.md).
|
||||
|
||||
## Available Processors
|
||||
|
||||
Below is a summary of pre-defined input processors and user-definable input processors available in ZMK, with references to documentation pages describing them.
|
||||
|
||||
### Pre-Defined Processors
|
||||
|
||||
A set of predefined input processors is available by adding the following at the top of your keymap/overlay file:
|
||||
|
||||
```
|
||||
#include <input/processors.dtsi>
|
||||
```
|
||||
|
||||
Once included, you can use the following:
|
||||
|
||||
| Binding | Processor | Description |
|
||||
| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| `&zip_xy_scaler` | [XY Scaler](scaler.md#pre-defined-instances) | Scale a the X/Y input events using a multiplier and divisor |
|
||||
| `&zip_x_scaler` | [X Scaler](scaler.md#pre-defined-instances) | Scale a the X input events using a multiplier and divisor |
|
||||
| `&zip_y_scaler` | [Y Scaler](scaler.md#pre-defined-instances) | Scale a the Y input events using a multiplier and divisor |
|
||||
| `&zip_xy_transform` | [XY Transform](transformer.md#pre-defined-instances) | Transform X/Y values, e.g. inverting or swapping |
|
||||
| `&zip_scroll_transform` | [Scroll Transform](transformer.md#pre-defined-instances) | Transform wheel/horizontal wheel values, e.g. inverting or swapping |
|
||||
| `&zip_xy_to_scroll_mapper` | [XY To Scroll Mapper](code-mapper.md#pre-defined-instances) | Map X/Y values to scroll wheel/horizontal wheel events |
|
||||
| `&zip_xy_swap_mapper` | [XY Swap Mapper](code-mapper.md#pre-defined-instances) | Swap X/Y values |
|
||||
| `&zip_temp_layer` | [Temporary Layer](temp-layer.md#pre-defined-instances) | Temporarily enable a layer during pointer use |
|
||||
|
||||
### User-Defined Processors
|
||||
|
||||
Several of the input processors that have predefined instances, e.g. `&zip_xy_scaler` or `&zip_xy_to_scroll_mapper` can also have new instances created with custom properties around which input codes to scale, or which codes to map, etc.
|
||||
|
||||
| Compatible | Processor | Description |
|
||||
| --------------------------------- | ---------------------------------------------------- | ------------------------------------------------ |
|
||||
| `zmk,input-processor-transform` | [Transform](transformer.md#user-defined-instances) | Perform various transforms like inverting values |
|
||||
| `zmk,input-processor-code-mapper` | [Code Mapper](code-mapper.md#user-defined-instances) | Map one event code to another type |
|
||||
|
||||
## External Processors
|
||||
|
||||
Much like behaviors, custom input processors can also be added to [external modules](../../features/modules.mdx) to allow complete control of the processing operation. See [`input_processor.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/drivers/input_processor.h) for the definition of the driver API.
|
||||
76
docs/docs/keymaps/input-processors/scaler.md
Normal file
76
docs/docs/keymaps/input-processors/scaler.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Scaler Input Processor
|
||||
sidebar_label: Scaler
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The scaler input processor is used to scale the value of an input event that has a code matching the codes set on the scaler. Events with other codes will be ignored. Values are scaled by multiplying by the multiplier parameter, and then dividing by the divisor parameter.
|
||||
|
||||
## Usage
|
||||
|
||||
When used, a scaler takes two parameters that are positive integers, a multiplier and a divisor, e.g.:
|
||||
|
||||
```dts
|
||||
&zip_xy_scaler 2 1
|
||||
```
|
||||
|
||||
which will double all the X/Y movement, or:
|
||||
|
||||
```dts
|
||||
&zip_xy_scaler 1 3
|
||||
```
|
||||
|
||||
which will make movements more granular by reducing the speed to one third.
|
||||
|
||||
:::warning
|
||||
|
||||
A maximum value of `16` should be used for the multiplier and divisor parameters to avoid overflows.
|
||||
|
||||
:::
|
||||
|
||||
## Pre-Defined Instances
|
||||
|
||||
Three pre-defined instance of the scaler input processor are available:
|
||||
|
||||
| Reference | Description |
|
||||
| ---------------- | --------------------------------------------- |
|
||||
| `&zip_xy_scaler` | Scale X- and Y-axis values by the same amount |
|
||||
| `&zip_x_scaler` | Scale X-axis values |
|
||||
| `&zip_y_scaler` | Scale Y-axis values |
|
||||
|
||||
## User-Defined Instances
|
||||
|
||||
Users can define new instances of the scaler input processor if they want to target different codes.
|
||||
|
||||
### Example
|
||||
|
||||
```dts
|
||||
#include <zephyr/dt-bindings/input/input-event-codes.h>
|
||||
|
||||
/ {
|
||||
input_processors {
|
||||
zip_wheel_scaler: zip_wheel_scaler {
|
||||
compatible = "zmk,input-processor-scaler";
|
||||
#input-processor-cells = <2>;
|
||||
type = <INPUT_EV_REL>;
|
||||
codes = <INPUT_REL_WHEEL>;
|
||||
track-remainders;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Compatible
|
||||
|
||||
The scaler input processor uses a `compatible` property of `"zmk,input-processor-scaler"`.
|
||||
|
||||
### Standard Properties
|
||||
|
||||
- `#input-processor-cells` - required to be constant value of `<2>`.
|
||||
- `track-remainders` - boolean flag that indicates callers should allow the processor to track remainders between events.
|
||||
|
||||
### User Properties
|
||||
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events.
|
||||
- `codes` - The specific codes within the given type to scale, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
|
||||
58
docs/docs/keymaps/input-processors/temp-layer.md
Normal file
58
docs/docs/keymaps/input-processors/temp-layer.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Temporary Layer Input Processor
|
||||
sidebar_label: Temporary Layer
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The temporary layer input processor is used to enable a layer when input events are received, and automatically disable it when no further events are received in the given timeout duration. This most frequently is used to temporarily enable a layer with a set of [mouse button emulation behaviors](../behaviors/mouse-emulation.md#mouse-button-press) on it, so you can press various mouse buttons with the normal keyboard keys while using a physical pointer device for X/Y movement.
|
||||
|
||||
## Usage
|
||||
|
||||
When used, the temporary layer input processor takes two parameters, the layer index to enable and a timeout value in milliseconds:
|
||||
|
||||
```dts
|
||||
&zip_temp_layer 2 2000
|
||||
```
|
||||
|
||||
Above example enables the third layer and automatically disables it again after 2 seconds with no events from this pointing device.
|
||||
|
||||
## Pre-Defined Instances
|
||||
|
||||
One pre-defined instance of the temporary layer input processor is available:
|
||||
|
||||
| Reference | Description |
|
||||
| ----------------- | --------------------------------------------------------------- |
|
||||
| `&zip_temp_layer` | Enable a certain layer temporarily until no events are received |
|
||||
|
||||
## User-Defined Instances
|
||||
|
||||
Users can define new instances of the temporary layer input processor to use different settings.
|
||||
|
||||
### Example
|
||||
|
||||
```dts
|
||||
#include <zephyr/dt-bindings/input/input-event-codes.h>
|
||||
|
||||
/ {
|
||||
/omit-if-no-ref/ zip_temp_layer: zip_temp_layer {
|
||||
compatible = "zmk,input-processor-temp-layer";
|
||||
#input-processor-cells = <2>;
|
||||
require-prior-idle-ms = <2000>;
|
||||
excluded-positions = <1 2 3>;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Compatible
|
||||
|
||||
The temp layer input processor uses a `compatible` property of `"zmk,input-processor-temp-layer"`.
|
||||
|
||||
### Standard Properties
|
||||
|
||||
- `#input-processor-cells` - required to be constant value of `<2>`.
|
||||
|
||||
### User Properties
|
||||
|
||||
- `require-prior-idle-ms` - Only activate the layer if there have not been any key presses for at least the set number of milliseconds before the pointing device event
|
||||
- `excluded-positions` - List of (zero-based) key positions to exclude from deactivating the layer once it is active.
|
||||
75
docs/docs/keymaps/input-processors/transformer.md
Normal file
75
docs/docs/keymaps/input-processors/transformer.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: Transformer Input Processor
|
||||
sidebar_label: Transformer
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The transformer input processor is used to perform various transforms on the value of an input event that has a code matching the codes set on the transformer. Events with other codes will be ignored.
|
||||
|
||||
## Available Transforms
|
||||
|
||||
The following transforms are available, by including
|
||||
the [`dt-bindings/zmk/input_transform.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/input_transform.h) header
|
||||
provided by ZMK near the top of your keymap/overlay:
|
||||
|
||||
```
|
||||
#include <dt-bindings/zmk/input_transform.h>
|
||||
```
|
||||
|
||||
- `INPUT_TRANSFORM_XY_SWAP` - When encountering a value with matching type, swap the type of the event to the other axis, e.g. change an event of type `INPUT_REL_X` to type `INPUT_REL_Y`.
|
||||
- `INPUT_TRANSFORM_X_INVERT` - Invert the values of any events that match the configured `x-codes` of the processor, by multiplying by negative one.
|
||||
- `INPUT_TRANSFORM_Y_INVERT` - Invert the values of any events that match the configured `y-codes` of the processor, by multiplying by negative one.
|
||||
|
||||
## Usage
|
||||
|
||||
When used, a transformer takes one parameter, a combination of flags indicating which transforms to apply:
|
||||
|
||||
```dts
|
||||
&zip_xy_transform (INPUT_TRANSFORM_X_INVERT | INPUT_TRANSFORM_Y_INVERT)
|
||||
```
|
||||
|
||||
## Pre-Defined Instances
|
||||
|
||||
Three pre-defined instance of the scaler input processor are available:
|
||||
|
||||
| Reference | Description |
|
||||
| ----------------------- | ------------------------------------------------------------- |
|
||||
| `&zip_xy_transform` | Applies the given transforms to X/Y movement events |
|
||||
| `&zip_scroll_transform` | Applies the given transforms to wheel/horizontal wheel events |
|
||||
|
||||
## User Defined Instances
|
||||
|
||||
Users can define new instances of the transform input processor if they want to target different codes.
|
||||
|
||||
### Example
|
||||
|
||||
```dts
|
||||
#include <zephyr/dt-bindings/input/input-event-codes.h>
|
||||
|
||||
/ {
|
||||
input_processors {
|
||||
my_rotation_event_transform: my_rotation_event_transform {
|
||||
compatible = "zmk,input-processor-transform";
|
||||
#input-processor-cells = <1>;
|
||||
type = <INPUT_EV_REL>;
|
||||
x-codes = <INPUT_REL_RX>;
|
||||
y-codes = <INPUT_REL_RY>;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Compatible
|
||||
|
||||
The transform input processor uses a `compatible` property of `"zmk,input-processor-transform"`.
|
||||
|
||||
### Standard Properties
|
||||
|
||||
- `#input-processor-cells` - required to be constant value of `<1>`.
|
||||
|
||||
### User Properties
|
||||
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to transform. Usually, this is `INPUT_EV_REL` for relative events.
|
||||
- `x-codes` - The specific X codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
|
||||
- `y-codes` - The specific Y codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
|
||||
59
docs/docs/keymaps/input-processors/usage.md
Normal file
59
docs/docs/keymaps/input-processors/usage.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Input Processor Usage
|
||||
sidebar_label: Usage
|
||||
---
|
||||
|
||||
Input processors are used by assigning them to a given [input listener](../../features/pointing.md#input-listeners). A base set of processors is assigned to a listener, and then overrides can be set that are only active when certain [layers](../index.mdx#layers) are active. The examples in the following assume you are adding processors to the `&trackpad` device which is set up with a `&trackpad_listener`.
|
||||
|
||||
### Base Processors
|
||||
|
||||
Base processors are assigned in the `input-processors` property, and when events are generated, the events are process in the sequence in the order the processors are listed. For example, if you wanted your trackpad to always scale the values to increase the movements, you would assign the [scaler](scaler.md#pre-defined-instances) input processor to the property:
|
||||
|
||||
```dts
|
||||
#include <input/processors.dtsi>
|
||||
|
||||
&trackpad_listener {
|
||||
input-processors = <&zip_xy_scaler 3 2>;
|
||||
}
|
||||
```
|
||||
|
||||
### Layer Specific Overrides
|
||||
|
||||
Additional overrides can be added that only apply when the associated layer is active. For example, to make the trackpad work as a scroll device when your layer `1` is active, nest a child node on the listener and set the `layers` and `input-processors` properties:
|
||||
|
||||
```dts
|
||||
#include <input/processors.dtsi>
|
||||
|
||||
&trackpad_listener {
|
||||
input-processors = <&zip_xy_scaler 3 2>;
|
||||
|
||||
scroller {
|
||||
layers = <1>;
|
||||
input-processors = <&zip_xy_to_scroll_mapper>;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
Overrides are processed in the order they are declared, from top to bottom, followed by the base processors in the parent node. Their application order is _not_ in any way tied to the layers specified in the `layers` property.
|
||||
|
||||
:::
|
||||
|
||||
By default, the first-defined override node that matches the layer specification will apply, in which case and any other overrides or the base processors will be skipped. If you add the `process-next;` property to a child node, the other processors will continue to be checked and applied even if that node's layer filter matches.
|
||||
|
||||
```dts
|
||||
#include <input/processors.dtsi>
|
||||
|
||||
&trackpad_listener {
|
||||
input-processors = <&zip_xy_scaler 3 2>;
|
||||
|
||||
scroller {
|
||||
layers = <1>;
|
||||
input-processors = <&zip_xy_to_scroll_mapper>;
|
||||
process-next;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
For more details, see the [Input Listener configuration](../../config/pointing.md#input-listener) section.
|
||||
Reference in New Issue
Block a user