Skip to content

Add set_caps_lock_led to complex modifications - #4571

Merged
tekezo merged 1 commit into
pqrs-org:mainfrom
anandghegde:feature/set-caps-lock-led
Oct 26, 2026
Merged

tekezo merged 1 commit into
pqrs-org:mainfrom
anandghegde:feature/set-caps-lock-led

Conversation

@anandghegde

Copy link
Copy Markdown
Contributor

Closes #3493 (originally requested in #1257).

What this adds

A new to event that controls the caps lock LED independently of the caps lock state:

{
  "description": "Use the caps lock LED as a layer indicator",
  "manipulators": [
    {
      "type": "basic",
      "from": { "key_code": "caps_lock" },
      "to": [
        { "set_variable": { "name": "layer", "value": 1 } },
        { "set_caps_lock_led": "on" }
      ],
      "to_after_key_up": [
        { "set_variable": { "name": "layer", "value": 0 } },
        { "set_caps_lock_led": "auto" }
      ]
    }
  ]
}
Value Effect
"on" Force the caps lock LED on
"off" Force the caps lock LED off
"auto" Remove the override; the LED follows the caps lock state again

The override is sticky: it stays in effect until another set_caps_lock_led changes it. This is what makes the layer-indicator and mic-mute-indicator use cases in #3493 and #1257 work — "on" on key down, "auto" on key up.

Why it is handled in the daemon

The caps lock LED is owned by Karabiner-Core-Service: device_grabber holds the hid_keyboard_caps_lock_led_state_manager for every grabbed device. software_function events are executed in Karabiner-Console-User-Server, so set_caps_lock_led would have to round-trip out of the process that actually owns the LED.

Instead this follows the set_notification_message path, which has the same shape: post_event_to_virtual_devices::manipulate calls a daemon-side manager directly instead of pushing the event to the console user server.

Implementation

  • src/share/types/caps_lock_led_value.hpp — new on / off / automatic enum with to_json / from_json, modelled on sticky_modifier_type.
  • src/share/caps_lock_led_override_manager.hpp — new dispatcher-backed manager holding the std::optional<led_state> override and emitting override_changed, modelled on notification_message_manager. It deliberately does not signal when the value is unchanged, so repeating set_caps_lock_led on key repeat does not churn the LED.
  • event_definition / event_queue::event — new type, variant alternative, JSON handling, factory, TO_C_STRING / TO_TYPE.
  • post_event_to_virtual_devices — takes a std::weak_ptr<caps_lock_led_override_manager> and applies the value on key_down only.
  • device_grabber::update_caps_lock_led — prefers the override over last_caps_lock_state_, and refreshes the LED whenever the override changes.
  • to_event_definition accepts it; from_event_definition rejects it, like the other to-only events.

Tests

  • tests/src/caps_lock_led_override_manager/ — new test directory for the manager (initial state, on/off, auto clearing the override, async_clear_override, and no signal on unchanged values).
  • tests/src/manipulator_types/ — parsing "on" / "off" / "auto", conversion to event_queue::event, to_json / make_from_json round-trip, plus error cases for a non-string and an unknown value.
  • tests/src/post_event_to_virtual_devices/ — drives manipulate() and asserts the override changes on key_down and is left alone on key_up.

cd tests && make passes in full (39 suites). device_grabber.hpp was syntax-checked separately with -std=c++23 -Wall -Werror; I could not run a full make of src/apps/CoreService here because it fails on an Info.plist build-input error that also reproduces on a clean checkout of main on this machine, before any of my changes.

Things you may want to decide differently

  1. Spelling of the value. I used a bare string ({"set_caps_lock_led": "on"}) to match shell_command. An object ({"set_caps_lock_led": {"value": "on"}}) or an LED-keyed object ({"set_led": {"caps_lock": "on"}}, mirroring sticky_modifier) would leave more room for the Num Lock / Scroll Lock request in Controlling Caps Lock LED during Complex Modifications #1257. Happy to switch.
  2. No toggle. sticky_modifier has one, but for an LED it is ambiguous while no override is set, and the two-manipulator-with-conditions pattern already covers it. Easy to add later if you want it.
  3. Override lifetime. It currently persists until changed, and is not reset on configuration reload. Resetting on reload is a one-line change if you would prefer that.

The documentation for this lives in pqrs-org/website; I am glad to open the companion PR there once the JSON shape is settled.

@tekezo

tekezo commented Sep 21, 2026

Copy link
Copy Markdown
Member

Thanks for the PR! This looks good, so I plan to merge it.
There’s another PR ahead of this one in the queue, so please bear with me until I can merge it.

@anandghegde
anandghegde force-pushed the feature/set-caps-lock-led branch from 71497f6 to 2f3c242 Compare September 21, 2026 12:47
@anandghegde

Copy link
Copy Markdown
Contributor Author

Thanks! No rush at all.

Heads-up that the branch had drifted into a merge conflict, so I've rebased it onto current main (05f36e3) and force-pushed — the PR shows as mergeable again, so it won't need anything from you when you get to it.

The only conflict was in NEWS.md, where the new-features list had picked up system.ui_language; both entries are kept. No code conflicts — none of the 31 commits since I branched touch any file this PR changes.

Re-ran the affected suites on the rebased branch, all green:

suite result
caps_lock_led_override_manager 17 asserts / 5 tests
manipulator_types 221 asserts / 8 tests
post_event_to_virtual_devices 962 asserts / 3 tests
fn_function_keys_manipulator_manager 66 asserts / 1 test

Add a new `to` event that controls the caps lock LED independently of
the caps lock state:

    "to": [ { "set_caps_lock_led": "on" } ]

"on" and "off" force the LED, "auto" removes the override so that the
LED follows the caps lock state again.

The caps lock LED is driven by Karabiner-Core-Service, so the event is
handled in the daemon by a new caps_lock_led_override_manager rather
than being forwarded to Karabiner-Console-User-Server. This follows the
same path as set_notification_message.

device_grabber::update_caps_lock_led now prefers the override over
last_caps_lock_state_, and refreshes the LED whenever the override
changes.

Closes pqrs-org#3493
@anandghegde
anandghegde force-pushed the feature/set-caps-lock-led branch from b4a3c28 to 744de99 Compare October 5, 2026 11:42
@tekezo
tekezo merged commit 83d4bef into pqrs-org:main Oct 26, 2026
@tekezo

tekezo commented Oct 26, 2026

Copy link
Copy Markdown
Member

Thank you for your patience.
This has been included in the latest beta version (v16.99.8).
https://github.com/pqrs-org/Karabiner-Elements/releases/tag/beta

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Controlling Caps Lock LED during Complex Modifications

2 participants