Docs: How to react to lock status changes

[hendrix04]

Add a callback to lock status so that thing such as LEDs can be kept in sync.

[xs5871]

I don't believe that a callback is the best way to go about this. Would could argue about the shortcomings: it's opaque; can't be validated; you don't no where, when and under what conditions the callback is run; there's no error handling. There's probably more and most of that could be "fixed", but that discussion wouldn't really getting us anywhere.

The recommended (and some might argue nicer, pythonic) solution is extension by inheritance in userspace:

# in your main.py
from kmk.extensions.led import LED
from kmk.extensions.lock_status import LockStatus

leds = LED(led_pin=[board.GP27, board.GP28])

class LEDLockStatus(LockStatus):
    def set_lock_leds(self):
        if self.get_caps_lock():
            leds.set_brightness(50, leds=[0])
        else:
            leds.set_brightness(0, leds=[0])

        if self.get_scroll_lock():
            leds.set_brightness(50, leds=[1])
        else:
            leds.set_brightness(0, leds=[1])

    def after_hid_send(self, sandbox):
        super().after_hid_send()
        self.set_lock_leds()

keyboard.extensions.append(leds)
keyboard.extensions.append(LEDLockStatus())

As I mentioned in #503, I don't think there's any functionality missing in the modules, we're missing proper documentation with examples of how to string different modules and extensions together.

[hendrix04]

I can concede to that, but the non-callback related changes in lock_status.py are still needed If that isn't changed, the lock status isn't in sync at boot.

[hendrix04]

Sure thing. I do have questions though, primarily for clarification, so that I can understand what's happening.

Answers on the code comments.

[hendrix04]

The two comments aside, I like it a lot. Special thanks for adding documentation! Very much appreciated.

Two comments have now been fixed. Hopefully, it is good to go.