AlexandClaude Opus 4.8
72fdf77c19
A full man<->code consistency audit surfaced options, format placeholders
and CSS classes that were implemented but undocumented, documented but not
implemented (some causing fmt crashes when copied from examples), and
defaults that disagreed with the code. This aligns the docs with the code
and fixes a few genuine code gaps.
Docs:
- Add the missing waybar-user(5) man page (and register it in meson.build)
- Document previously-undocumented options/placeholders/CSS across many
modules (custom image-path/image-name/icon-size, graph_type/width/
datapoints; battery smooth-power; wireplumber format-source/only-physical;
mpris {position}/prefer-album-artist; network {signalStrengthApp}/compact
bandwidth; pulseaudio {source_volume}/{source_desc}; upower {temperature}/
{model}/{native-path}; wwan {power_state}/{imei}; tray ignore-list; and
many CSS state classes: .sink-muted, .source-muted, .workspace-hover, etc.)
- Correct documented defaults to match the code (hyprland format {name},
gamemode {count}, cpu-graph interval 5, cava input_delay 4, niri taskbar
icon-size 16, disk/gps/wayfire formats, menu-actions object type, ...)
- Remove placeholders/options that do not apply (custom-graph {icon}/format/
format-icons/rotate) and fix crashing examples (wwan {mode}, gps
format-no-fix); note cava background/foreground/continuous_rendering are
cava-config-file options
Code:
- bluetooth: accept the documented `controller` key as a synonym of
`controller-alias` (the option was silently ignored)
- mango/workspaces: supply the documented `{name}` fmt arg (was missing ->
fmt::format threw)
- privacy: read `tooltip` as a bool (was guarded on isString(), so the
documented `tooltip: false` was silently ignored)
All man pages validated with scdoc 1.11.4. Not compiled locally (no gtkmm);
C++ build relies on CI.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
248 lines
7.4 KiB
Scdoc
248 lines
7.4 KiB
Scdoc
waybar-battery(5)
|
|
|
|
# NAME
|
|
|
|
waybar - battery module
|
|
|
|
# DESCRIPTION
|
|
|
|
The *battery* module displays the current capacity and state (eg. charging) of your battery.
|
|
|
|
# CONFIGURATION
|
|
|
|
*bat*: ++
|
|
typeof: string ++
|
|
The battery to monitor, as in /sys/class/power_supply/ instead of auto detect.
|
|
|
|
*adapter*: ++
|
|
typeof: string ++
|
|
The adapter to monitor, as in /sys/class/power_supply/ instead of auto detect.
|
|
|
|
*full-at*: ++
|
|
typeof: integer ++
|
|
Define the max percentage of the battery, for when you've set the battery to stop charging at a lower level to save it. For example, if you've set the battery to stop at 80% that will become the new 100%.
|
|
|
|
*design-capacity*: ++
|
|
typeof: bool ++
|
|
default: false ++
|
|
Option to use the battery design capacity instead of its current maximal capacity.
|
|
|
|
*full-at-plugged*: ++
|
|
typeof: bool ++
|
|
default: false ++
|
|
When enabled, a battery that is *Full* while the adapter is online is reported with the *Plugged* status instead of *Full* (so you can style/format it separately). Disabled by default to preserve the existing *Full* behaviour.
|
|
|
|
*interval*: ++
|
|
typeof: integer ++
|
|
default: 60 ++
|
|
The interval in which the information gets polled.
|
|
|
|
*smooth-power*: ++
|
|
typeof: bool ++
|
|
default: false ++
|
|
Enable exponential smoothing of the battery power reading used to estimate the *{time}* remaining, so the estimate fluctuates less between refreshes.
|
|
|
|
*smooth-power-time-constant*: ++
|
|
typeof: double ++
|
|
default: 260.0 ++
|
|
The time constant (in seconds) of the *smooth-power* exponential filter. Only used when *smooth-power* is enabled. Values below 1.0 are clamped to 1.0.
|
|
|
|
*states*: ++
|
|
typeof: object ++
|
|
A number of battery states which get activated on certain capacity levels. See *waybar-states(5)*.
|
|
|
|
*format*: ++
|
|
typeof: string ++
|
|
default: {capacity}% ++
|
|
The format, how information should be displayed.
|
|
|
|
*format-time*: ++
|
|
typeof: string ++
|
|
default: {H} h {M} min ++
|
|
The format, how the time should be displayed.
|
|
|
|
*format-icons*: ++
|
|
typeof: array/object ++
|
|
Based on the current capacity, the corresponding icon gets selected. ++
|
|
The order is *low* to *high*. Or by the state if it is an object.
|
|
|
|
*max-length*: ++
|
|
typeof: integer++
|
|
The maximum length in character the module should display.
|
|
|
|
*min-length*: ++
|
|
typeof: integer ++
|
|
The minimum length in characters the module should accept.
|
|
|
|
*align*: ++
|
|
typeof: float ++
|
|
The alignment of the label within the module, where 0 is left-aligned and 1 is right-aligned. If the module is rotated, it will follow the flow of the text.
|
|
|
|
*justify*: ++
|
|
typeof: string ++
|
|
The alignment of the text within the module's label, allowing options 'left', 'right', or 'center' to define the positioning.
|
|
|
|
*rotate*: ++
|
|
typeof: integer++
|
|
Positive value to rotate the text label (in 90 degree increments).
|
|
|
|
*on-click*: ++
|
|
typeof: string ++
|
|
Command to execute when clicked on the module.
|
|
|
|
*on-click-middle*: ++
|
|
typeof: string ++
|
|
Command to execute when middle-clicked on the module using mousewheel.
|
|
|
|
*on-click-right*: ++
|
|
typeof: string ++
|
|
Command to execute when you right-click on the module.
|
|
|
|
*on-update*: ++
|
|
typeof: string ++
|
|
Command to execute when the module is updated.
|
|
|
|
*on-scroll-up*: ++
|
|
typeof: string ++
|
|
Command to execute when scrolling up on the module.
|
|
|
|
*weighted-average*: ++
|
|
typeof: bool ++
|
|
default: true ++
|
|
Option to combine multiple batteries with different capacities.
|
|
|
|
*on-scroll-down*: ++
|
|
typeof: string ++
|
|
Command to execute when scrolling down on the module.
|
|
|
|
*smooth-scrolling-threshold*: ++
|
|
typeof: double ++
|
|
Threshold to be used when scrolling.
|
|
|
|
*tooltip*: ++
|
|
typeof: bool ++
|
|
default: true ++
|
|
Option to disable tooltip on hover.
|
|
|
|
*bat-compatibility*: ++
|
|
typeof: bool ++
|
|
default: false ++
|
|
Option to enable battery compatibility if not detected.
|
|
|
|
*menu*: ++
|
|
typeof: string ++
|
|
Action that popups the menu.
|
|
|
|
*menu-file*: ++
|
|
typeof: string ++
|
|
Location of the menu descriptor file. There need to be an element of type
|
|
GtkMenu with id *menu*.
|
|
|
|
*menu-actions*: ++
|
|
typeof: array ++
|
|
The actions corresponding to the buttons of the menu.
|
|
|
|
*expand*: ++
|
|
typeof: bool ++
|
|
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
|
|
|
|
*{power}*: Power in watts
|
|
|
|
*{icon}*: Icon, as defined in *format-icons*.
|
|
|
|
*{time}*: Estimate of time until full or empty. Note that this is based on the power draw at the last refresh time, not an average.
|
|
|
|
*{cycles}*: Amount of charge cycles the highest-capacity battery has seen. *(Linux only)*
|
|
|
|
*{health}*: The percentage of the highest-capacity battery's original maximum charge it can still hold.
|
|
|
|
# TIME FORMAT
|
|
|
|
The *battery* module allows you to define how time should be formatted via *format-time*.
|
|
|
|
The three arguments are:
|
|
*{H}*: Hours
|
|
*{M}*: Minutes
|
|
*{m}*: Zero-padded minutes
|
|
|
|
# CUSTOM FORMATS
|
|
|
|
The *battery* module allows one to define custom formats based on up to two factors. The best-fitting format will be selected.
|
|
|
|
*format-<state>*: With *states*, a custom format can be set depending on the capacity of your battery.
|
|
|
|
*format-<status>*: With the status, a custom format can be set depending on the status in /sys/class/power_supply/<bat>/status (in lowercase).
|
|
|
|
*format-<status>-<state>*: You can also set a custom format depending on both values.
|
|
|
|
# STATES
|
|
|
|
- Every entry (*state*) consists of a *<name>* (typeof: *string*) and a *<value>* (typeof: *integer*).
|
|
- 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>*
|
|
- *on-<status>*
|
|
|
|
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
|
|
|
|
```
|
|
"battery": {
|
|
"bat": "BAT2",
|
|
"interval": 60,
|
|
"states": {
|
|
"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!'",
|
|
"on-discharging": "notify-send -u normal 'Power Switch' Discharging",
|
|
"on-charging": "notify-send -u normal 'Power Switch' Charging'"
|
|
},
|
|
"format": "{capacity}% {icon}",
|
|
"format-icons": ["", "", "", "", ""],
|
|
"max-length": 25
|
|
}
|
|
```
|
|
|
|
# STYLE
|
|
|
|
- *#battery*
|
|
- *#battery.<status>*
|
|
- *<status>* is the value of /sys/class/power_supply/<bat>/status in lowercase.
|
|
- *#battery.<state>*
|
|
- *<state>* can be defined in the *config*. For more information see *states*.
|
|
- *#battery.<status>.<state>*
|
|
- Combination of both *<status>* and *<state>*.
|
|
|
|
The following classes are applied to the entire Waybar rather than just the
|
|
battery widget:
|
|
|
|
- *window#waybar.battery-<state>*
|
|
- *<state>* can be defined in the *config*, as previously mentioned.
|
|
|