diff options
Diffstat (limited to 'docs/custom_quantum_functions.md')
-rw-r--r-- | docs/custom_quantum_functions.md | 102 |
1 files changed, 0 insertions, 102 deletions
diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index bf3a60377..a459042b3 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md | |||
@@ -88,108 +88,6 @@ keyrecord_t record { | |||
88 | } | 88 | } |
89 | ``` | 89 | ``` |
90 | 90 | ||
91 | # LED Control | ||
92 | |||
93 | QMK provides methods to read 5 of the LEDs defined in the HID spec: | ||
94 | |||
95 | * Num Lock | ||
96 | * Caps Lock | ||
97 | * Scroll Lock | ||
98 | * Compose | ||
99 | * Kana | ||
100 | |||
101 | There are two ways to get the lock LED state: | ||
102 | |||
103 | * by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or | ||
104 | * by calling `led_t host_keyboard_led_state()` | ||
105 | |||
106 | !> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called. | ||
107 | |||
108 | Two more deprecated functions exist that provide the LED state as a `uint8_t`: | ||
109 | |||
110 | * `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)` | ||
111 | * `uint8_t host_keyboard_leds()` | ||
112 | |||
113 | ## `led_update_user()` | ||
114 | |||
115 | This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter. | ||
116 | |||
117 | By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and | ||
118 | return `false` when you would prefer not to run the code in `led_update_kb()`. | ||
119 | |||
120 | Some examples include: | ||
121 | |||
122 | - overriding the LEDs to use them for something else like layer indication | ||
123 | - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior. | ||
124 | - play a sound when an LED turns on or off. | ||
125 | - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior. | ||
126 | |||
127 | ?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead. | ||
128 | |||
129 | ### Example `led_update_kb()` Implementation | ||
130 | |||
131 | ```c | ||
132 | bool led_update_kb(led_t led_state) { | ||
133 | bool res = led_update_user(led_state); | ||
134 | if(res) { | ||
135 | // writePin sets the pin high for 1 and low for 0. | ||
136 | // In this example the pins are inverted, setting | ||
137 | // it low/0 turns it on, and high/1 turns the LED off. | ||
138 | // This behavior depends on whether the LED is between the pin | ||
139 | // and VCC or the pin and GND. | ||
140 | writePin(B0, !led_state.num_lock); | ||
141 | writePin(B1, !led_state.caps_lock); | ||
142 | writePin(B2, !led_state.scroll_lock); | ||
143 | writePin(B3, !led_state.compose); | ||
144 | writePin(B4, !led_state.kana); | ||
145 | } | ||
146 | return res; | ||
147 | } | ||
148 | ``` | ||
149 | |||
150 | ### Example `led_update_user()` Implementation | ||
151 | |||
152 | This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state. | ||
153 | |||
154 | ```c | ||
155 | #ifdef AUDIO_ENABLE | ||
156 | float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND); | ||
157 | float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND); | ||
158 | #endif | ||
159 | |||
160 | bool led_update_user(led_t led_state) { | ||
161 | #ifdef AUDIO_ENABLE | ||
162 | static uint8_t caps_state = 0; | ||
163 | if (caps_state != led_state.caps_lock) { | ||
164 | led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off); | ||
165 | caps_state = led_state.caps_lock; | ||
166 | } | ||
167 | #endif | ||
168 | return true; | ||
169 | } | ||
170 | ``` | ||
171 | |||
172 | ### `led_update_*` Function Documentation | ||
173 | |||
174 | * Keyboard/Revision: `bool led_update_kb(led_t led_state)` | ||
175 | * Keymap: `bool led_update_user(led_t led_state)` | ||
176 | |||
177 | ## `host_keyboard_led_state()` | ||
178 | |||
179 | Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code). | ||
180 | |||
181 | ## Setting Physical LED State | ||
182 | |||
183 | Some keyboard implementations provide convenience methods for setting the state of the physical LEDs. | ||
184 | |||
185 | ### Ergodox Boards | ||
186 | |||
187 | The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index. | ||
188 | |||
189 | In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`. | ||
190 | |||
191 | Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default). | ||
192 | |||
193 | # Keyboard Initialization Code | 91 | # Keyboard Initialization Code |
194 | 92 | ||
195 | There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use. | 93 | There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use. |