From a64876b928b86377c61529113e2a95e6b7c1f60d Mon Sep 17 00:00:00 2001
From: Prakhar Chhalotre <chhalotreprakhar00@gmail.com>
Date: Tue, 24 Feb 2026 19:37:01 +0530
Subject: [PATCH] docs: update man page

---
 man/waybar-keyboard-state.5.scd | 37 +++++++++++++++++++++++++++++++--
 src/modules/keyboard_state.cpp  | 21 +++++++++++++------
 2 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/man/waybar-keyboard-state.5.scd b/man/waybar-keyboard-state.5.scd
index 79498414..7babe336 100644
--- a/man/waybar-keyboard-state.5.scd
+++ b/man/waybar-keyboard-state.5.scd
@@ -26,7 +26,10 @@ You must be a member of the input group to use this module.
 *format-icons*: ++
 	typeof: object ++
 	default: {"locked": "locked", "unlocked": "unlocked"} ++
-	Based on the keyboard state, the corresponding icon gets selected. The same set of icons is used for number, caps, and scroll lock, but the icon is selected from the set independently for each. See *icons*.
+	Based on the keyboard state, the corresponding icon gets selected. Supports two syntaxes:
+	- Common format-icons: "locked" and "unlocked" keys apply to all lock types.
+	- Per-lock-type format-icons: per-lock-type objects with "numlock", "capslock", "scrolllock" keys, each containing "locked" and "unlocked" icons.
+	See *icons*.
 
 *numlock*: ++
 	typeof: bool ++
@@ -68,15 +71,21 @@ You must be a member of the input group to use this module.
 
 The following *format-icons* can be set.
 
+## Common format-icons for all lock types:
 - *locked*: Will be shown when the keyboard state is locked. Default "locked".
-- *unlocked*: Will be shown when the keyboard state is not locked. Default "unlocked"
+- *unlocked*: Will be shown when the keyboard state is not locked. Default "unlocked".
+
+## Per-lock-type format-icons:
+- *numlock*, *capslock*, *scrolllock*: Object containing "locked" and "unlocked" keys for lock-type-specific icons. Defaults to {"locked": "locked", "unlocked": "unlocked"} for each lock type.
 
 # EXAMPLE:
 
+## Common format-icons for all lock types:
 ```
 "keyboard-state": {
 	"numlock": true,
 	"capslock": true,
+	"scrolllock": true,
 	"format": "{name} {icon}",
 	"format-icons": {
 		"locked": "",
@@ -85,6 +94,30 @@ The following *format-icons* can be set.
 }
 ```
 
+## Per-lock-type format-icons:
+```
+"keyboard-state": {
+	"numlock": true,
+	"capslock": true,
+	"scrolllock": true,
+	"format": "{name} {icon}",
+	"format-icons": {
+		"numlock": {
+			"locked": "1",
+			"unlocked": "0"
+		},
+		"capslock": {
+			"locked": "A",
+			"unlocked": "a"
+		},
+		"scrolllock": {
+			"locked": "S",
+			"unlocked": "s"
+		}
+	}
+}
+```
+
 # STYLE
 
 - *#keyboard-state*
diff --git a/src/modules/keyboard_state.cpp b/src/modules/keyboard_state.cpp
index 577f52bd..49cf863f 100644
--- a/src/modules/keyboard_state.cpp
+++ b/src/modules/keyboard_state.cpp
@@ -79,17 +79,22 @@ auto supportsLockStates(const libevdev* dev) -> bool {
 }
 
 auto isCommonFormatIcons(const Json::Value& config) -> bool {
-  return config["format-icons"].isObject() && (config["format-icons"]["locked"].isString() || config["format-icons"]["unlocked"].isString());
+  return config["format-icons"].isObject() && (config["format-icons"]["locked"].isString() ||
+                                               config["format-icons"]["unlocked"].isString());
 }
 
-auto keyStateToIcons(const Json::Value& config) -> std::unordered_map<std::string, std::vector<std::string>> {
+auto keyStateToIcons(const Json::Value& config)
+    -> std::unordered_map<std::string, std::vector<std::string>> {
   std::unordered_map<std::string, std::vector<std::string>> key_icon_states;
   std::vector<std::string> default_icons = {"unlocked", "locked"};
 
   if (isCommonFormatIcons(config)) {
     std::vector<std::string> icons = {
-      config["format-icons"]["unlocked"].isString() ? config["format-icons"]["unlocked"].asString() : "unlocked",
-      config["format-icons"]["locked"].isString() ? config["format-icons"]["locked"].asString() : "locked",
+        config["format-icons"]["unlocked"].isString()
+            ? config["format-icons"]["unlocked"].asString()
+            : "unlocked",
+        config["format-icons"]["locked"].isString() ? config["format-icons"]["locked"].asString()
+                                                    : "locked",
     };
     key_icon_states["Lock"] = icons;
     return key_icon_states;
@@ -100,8 +105,12 @@ auto keyStateToIcons(const Json::Value& config) -> std::unordered_map<std::strin
     std::string map_key = key.substr(0, key.length() - 4);
     map_key[0] = std::toupper(map_key[0]);
     if (config["format-icons"].isObject() && config["format-icons"][key].isObject()) {
-      std::string unlocked = config["format-icons"][key]["unlocked"].isString() ? config["format-icons"][key]["unlocked"].asString() : "unlocked";
-      std::string locked = config["format-icons"][key]["locked"].isString() ? config["format-icons"][key]["locked"].asString() : "locked";
+      std::string unlocked = config["format-icons"][key]["unlocked"].isString()
+                                 ? config["format-icons"][key]["unlocked"].asString()
+                                 : "unlocked";
+      std::string locked = config["format-icons"][key]["locked"].isString()
+                               ? config["format-icons"][key]["locked"].asString()
+                               : "locked";
       key_icon_states[map_key] = {unlocked, locked};
       found_any = true;
     }