Skip to content

Commit

Permalink
feat(mouse): Updated mouse keys docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
petejohanson committed Apr 10, 2024
1 parent 5cb771f commit 1d06bda
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 5 deletions.
2 changes: 2 additions & 0 deletions docs/docs/behaviors/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 Button Press](mouse-emulation.md#mouse-move) | Emulates mouse movement |
| `&msc` | [Mouse Button Press](mouse-emulation.md#mouse-scroll) | Emulates mouse scrolling |

## Reset behaviors

Expand Down
71 changes: 66 additions & 5 deletions docs/docs/behaviors/mouse-emulation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand All @@ -17,14 +16,12 @@ 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
```

If you use the mouse key press behavior in your keymap, the feature will automatically be enabled for you.

## Mouse Button Defines

To make it easier to encode the HID mouse button numeric values, include
Expand Down Expand Up @@ -69,3 +66,67 @@ This example will send press of the fourth mouse button when the binding is trig
```
&mkp MB4
```

## 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 velocity.

The following defines can be passed for the parameter:

| Define | Action |
| :----------- | :--------- |
| `MOVE_UP` | Move up |
| `MOVE_DOWN` | Move down |
| `MOVE_LEFT` | Move left |
| `MOVE_RIGHT` | Move right |

### Examples

The following will send a scroll down event to the host when pressed/held:

```
&mmv MOVE_DOWN
```

The following will send a scroll left event to the host when pressed/held:

```
&mmv MOVE_LEFT
```

## 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 |
| :----------- | :--------- |
| `MOVE_UP` | Move up |
| `MOVE_DOWN` | Move down |
| `MOVE_LEFT` | Move left |
| `MOVE_RIGHT` | Move right |

### Examples

The following will send a scroll down event to the host when pressed/held:

```
&msc MOVE_DOWN
```

The following will send a scroll left event to the host when pressed/held:

```
&msc MOVE_LEFT
```

0 comments on commit 1d06bda

Please sign in to comment.