A GTK tray applet for power management for i3/sway/KDE
Project description
pwr-tray
A GTK Tray Applet for Power/Energy Saving and System/DE Controls.
Currently supported/tested DEs are:
- i3wm
- KDE on X11
In the plans are:
- Support for these DEs:
- swaywm
- KDE on Wayland
- Gnome on X11
- Gnome on Wayland
- And, imaginably, an AppImage that bundles all the system requirements since pip/pipx does not deal with those.
Install
- Basically:
pipx install pwr-tray
(exactly how depends on your installation and its state) - Plus, various system modules and executables.
- Manually run as
pwr-tray -o
:- Creates config (in
~/.config/pwr-tray/config.ini
). - Shows missing, required system-level imports (DE dependent).
- See "Installing Needed System Python Modules" (immediately below).
- Shows missing system-level commands (DE dependent). Install per distro instructions.
systemctl
andplayerctl
are always required.
- Creates config (in
- When running manually, see the "Per-Distro Specific Notes" below for its configuration.
- Finally, see the "Using pwr-tray" for everyday use after install.
Installing Needed System Python Modules
- On Debian, use
sudo apt install ...
of:- python3-gi python3-gi-cairo gir1.2-gtk-3.0
- gir1.2-appindicator3-0.1 libappindicator3-1
- On Debian 12 and others?, if the above is not working, try:
- python3-gi python3-gi-cairo gir1.2-gtk-3.0
- gir1.2-notify-0.7 gir1.2-ayatanaappindicator3-0.1 ayatanalibappindicator3-1
- On Arch, use
pacman -Syy ...
of:- libappindicator-gtk3 python-gobject python-cairo
- On other distros, use the hints above to resolve any missing "imports".
Using pwr-tray
Manual Launch of the Applet
- For foreground in terminal, run
pwr-tray -o
("-o" logs to stdout). - In the background, run
setsid pwr-tray &
(logs to~/.config/pwr-tray/debug.log
).
Other Forms of pwr-tray
pwr-tray -e
edits the config file (~/.config/pwr-ini/config.ini
)pwr-tray -f
tails the log file (~/.config/pwr-ini/debug.log
)
Tests
- Running
pwr-tray --quick
reduces the lock and sleep timeout to 1 minute (although you can 'click' the current value to try others), and--quick
runs double-time (so 1 minute timers expire in 30s per the wall clock). - You can run in various modes, but the default, SleepAfterLock, runs thru almost every action.
- Then ensure closing the lid, hitting the power button, etc., has the desired effects.
Configuration Basics
- When the program is started w/o a
config.ini
, then it is created with defaults. - It has three sections:
- Settings: The settings for when plugged in. Missing/invalid settings are inherited from the defaults. Here are the defaults:
- HiBattery: The settings for when on battery on and not a low battery condition. Missing/invalid settings are inherited from 'Settings'.
- LoBattery: The settings for when on battery in a low battery condition. Missing/invalid settings are inherited from 'Settings'.
Here are the current 'Settings' defaults with explanation.
[Settings]
i3lock_args = -t -i ./lockpaper.png # arguments when running i3lock
debug_mode = False # more frequent and elaborate logging
power_down = False # power down (rather than Suspend)
turn_off_monitors = False # turn off monitors after locking screen
lock_min_list = [15, 30] # lock minutes choices
sleep_min_list = [5, 30] # sleep minutes choices (after lock)
lo_battery_pct = 10 # define "low battery" state
NOTE: I've had problems with turning off the monitors, and if you do so, then it is harder to know the system state. If you have issues with the monitors failing to sleep or the system cannot wake with the monitors off, then avoid those that "feature".
Tray Menu
Notes:
pwr-tray
changes directory to~/.config/pwr-tray
.- If .ini file is missing, it is created and
lockpaper.png
is copied there too. - Your picks of mode and times are saved to disk when changed, and restored on the next start.
- Items may be absent depending on the mode and battery state.
- Icons change based on state:
- Full Sun: Presentation Mode
- Setting Sun: SleepAfterLock Mode ("normal")
- Open Lock: LockOnly Mode
- Red Downward Triangle: LowBattery State
- Musical Notes: Inhibited when playing media or by other inhibitors.
First, you may see:
- 🗲 Plugged In (or HiBattery or LoBattery). If you click this when you don't have a battery, then it switches to the next state. This allows you to test battery state handly faily well and/or repurpose the battery config sections.
- ♺ Chg Screen Idle: 15m->30m - change the time to start the screen saver; each time clicked, it changes to the next one.
- ♺ Chg System Idle: 5m->30m - change the time to take the system down; clicking selects the next value.
Next, choose from three major power modes (to control the effects of timeouts):
- ⮀ PRESENTATION Mode - Keeps the screen unlocked/on and system up.
- ⮀ LockOnly Mode - Keeps the system up, but the screens may lock.
- ⮀ SleepAfterLock Mode - Allows screen locking and system to go down (the "normal" mode).
- NOTE: when in LoBattery, SleepAfterLock is in effect. The icon will change per your selection and the battery state.
Next, you may choose from various locking/blanking/DE operations:
- ▷ Lock Screen - lock screen.
- ▷ Blank Monitors - Blanks the screen after locking the screen.
- ▷ Reload i3 - various DE-dependent actions.
- ▷ Log Off - terminate your user session.
Or choose a new system state:
- ▼ Suspend System - suspends the system immediately.
- ▼ Reboot System - reboots the system immediately.
- ▼ Poweroff System - power down the system immediately.
Or act on the applet itself:
- ☓ Quit this Applet - exit applet.
- ↺ Restart this Applet - restart applet.
Per-Distro Specific Notes
i3wm Specific Notes
- Uninstall or disable all competing energy saving programs (e.g.,
xscreensaver
,xfce4-power-manager
, etc.) when runningi3
whether started bysystemd
ori3/config
or whatever; don't forget the X11 defaults that can be defeated many ways such as in in~/.config/i3/config
:
exec --no-startup-id xset s off ; xset s noblank ; xset -dpms
- Edit
/etc/system/logind.conf
and uncommentHandlePowerKey=
,HandlePowerKey=
,HandlePowerKey=
, andHandlePowerKey=
, and set the action tosuspend
(reboot or restartsystemd-logind
). That enablesxss-lock
to handle those keys similar topwr-tray
. - In
~/.config/i3/config
, configurexss-lock
something like:
set $screenlock i3lock -t -i ./lockpaper.png --ignore-empty-password --show-failed-attempts
exec --no-startup-id xss-lock --transfer-sleep-lock -- $screenlock --nofork
- Finally, start your pwr-tray somehow. Below is a simplest case, but it may depend on your status bar:
bar {
status_command i3status
tray_output primary
}
exec_always --no-startup-id ~/.local/bin/pwr-tray
- If you use
polybar
for status, then it may be best to runpwr-tray
from polybar's 'launch' script, and I had to run it asenv DISPLAY=:0 pwr-tray
and delay to ensure the tray is ready.
sway Specific Notes
- Uninstall or disable all competing energy saving programs (e.g.,
swayidle
,xfce4-power-manager
, etc.) when runningsway
whether started bysystemd
orsway/config
or whatever. - NOTE: on
sway
,pwr-tray
cannot read the title time and do its usual micromanagement of the system; instead, it runs aswayidle
whose arguments may change with you changepwr-tray
settings either in the .ini file or by clicking tray items. - Edit
/etc/system/logind.conf
and uncommentHandlePowerKey=
,HandlePowerKey=
,HandlePowerKey=
, andHandlePowerKey=
, and set the action tosuspend
(reboot or restartsystemd-logind
). That enables the ever-runningsway-idle
to handle the suspend / resume events.
KDE (X11) Specific Notes
- In Settings/Energy Saving, disable "Screen Energy Saving", "Suspend session", etc., except keep the "Button events handling" and make it as you wish (e.g., "When power button pressed", "Sleep").
- In Settings/AutoStart, add the full path of
~/.local/bin/pwr-tray
.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.