Commit | Line | Data |
---|---|---|
ee132284 S |
1 | ## Pointing Device |
2 | ||
af37bb2f | 3 | Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you. |
ee132284 S |
4 | |
5 | To enable Pointing Device, uncomment the following line in your rules.mk: | |
6 | ||
7 | ``` | |
8 | POINTING_DEVICE_ENABLE = yes | |
9 | ``` | |
10 | ||
11 | To manipulate the mouse report, you can use the following functions: | |
12 | ||
13 | * `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer | |
14 | * `pointing_device_set_report(report_mouse_t newMouseReport)` - Overrides and saves the report_mouse_t to be sent to the host computer | |
15 | ||
16 | Keep in mind that a report_mouse_t (here "mouseReport") has the following properties: | |
17 | ||
18 | * `mouseReport.x` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ to the right, - to the left) on the x axis. | |
19 | * `mouseReport.y` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ upward, - downward) on the y axis. | |
20 | * `mouseReport.v` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing vertical scrolling (+ upward, - downward). | |
21 | * `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left). | |
22 | * `mouseReport.buttons` - this is a uint8_t in which the last 5 bits are used. These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1. | |
23 | ||
24 | When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in "pointing_device_send()", which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden. | |
25 | ||
26 | In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. Listen, this is an example: | |
27 | ||
28 | ``` | |
29 | case MS_SPECIAL: | |
30 | report_mouse_t currentReport = pointing_device_get_report(); | |
31 | if (record->event.pressed) | |
32 | { | |
33 | currentReport.v = 127; | |
34 | currentReport.h = 127; | |
35 | currentReport.buttons |= MOUSE_BTN1; //this is defined in report.h | |
36 | } | |
37 | else | |
38 | { | |
39 | currentReport.v = -127; | |
40 | currentReport.h = -127; | |
41 | currentReport.buttons &= ~MOUSE_BTN1; | |
42 | } | |
43 | pointing_device_set_report(currentReport); | |
44 | break; | |
45 | ``` | |
46 | ||
7b0356d1 | 47 | Recall that the mouse report is set to zero (except the buttons) whenever it is sent, so the scrolling would only occur once in each case. |