162 lines
5.2 KiB
Markdown
162 lines
5.2 KiB
Markdown
## awesome.battery-widget
|
|
|
|
Battery indicator widget for awesome window manager.
|
|
|
|
|
|
|
|
Displays status information from `/sys/class/power_supply`.
|
|
|
|
|
|
### Dependencies
|
|
|
|
Optionally, in order to receive status updates, you will also need `acpid`:
|
|
|
|
```bash
|
|
pacman -S acpid
|
|
systemctl enable --now acpid
|
|
```
|
|
|
|
|
|
### Usage
|
|
|
|
In order to add a battery widget to your wibox, you have to import the module
|
|
and then instanciate a widget with the desired options like this:
|
|
|
|
```lua
|
|
local deficient = require("deficient")
|
|
|
|
|
|
-- instanciate widget
|
|
local battery_widget = deficient.battery_widget {
|
|
-- pass options here
|
|
}
|
|
|
|
|
|
-- add to wibox
|
|
s.mywibox:setup {
|
|
...,
|
|
{ -- Right widgets
|
|
...,
|
|
battery_widget,
|
|
},
|
|
}
|
|
```
|
|
|
|
If you pass an adapter name using the `adapter = "..."` option, a widget for
|
|
that specific battery adapter will be instanciated. If the `adapter` option is
|
|
not specified, the call will return a table containing widgets for each of the
|
|
battery adapters in `/sys/class/power_supply`. In that case if there are no
|
|
batteries an empty table will be returned and no error will occur on machines
|
|
without batteries.
|
|
|
|
|
|
### Options
|
|
|
|
The behaviour and appearance of the widget can be tweaked using a few options.
|
|
This is an example using all available options:
|
|
|
|
```lua
|
|
battery_widget {
|
|
ac = "AC",
|
|
adapter = "BAT0",
|
|
ac_prefix = "AC: ",
|
|
battery_prefix = "Bat: ",
|
|
percent_colors = {
|
|
{ 25, "red" },
|
|
{ 50, "orange"},
|
|
{999, "green" },
|
|
},
|
|
listen = true,
|
|
timeout = 10,
|
|
widget_text = "${AC_BAT}${color_on}${percent}%${color_off}",
|
|
widget_font = "Deja Vu Sans Mono 16",
|
|
tooltip_text = "Battery ${state}${time_est}\nCapacity: ${capacity_percent}%",
|
|
alert_threshold = 5,
|
|
alert_timeout = 0,
|
|
alert_title = "Low battery !",
|
|
alert_text = "${AC_BAT}${time_est}",
|
|
alert_icon = "~/Downloads/low_battery_icon.png",
|
|
warn_full_battery = true,
|
|
full_battery_icon = "~/Downloads/full_battery_icon.png",
|
|
}
|
|
```
|
|
|
|
`adapter`
|
|
The name of the directory entry in `/sys/class/power_supply` corresponding to the requested battery adapter.
|
|
|
|
`ac`
|
|
The name of the directory entry in `/sys/class/power_supply` corresponding to your AC status.
|
|
|
|
`ac_prefix`
|
|
The prefix to populate `${AC_BAT}` when your computer is using ac power. If your font supports unicode characters, you could use "🔌".
|
|
|
|
`battery_prefix`
|
|
The prefix to populate `${AC_BAT}` when your computer is using battery power. If your font supports unicode characters, you could use "🔋". Can also be configured as a table like `percent_colors` to show different prefixes at different battery percentages.
|
|
|
|
`percent_colors` (`limits` for backwards compatibility)
|
|
The colors that the percentage changes to, as well as the upper-bound limit of when it will change. Ex. `{100, "green"}` means any percentage lower than 100 is colored green.
|
|
|
|
`listen`
|
|
Tells the widget to listen to updates via `acpi_listen`. When an event is fired, the widget updates.
|
|
|
|
`timeout`
|
|
The time interval that the widget waits before it updates itself, in seconds.
|
|
|
|
`widget_text`, `tooltip_text`
|
|
The text which shows up on the toolbar and when you highlight the widget, respectively. Please refer to function `battery_widget:update()` for other interpolatable variables.
|
|
|
|
`widget_font`
|
|
The font description used for the widget text, for instance "Deja Vu Sans Mono 16". If this is empty or unspecified, the default font will be used.
|
|
|
|
`alert_threshold`
|
|
The percentage used as the maximum value at which an alert will be generated, `-1` to disable alerts. Once the alert is dismissed (or expired) it will not show up again until the battery has been charging.
|
|
|
|
`alert_timeout`
|
|
The time after which the alert expire, `0` for no timeout.
|
|
|
|
`alert_title`, `alert_text`, `alert_icon`
|
|
The text which shows up on the alert notification, respectively the title, body text and image path.
|
|
|
|
`warn_full_battery`, boolean
|
|
Whether a notification should be displayed when the battery gets fully charged.
|
|
|
|
`full_battery_icon`
|
|
Path to the image, which should be shown as part of the notification when battery gets fully charged (depends on `warn_full_battery`).
|
|
|
|
### Usage Examples
|
|
|
|
Percentage tables can be used for `ac_prefix`, `battery_prefix`, and `percent_colors` to show different things depending on the battery charge level, e.g.:
|
|
|
|
```lua
|
|
battery_widget {
|
|
-- Show different prefixes when charging on AC
|
|
ac_prefix = {
|
|
{ 25, "not charged" },
|
|
{ 50, "1/4 charged" },
|
|
{ 75, "2/4 charged" },
|
|
{ 95, "3/4 charged" },
|
|
{100, "fully charged" },
|
|
},
|
|
|
|
-- Show a visual indicator of charge level when on battery power
|
|
battery_prefix = {
|
|
{ 25, "#--- "},
|
|
{ 50, "##-- "},
|
|
{ 75, "###- "},
|
|
{100, "#### "},
|
|
}
|
|
}
|
|
```
|
|
|
|
`ac_prefix`, `battery_prefix`, and `widget_text` can be further customized with spans to specify colors or fonts, e.g.:
|
|
|
|
```lua
|
|
battery_widget {
|
|
-- Use different colors for ac_prefix and battery_prefix
|
|
ac_prefix = '<span color="red">AC: </span>',
|
|
battery_prefix = '<span color="green">Bat: </span>',
|
|
|
|
-- Use a bold font for both prefixes (overrides widget_font)
|
|
widget_text = '<span font="Deja Vu Sans Bold 16">${AC_BAT}</span>${color_on}${percent}%${color_off}'
|
|
}
|
|
```
|