From e2b97f112790413168738d1b00facc2052ef8ca5 Mon Sep 17 00:00:00 2001
From: Dmitry Tsykunov <>
Date: Sat, 1 May 2021 09:38:57 +0300
Subject: [PATCH] Add mouse behaviour documentation

---
 app/include/dt-bindings/zmk/mouse.h |  5 ++++
 docs/docs/behaviors/mouse-move.md   | 37 +++++++++++++++++++++++++++++
 docs/docs/behaviors/mouse-press.md  | 37 +++++++++++++++++++++++++++++
 docs/docs/behaviors/mouse-wheel.md  | 35 +++++++++++++++++++++++++++
 4 files changed, 114 insertions(+)
 create mode 100644 docs/docs/behaviors/mouse-move.md
 create mode 100644 docs/docs/behaviors/mouse-press.md
 create mode 100644 docs/docs/behaviors/mouse-wheel.md

diff --git a/app/include/dt-bindings/zmk/mouse.h b/app/include/dt-bindings/zmk/mouse.h
index bd7b395ed3d..16766ac1836 100644
--- a/app/include/dt-bindings/zmk/mouse.h
+++ b/app/include/dt-bindings/zmk/mouse.h
@@ -5,6 +5,7 @@
  */
 #pragma once
 
+/* Mouse press behavior */
 /* Left click */
 #define MB1 (0x01)
 #define LCLK (MB1)
@@ -27,6 +28,8 @@
 
 #define MB8 (0x80)
 
+/* Mouse move behavior */
+
 #define MOVE_UP (0x0000FFFF)
 
 #define MOVE_DOWN (0x00000001)
@@ -35,6 +38,8 @@
 
 #define MOVE_RIGHT (0x00010000)
 
+/* Mouse wheel behavior */
+
 #define WHEEL_UP (0x0001)
 
 #define WHEEL_DOWN (0x00FF)
diff --git a/docs/docs/behaviors/mouse-move.md b/docs/docs/behaviors/mouse-move.md
new file mode 100644
index 00000000000..91ef666fdfe
--- /dev/null
+++ b/docs/docs/behaviors/mouse-move.md
@@ -0,0 +1,37 @@
+---
+title: Mouse Move Behavior
+sidebar_label: Mouse Move
+---
+
+## Summary
+
+Mouse move behavior allows to send keycode signals of mouse movement.
+
+Please visit view [`dt-bindings/zmk/mouse.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/mouse.h) for a comprehensive list of signals.
+
+## Keycode Defines
+
+To make it easier to encode the HID keycode numeric values, most keymaps 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:
+
+```
+#include <dt-bindings/zmk/mouse.h>
+```
+
+Doing so makes a set of defines such as `MOVE_UP`, `MOVE_DOWN`, `MOVE_LEFT` and `MOVE_RIGHT` available for use with these behaviors.
+
+## Mouse press
+
+The "mouse move" behavior sends standard keycodes on press/release.
+
+### Behavior Binding
+
+- Reference: `&mmv`
+- Parameter: The keycode usage ID.
+
+Example:
+
+```
+&mmv MOVE_UP
+```
diff --git a/docs/docs/behaviors/mouse-press.md b/docs/docs/behaviors/mouse-press.md
new file mode 100644
index 00000000000..3fad8e5d4cd
--- /dev/null
+++ b/docs/docs/behaviors/mouse-press.md
@@ -0,0 +1,37 @@
+---
+title: Mouse Press Behavior
+sidebar_label: Mouse Press
+---
+
+## Summary
+
+Mouse press behavior allows to send keycode presses and releases of mouse buttons.
+
+Please visit view [`dt-bindings/zmk/mouse.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/mouse.h) for a comprehensive list.
+
+## Keycode Defines
+
+To make it easier to encode the HID keycode numeric values, most keymaps 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:
+
+```
+#include <dt-bindings/zmk/mouse.h>
+```
+
+Doing so makes a set of defines such as `LCLK`, `RCLK`, etc. available for use with these behaviors
+
+## Mouse press
+
+The "mouse press" behavior sends standard keycodes on press/release.
+
+### Behavior Binding
+
+- Reference: `&mp`
+- Parameter: The keycode usage ID.
+
+Example:
+
+```
+&mp LCLK
+```
diff --git a/docs/docs/behaviors/mouse-wheel.md b/docs/docs/behaviors/mouse-wheel.md
new file mode 100644
index 00000000000..5bf21e4cde3
--- /dev/null
+++ b/docs/docs/behaviors/mouse-wheel.md
@@ -0,0 +1,35 @@
+---
+title: Mouse Wheel Behavior
+sidebar_label: Mouse Wheel
+---
+
+## Summary
+
+Mouse wheel behavior allows to send keycode signals of mouse wheel scrolling.
+
+## Keycode Defines
+
+To make it easier to encode the HID keycode numeric values, most keymaps 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:
+
+```
+#include <dt-bindings/zmk/mouse.h>
+```
+
+Doing so makes a set of defines such as `WHEEL_UP`, `WHEEL_DOWN`, `WHEEL_LEFT` and `WHEEL_RIGHT` available for use with these behaviors.
+
+## Mouse wheel
+
+The "mouse wheel" behavior sends standard keycodes on press/release.
+
+### Behavior Binding
+
+- Reference: `&mwh`
+- Parameter: The keycode usage ID.
+
+Example:
+
+```
+&mwh WHEEL_UP
+```