f0b2bfd5ca5b416a9c7c9bef8c2850f1084bd106
- Author
- Ryan <fauxpark@gmail.com>
- Committer
- GitHub <noreply@github.com>
- Date
Message
Programmable Button API refactor and improve docs (#18641)
Diff
This diff is truncated to protect this page.
1diff --git a/docs/feature_programmable_button.md b/docs/feature_programmable_button.md
2index b1ef555d16a955fd0cb6e5822b1455ce47bde767..1982b8295e8762eff0a4b7c179399c8b243f25fe 100644
3--- a/docs/feature_programmable_button.md
4+++ b/docs/feature_programmable_button.md
5@@ -1,74 +1,144 @@
6-## Programmable Button
7+# Programmable Button :id=programmable-button
8
9-Programmable button is a feature that can be used to send keys that have no
10-predefined meaning.
11-This means they can be processed on the host side by custom software without
12-colliding without the operating system trying to interpret these keys.
13+Programmable Buttons are keys that have no predefined meaning. This means they can be processed on the host side by custom software without the operating system trying to interpret them.
14
15-The keycodes are emitted according to the HID usage
16-"Telephony Device Page" (0x0B), "Programmable button usage" (0x07).
17-On Linux (> 5.14) they are handled automatically and translated to `KEY_MACRO#`
18-keycodes.
19-(Up to `KEY_MACRO30`)
20+The keycodes are emitted according to the HID Telephony Device page (`0x0B`), Programmable Button usage (`0x07`). On Linux (> 5.14) they are handled automatically and translated to `KEY_MACRO#` keycodes (up to `KEY_MACRO30`).
21
22-### Enabling Programmable Button support
23+?> Currently there is no known support in Windows or macOS. It may be possible to write a custom HID driver to receive these usages, but this is out of the scope of the QMK documentation.
24
25-To enable Programmable Button, add the following line to your keymap’s `rules.mk`:
26+## Usage :id=usage
27
28-```c
29+Add the following to your `rules.mk`:
30+
31+```make
32 PROGRAMMABLE_BUTTON_ENABLE = yes
33 ```
34
35-### Mapping
36-
37-In your keymap you can use the following keycodes to map key presses to Programmable Buttons:
38-
39-|Key |Description |
40-|------------------------|----------------------|
41-|`PROGRAMMABLE_BUTTON_1` |Programmable button 1 |
42-|`PROGRAMMABLE_BUTTON_2` |Programmable button 2 |
43-|`PROGRAMMABLE_BUTTON_3` |Programmable button 3 |
44-|`PROGRAMMABLE_BUTTON_4` |Programmable button 4 |
45-|`PROGRAMMABLE_BUTTON_5` |Programmable button 5 |
46-|`PROGRAMMABLE_BUTTON_6` |Programmable button 6 |
47-|`PROGRAMMABLE_BUTTON_7` |Programmable button 7 |
48-|`PROGRAMMABLE_BUTTON_8` |Programmable button 8 |
49-|`PROGRAMMABLE_BUTTON_9` |Programmable button 9 |
50-|`PROGRAMMABLE_BUTTON_10`|Programmable button 10|
51-|`PROGRAMMABLE_BUTTON_11`|Programmable button 11|
52-|`PROGRAMMABLE_BUTTON_12`|Programmable button 12|
53-|`PROGRAMMABLE_BUTTON_13`|Programmable button 13|
54-|`PROGRAMMABLE_BUTTON_14`|Programmable button 14|
55-|`PROGRAMMABLE_BUTTON_15`|Programmable button 15|
56-|`PROGRAMMABLE_BUTTON_16`|Programmable button 16|
57-|`PROGRAMMABLE_BUTTON_17`|Programmable button 17|
58-|`PROGRAMMABLE_BUTTON_18`|Programmable button 18|
59-|`PROGRAMMABLE_BUTTON_19`|Programmable button 19|
60-|`PROGRAMMABLE_BUTTON_20`|Programmable button 20|
61-|`PROGRAMMABLE_BUTTON_21`|Programmable button 21|
62-|`PROGRAMMABLE_BUTTON_22`|Programmable button 22|
63-|`PROGRAMMABLE_BUTTON_23`|Programmable button 23|
64-|`PROGRAMMABLE_BUTTON_24`|Programmable button 24|
65-|`PROGRAMMABLE_BUTTON_25`|Programmable button 25|
66-|`PROGRAMMABLE_BUTTON_26`|Programmable button 26|
67-|`PROGRAMMABLE_BUTTON_27`|Programmable button 27|
68-|`PROGRAMMABLE_BUTTON_28`|Programmable button 28|
69-|`PROGRAMMABLE_BUTTON_29`|Programmable button 29|
70-|`PROGRAMMABLE_BUTTON_30`|Programmable button 30|
71-|`PROGRAMMABLE_BUTTON_31`|Programmable button 31|
72-|`PROGRAMMABLE_BUTTON_32`|Programmable button 32|
73-|`PB_1` to `PB_32` |Aliases for keymaps |
74-
75-### API
76-
77-You can also use a dedicated API defined in `programmable_button.h` to interact with this feature:
78+## Keycodes :id=keycodes
79
80-```
81-void programmable_button_clear(void);
82-void programmable_button_send(void);
83-void programmable_button_on(uint8_t code);
84-void programmable_button_off(uint8_t code);
85-bool programmable_button_is_on(uint8_t code);
86-uint32_t programmable_button_get_report(void);
87-void programmable_button_set_report(uint32_t report);
88-```
89+|Key |Aliases|Description |
90+|------------------------|-------|----------------------|
91+|`PROGRAMMABLE_BUTTON_1` |`PB_1` |Programmable button 1 |
92+|`PROGRAMMABLE_BUTTON_2` |`PB_2` |Programmable button 2 |
93+|`PROGRAMMABLE_BUTTON_3` |`PB_3` |Programmable button 3 |
94+|`PROGRAMMABLE_BUTTON_4` |`PB_4` |Programmable button 4 |
95+|`PROGRAMMABLE_BUTTON_5` |`PB_5` |Programmable button 5 |
96+|`PROGRAMMABLE_BUTTON_6` |`PB_6` |Programmable button 6 |
97+|`PROGRAMMABLE_BUTTON_7` |`PB_7` |Programmable button 7 |
98+|`PROGRAMMABLE_BUTTON_8` |`PB_8` |Programmable button 8 |
99+|`PROGRAMMABLE_BUTTON_9` |`PB_9` |Programmable button 9 |
100+|`PROGRAMMABLE_BUTTON_10`|`PB_10`|Programmable button 10|
101+|`PROGRAMMABLE_BUTTON_11`|`PB_11`|Programmable button 11|
102+|`PROGRAMMABLE_BUTTON_12`|`PB_12`|Programmable button 12|
103+|`PROGRAMMABLE_BUTTON_13`|`PB_13`|Programmable button 13|
104+|`PROGRAMMABLE_BUTTON_14`|`PB_14`|Programmable button 14|
105diff --git a/quantum/action.c b/quantum/action.c
106index 78322e4a83aff62aefb381c54be5e917c4b6c1dc..abf9834d2f39f907b988e743acb50577e226be6f 100644
107--- a/quantum/action.c
108+++ b/quantum/action.c
109@@ -1081,7 +1081,6 @@ void clear_keyboard_but_mods_and_keys() {
110 #endif
111 #ifdef PROGRAMMABLE_BUTTON_ENABLE
112 programmable_button_clear();
113- programmable_button_send();
114 #endif
115 }
116
117diff --git a/quantum/keyboard.c b/quantum/keyboard.c
118index 280532a5fdb746e497d401e8f88390c87f14ab38..eb5e4b583a9913d39afc8e6a55f5b4762faa27f2 100644
119--- a/quantum/keyboard.c
120+++ b/quantum/keyboard.c
121@@ -66,9 +66,6 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
122 #ifdef JOYSTICK_ENABLE
123 # include "process_joystick.h"
124 #endif
125-#ifdef PROGRAMMABLE_BUTTON_ENABLE
126-# include "programmable_button.h"
127-#endif
128 #ifdef HD44780_ENABLE
129 # include "hd44780.h"
130 #endif
131@@ -669,10 +666,6 @@ void keyboard_task(void) {
132 digitizer_task();
133 #endif
134
135-#ifdef PROGRAMMABLE_BUTTON_ENABLE
136- programmable_button_send();
137-#endif
138-
139 #ifdef BLUETOOTH_ENABLE
140 bluetooth_task();
141 #endif
142diff --git a/quantum/process_keycode/process_programmable_button.c b/quantum/process_keycode/process_programmable_button.c
143index c6e77faacc0ead8818ecd6700303432844879b5c..6379698848f5437da899b50878bd7182036d7141 100644
144--- a/quantum/process_keycode/process_programmable_button.c
145+++ b/quantum/process_keycode/process_programmable_button.c
146@@ -22,9 +22,9 @@ bool process_programmable_button(uint16_t keycode, keyrecord_t *record) {
147 if (keycode >= PROGRAMMABLE_BUTTON_MIN && keycode <= PROGRAMMABLE_BUTTON_MAX) {
148 uint8_t button = keycode - PROGRAMMABLE_BUTTON_MIN + 1;
149 if (record->event.pressed) {
150- programmable_button_on(button);
151+ programmable_button_register(button);
152 } else {
153- programmable_button_off(button);
154+ programmable_button_unregister(button);
155 }
156 }
157 return true;
158diff --git a/quantum/programmable_button.c b/quantum/programmable_button.c
159index a3ef42d82ba21c5c93d611757a3752512d5ada17..b6c9ad3189924bf7a57d269f9137f93a1459a2a8 100644
160--- a/quantum/programmable_button.c
161+++ b/quantum/programmable_button.c
162@@ -24,27 +24,38 @@ static uint32_t programmable_button_report = 0;
163
164 void programmable_button_clear(void) {
165 programmable_button_report = 0;
166+ programmable_button_flush();
167 }
168
169-void programmable_button_send(void) {
170- host_programmable_button_send(programmable_button_report);
171-}
172-
173-void programmable_button_on(uint8_t index) {
174+void programmable_button_add(uint8_t index) {
175 programmable_button_report |= REPORT_BIT(index);
176 }
177
178-void programmable_button_off(uint8_t index) {
179+void programmable_button_remove(uint8_t index) {
180 programmable_button_report &= ~REPORT_BIT(index);
181 }
182
183+void programmable_button_register(uint8_t index) {
184+ programmable_button_add(index);
185+ programmable_button_flush();
186+}
187+
188+void programmable_button_unregister(uint8_t index) {
189+ programmable_button_remove(index);
190+ programmable_button_flush();
191+}
192+
193 bool programmable_button_is_on(uint8_t index) {
194 return !!(programmable_button_report & REPORT_BIT(index));
195-};
196+}
197+
198+void programmable_button_flush(void) {
199+ host_programmable_button_send(programmable_button_report);
200+}
201
202 uint32_t programmable_button_get_report(void) {
203 return programmable_button_report;
204-};
205+}
206
207 void programmable_button_set_report(uint32_t report) {
208 programmable_button_report = report;
209diff --git a/quantum/programmable_button.h b/quantum/programmable_button.h
210index e89b8b9fd6a8db20fe1b472d304b624b04a270d1..e8c916d75c90c31c39558c67d386888152982c22 100644
211--- a/quantum/programmable_button.h
212+++ b/quantum/programmable_button.h
213@@ -19,12 +19,73 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
214
215 #include <stdint.h>
216 #include <stdbool.h>
217-#include "report.h"
218
219-void programmable_button_clear(void);
220-void programmable_button_send(void);
221-void programmable_button_on(uint8_t index);
222-void programmable_button_off(uint8_t index);
223-bool programmable_button_is_on(uint8_t index);
224+/**
225+ * \defgroup programmable_button
226+ *
227+ * HID Programmable Buttons
228+ * \{
229+ */
230+
231+/**
232+ * \brief Clear the programmable button report.
233+ */
234+void programmable_button_clear(void);
235+
236+/**
237+ * \brief Set the state of a button.
238+ *
239+ * \param index The index of the button to press, from 0 to 31.
240+ */
241+void programmable_button_add(uint8_t index);
242+
243+/**
244+ * \brief Reset the state of a button.
245+ *
246+ * \param index The index of the button to release, from 0 to 31.
247+ */
248+void programmable_button_remove(uint8_t index);
249+
250+/**
251+ * \brief Set the state of a button, and flush the report.
252+ *
253+ * \param index The index of the button to press, from 0 to 31.
254+ */
255+void programmable_button_register(uint8_t index);
256+
257+/**
258+ * \brief Reset the state of a button, and flush the report.
259+ *
260+ * \param index The index of the button to release, from 0 to 31.
261+ */
262+void programmable_button_unregister(uint8_t index);
263+
264+/**
265+ * \brief Get the state of a button.
266+ *
267+ * \param index The index of the button to check, from 0 to 31.
268+ *
269+ * \return `true` if the button is pressed.
270+ */
271+bool programmable_button_is_on(uint8_t index);
272+
273+/**
274+ * \brief Send the programmable button report to the host.
275+ */
276+void programmable_button_flush(void);
277+
278+/**
279+ * \brief Get the programmable button report.
280+ *
281+ * \return The bitmask of programmable button states.
282+ */
283 uint32_t programmable_button_get_report(void);
284-void programmable_button_set_report(uint32_t report);
285+
286+/**
287+ * \brief Set the programmable button report.
288+ *
289+ * \param report A bitmask of programmable button states.
290+ */
291+void programmable_button_set_report(uint32_t report);
292+
293+/** \} */