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

3 files changed, 26 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;
+}