From 94ba2e5a9f9c01b015b447554bfee99f5bcee032 Mon Sep 17 00:00:00 2001 From: DidierLoiseau Date: Fri, 18 Jan 2019 02:28:33 +0100 Subject: [PATCH] Defined IS_(HOST_)LED_ON/OFF() and improved LED documentation (#4853) * Defined IS_(HOST_)LED_ON/OFF() and improved LED documentation * Update docs/custom_quantum_functions.md Co-Authored-By: DidierLoiseau * Update docs/custom_quantum_functions.md Co-Authored-By: DidierLoiseau * Integrated @drashna and @fauxpark's PR comments - changed all plurals of "LED" to "LEDs" in the file - rewording of the note about host_keyboard_leds() vs. led_set_user() * Update docs/custom_quantum_functions.md Co-Authored-By: DidierLoiseau --- docs/custom_quantum_functions.md | 54 +++++++++++++++++++++++++++----- tmk_core/common/host.h | 6 ++++ 2 files changed, 52 insertions(+), 8 deletions(-) diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 5b95450f2..3397bf2d4 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -90,7 +90,7 @@ keyrecord_t record { # LED Control -This allows you to control the 5 LED's defined as part of the USB Keyboard spec. It will be called when the state of one of those 5 LEDs changes. +QMK provides methods to read the 5 LEDs defined as part of the HID spec: * `USB_LED_NUM_LOCK` * `USB_LED_CAPS_LOCK` @@ -98,31 +98,46 @@ This allows you to control the 5 LED's defined as part of the USB Keyboard spec. * `USB_LED_COMPOSE` * `USB_LED_KANA` +These five constants correspond to the positional bits of the host LED state. +There are two ways to get the host LED state: + +* by implementing `led_set_user()` +* by calling `host_keyboard_leds()` + +## `led_set_user()` + +This function will be called when the state of one of those 5 LEDs changes. +It receives the LED state as parameter. +Use the `IS_LED_ON(USB_LED, LED_NAME)` and `IS_LED_OFF(USB_LED, LED_NAME)` +macros to check the LED status. + +!> `host_keyboard_leds()` may already reflect a new value before `led_set_user()` is called. + ### Example `led_set_user()` Implementation ```c void led_set_user(uint8_t usb_led) { - if (usb_led & (1<