New and improved lock LED callbacks (#7215)

* New and improved lock LED callbacks

* Include stdbool

* Update documentation

* Use full function signatures and add keyboard-level example

6 files changed, 47 insertions, 1 deletions

diff --git a/quantum/quantum.c b/quantum/quantum.c
index 7e2b90ea7f..141a153400 100644
--- a/quantum/quantum.c
+++ b/quantum/quantum.c
@@ -1081,10 +1081,30 @@ void api_send_unicode(uint32_t unicode) {
 #endif
 }
 
+/** \brief Lock LED set callback - keymap/user level
+ *
+ * \deprecated Use led_update_user() instead.
+ */
 __attribute__((weak)) void led_set_user(uint8_t usb_led) {}
 
+/** \brief Lock LED set callback - keyboard level
+ *
+ * \deprecated Use led_update_kb() instead.
+ */
 __attribute__((weak)) void led_set_kb(uint8_t usb_led) { led_set_user(usb_led); }
 
+/** \brief Lock LED update callback - keymap/user level
+ *
+ * \return True if led_update_kb() should run its own code, false otherwise.
+ */
+__attribute__((weak)) bool led_update_user(led_t led_state) { return true; }
+
+/** \brief Lock LED update callback - keyboard level
+ *
+ * \return Ignored for now.
+ */
+__attribute__((weak)) bool led_update_kb(led_t led_state) { return led_update_user(led_state); }
+
 __attribute__((weak)) void led_init_ports(void) {}
 
 __attribute__((weak)) void led_set(uint8_t usb_led) {
@@ -1107,6 +1127,7 @@ __attribute__((weak)) void led_set(uint8_t usb_led) {
 #endif
 
     led_set_kb(usb_led);
+    led_update_kb((led_t) usb_led);
 }
 
 //------------------------------------------------------------------------------
diff --git a/quantum/quantum.h b/quantum/quantum.h
index 87343a15df..7988c58788 100644
--- a/quantum/quantum.h
+++ b/quantum/quantum.h
@@ -289,5 +289,7 @@ uint16_t hex_to_keycode(uint8_t hex);
 
 void led_set_user(uint8_t usb_led);
 void led_set_kb(uint8_t usb_led);
+bool led_update_user(led_t led_state);
+bool led_update_kb(led_t led_state);
 
 void api_send_unicode(uint32_t unicode);
diff --git a/quantum/template/base/keymaps/default/keymap.c b/quantum/template/base/keymaps/default/keymap.c
index 0002d91216..f1f40ca15d 100644
--- a/quantum/template/base/keymaps/default/keymap.c
+++ b/quantum/template/base/keymaps/default/keymap.c
@@ -63,4 +63,6 @@ void matrix_init_user(void) {}
 
 void matrix_scan_user(void) {}
 
-void led_set_user(uint8_t usb_led) {}
+bool led_update_user(led_t led_state) {
+    return true;
+}
diff --git a/tmk_core/common/host.c b/tmk_core/common/host.c
index ce39760a5b..713b0d9456 100644
--- a/tmk_core/common/host.c
+++ b/tmk_core/common/host.c
@@ -39,6 +39,12 @@ uint8_t host_keyboard_leds(void) {
     if (!driver) return 0;
     return (*driver->keyboard_leds)();
 }
+
+led_t host_keyboard_led_state(void) {
+    if (!driver) return (led_t) {0};
+    return (led_t)((*driver->keyboard_leds)());
+}
+
 /* send report */
 void host_keyboard_send(report_keyboard_t *report) {
     if (!driver) return;
diff --git a/tmk_core/common/host.h b/tmk_core/common/host.h
index b2a7f98427..2cffef6e15 100644
--- a/tmk_core/common/host.h
+++ b/tmk_core/common/host.h
@@ -21,6 +21,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #include <stdbool.h>
 #include "report.h"
 #include "host_driver.h"
+#include "led.h"
 
 #define IS_LED_ON(leds, led_name) ((leds) & (1 << (led_name)))
 #define IS_LED_OFF(leds, led_name) (~(leds) & (1 << (led_name)))
@@ -41,6 +42,7 @@ host_driver_t *host_get_driver(void);
 
 /* host driver interface */
 uint8_t host_keyboard_leds(void);
+led_t   host_keyboard_led_state(void);
 void    host_keyboard_send(report_keyboard_t *report);
 void    host_mouse_send(report_mouse_t *report);
 void    host_system_send(uint16_t data);
diff --git a/tmk_core/common/led.h b/tmk_core/common/led.h
index 2c28fe5401..daf974bed4 100644
--- a/tmk_core/common/led.h
+++ b/tmk_core/common/led.h
@@ -18,6 +18,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #ifndef LED_H
 #define LED_H
 #include "stdint.h"
+#include "stdbool.h"
 
 /* FIXME: Add doxygen comments here. */
 
@@ -32,6 +33,18 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 extern "C" {
 #endif
 
+typedef union {
+    uint8_t raw;
+    struct {
+        bool num_lock    : 1;
+        bool caps_lock   : 1;
+        bool scroll_lock : 1;
+        bool compose     : 1;
+        bool kana        : 1;
+        uint8_t reserved : 3;
+    };
+} led_t;
+
 void led_set(uint8_t usb_led);
 
 void led_init_ports(void);