Merge pull request #4208 from markx86/feat/battery-events

battery: Add support for battery level related events

man/waybar-battery.5.scd

@@ -116,7 +116,7 @@ The *battery* module displays the current capacity and state (eg. charging) of y
 *menu-file*: ++
 	typeof: string ++
 	Location of the menu descriptor file. There need to be an element of type
-	GtkMenu with id *menu*
+	GtkMenu with id *menu*.
 
 *menu-actions*: ++
 	typeof: array ++
@@ -127,6 +127,10 @@ The *battery* module displays the current capacity and state (eg. charging) of y
 	default: false ++
 	Enables this module to consume all left over space dynamically.
 
+*events*: ++
+	typeof: object ++
+	Specifies commands to be executed on specific battery states. See *EVENTS* section below.
+
 # FORMAT REPLACEMENTS
 
 *{capacity}*: Capacity in percentage
@@ -166,6 +170,19 @@ The *battery* module allows one to define custom formats based on up to two fact
 - The state can be addressed as a CSS class in the *style.css*. The name of the CSS class is the *<name>* of the state.	Each class gets activated when the current capacity is equal to or below the configured *<value>*.
 - Also each state can have its own *format*. Those can be configured via *format-<name>*. Or if you want to differentiate a bit more even as *format-<status>-<state>*. For more information see *custom-formats*.
 
+# EVENTS
+
+Every entry in the *events* object consists of a *<event-name>* (typeof: *string*) and a *<command>* (typeof: *string*). ++
+*<event-name>* can be in one of the following formats:
+
+- *on-<status>-<state>* 
+- *on-<status>-<capacity>*
+
+Where:
+
+- *<status>* is either *charging* or *discharging*,
+- *<state>* is the name of one of the states specified in the *states* object,
+- *<capacity>* is a battery level value (between *0-100*).
 
 
 # EXAMPLES
@@ -178,6 +195,11 @@ The *battery* module allows one to define custom formats based on up to two fact
 		"warning": 30,
 		"critical": 15
 	},
+	"events": {
+		"on-discharging-warning": "notify-send -u normal 'Low Battery'",
+		"on-discharging-critical": "notify-send -u critical 'Very Low Battery'",
+		"on-charging-100": "notify-send -u normal 'Battery Full!'"
+	},
 	"format": "{capacity}% {icon}",
 	"format-icons": ["", "", "", "", ""],
 	"max-length": 25