From 9dcd683c248af62d275c30eeb3a5aad968052d6e Mon Sep 17 00:00:00 2001
From: xs5871 <xs5871@qn-4.net>
Date: Sun, 18 Aug 2024 19:58:43 +0000
Subject: [PATCH] Add docs for pimoroni trackball handlers

---
 docs/en/pimoroni_trackball.md | 89 +++++++++++++++++++++++++++++++----
 1 file changed, 80 insertions(+), 9 deletions(-)

diff --git a/docs/en/pimoroni_trackball.md b/docs/en/pimoroni_trackball.md
index b08ce9f3b..650e63978 100644
--- a/docs/en/pimoroni_trackball.md
+++ b/docs/en/pimoroni_trackball.md
@@ -2,7 +2,7 @@
 
 Module handles usage of Trackball Breakout by Pimoroni.
 
-### Usage
+## Usage
 
 Declare I2C bus and add this module in your main class.
 
@@ -17,8 +17,79 @@ keyboard.modules.append(trackball)
 
 Module will also work when you cannot use `busio` and do `import bitbangio as io` instead.
 
-### Key inputs, other handler combinations
+## Key inputs, other handler combinations
 
+### Builtin handlers
+
+There are a couple of builtin handlers for your convenience.
+All parameters are show with their default values, optional parameters can be
+omitted.
+
+#### PointingHandler
+
+Plain pointing device, i.e. a mouse:
+
+```python
+PointingHandler(
+    # optional:
+    on_press=KC.MB_LMB,
+)
+```
+
+#### ScrollHandler
+
+Make the Trackball act as a 2D scroll wheel.
+The default scroll direction is `NATURAL` and can be set to `ScrollDirection.REVERSE`
+if the Apple behavior is prefered.
+
+```python
+ScrollHandler(
+    # optional:
+    scroll_direction=ScrollDirection.NATURAL,
+    on_press=KC.MB_LMB,
+)
+```
+
+#### KeyHandler
+
+Emit key presses instead of movement:
+
+```python
+KeyHandler(
+    up,            # key for the up direction
+    right,         # key for the right direction
+    down,          # key for the down direction
+    left,          # key for the left direction
+    press,         # key for pressing the trackball
+    # optional:
+    axis_snap=.25, # diagonal quantization accuracy
+    steps=8,       # amount of rotational angle for one key tap
+)
+```
+
+#### Custom Handler Example
+
+Here's an example for a custom handler that scrolls up and down, holds keys
+for left and right, and press is middle mouse button:
+
+```python
+from kmk.modules.pimoroni_trackball import TrackballHandler
+
+CustomHandler(TrackballHandler):
+    def handle(self, keyboard, trackball, x, y, switch, state):
+        if x > 0:
+            keyboard.tap_key(KC.RIGHT)
+        elif x < 0:
+            keyboard.tap_key(KC.LEFT)
+
+        if y != 0:
+            AX.W.move(keyboard, y)
+
+        if switch:
+            keyboard.pre_process_key(KC.MB_MMB, is_pressed=state)
+```
+
+### Assigning Handlers
 If you have used this thing on a mobile device, you will know it excels at cursor movement
 
 ```python
@@ -26,15 +97,15 @@ If you have used this thing on a mobile device, you will know it excels at curso
 from kmk.modules.pimoroni_trackball import Trackball, TrackballMode, PointingHandler, KeyHandler, ScrollHandler, ScrollDirection
 
 trackball = Trackball(
-    i2c, 
-    mode=TrackballMode.MOUSE_MODE, 
+    i2c,
+    mode=TrackballMode.MOUSE_MODE,
     # optional: set rotation angle of the trackball breakout board, default is 1
-    angle_offset=1.6, 
+    angle_offset=1.6,
     handlers=[
         # act like an encoder, input arrow keys, enter when pressed
-        KeyHandler(KC.UP, KC.RIGHT, KC.DOWN, KC.LEFT, KC.ENTER), 
+        KeyHandler(KC.UP, KC.RIGHT, KC.DOWN, KC.LEFT, KC.ENTER),
         # on layer 1 and above use the default pointing behavior, left click when pressed
-        PointingHandler(on_press=KC.MB_LMB),
+        PointingHandler(),
         # use ScrollDirection.NATURAL (default) or REVERSE to change the scrolling direction, left click when pressed
         ScrollHandler(scroll_direction=ScrollDirection.NATURAL, on_press=KC.MB_LMB)
     ]
@@ -49,7 +120,7 @@ KC.TB_HANDLER(1) # activate MouseHandler
 ```
 
 
-### Backlight
+## Backlight
 
 Setup backlight color using below commands:
 
@@ -65,7 +136,7 @@ This module exposes one keycode `TB_MODE`, which on hold switches between `MOUSE
 To choose the default mode, pass it in `Trackball` constructor.
 
 
-#### Light animation
+### Light animation
 
 The trackball has a RGB LED which can be controlled with the [RGB extension](http://kmkfw.io/docs/rgb).
 Example of very slowly glowing led, almost seamlessly changing colors: