This script implements a simple and customizable timer for your bar.
(set a timer)
(cancel a timer)
(start predefined timer)
(start other predefined timer and increase it)
(watch expiry time when you change a timer)
Even though the repo is named polybar-timer
, it is a general script and you can use it for every bar.
In particular, if you use waybar, then you can find a waybar-specific implementation of this timer here.
You can customize behaviour and appearance in a simple way.
Use cases: pomodoro timer, self-reminder when next meeting begins, tea/pasta timer, ...
This script works perfectly without any dependencies.
chmod +x polybar-timer.sh
)[module/timer]
type = custom/script
exec = /path/to/polybar-timer.sh tail 'TIMER' 5
tail = true
click-left = /path/to/polybar-timer.sh new 25 'Pomo session' 'Paused' 'notify-send "Session finished"' ; /path/to/polybar-timer.sh update %pid%
click-middle = /path/to/polybar-timer.sh cancel ; /path/to/polybar-timer.sh update %pid%
click-right = /path/to/polybar-timer.sh togglepause ; /path/to/polybar-timer.sh update %pid%
scroll-up = /path/to/polybar-timer.sh increase 60 || /path/to/polybar-timer.sh new 1 'TIMER' 'PAUSED' 'notify-send -u critical "Timer expired."' ; /path/to/polybar-timer.sh update %pid%
scroll-down = /path/to/polybar-timer.sh increase -60 ; /path/to/polybar-timer.sh update %pid%
The example configuration implements a 25min "pomodoro session" timer with left click, pausing with right click, canceling with middle click, and a normal timer by just scrolling up from the standby mode.
You can customize the different strings, numbers and actions to your own flavor and needs. To understand what the commands do and to implement some different behaviour see the documentation.
If you want to do some really specific stuff and add some functionality, just edit the script. It is really simple. Just take your 10 minutes to understand what it does and then customize it.
Notation: <...>
are necessary arguments. [...=DEFAULTVALUE]
are optional arguments,
and if you do not specify them their DEFAULTVALUE
is used.
If want to understand or edit the script, I highly recommend to run a tail process (see below) in a terminal window without any bar. This way you will see what the bar sees and you will understand how the updates work.
You can call the script with the following arguments:
tail <STANDBY_LABEL> <SECONDS>
This is the command which you want to put in your polybar exec
field.
It runs an infinite loop that calls the update
routine every SECONDS
seconds.
We will call the process which runs this tail
routine the tail process.
update <PID>
This routine is resposible for updating the output (i.e. what you see on the bar) and for handling the ACTION
when the timer expires.
It is executed automatically inside the tail process every few seconds.
However, you will most probably want to also trigger it manually (in addition to the regular updates) just after you have
just executed some of the commands below. For example, if you have
created a timer with new
, you want to call update
on the tail process right after. PID
needs to be the pid of the tail process.
(this is provided by polybar with %pid%
)
The update routine (triggered automatically every few seconds and whenever you call update
) does the following:
ACTION
and kills the timer.<TIMER_LABEL><minutes left>
if there is a timer running or <STANDBY_LABEL>
if no timer is running.These were the basic commands to handle the technical side. Now with the
following commands you can control the timer. If you want the bar to
to update immediately after a change, you should call update
right after, for example
polybar-timer.sh increase 60 ; polybar-timer.sh update <pid of tail process>'
.
new <MINUTES> <TIMER_LABEL_RUNNING> <TIMER_LABEL_PAUSED> [ACTION=""]
MINUTES
minutes and TIMER_LABEL_RUNNING
as its
label and sets its action to ACTION
. (ACTION
will be executed once the timer expires.) If this timer gets paused at some point, the label will be replaced by TIMER_LABEL_PAUSED
.increase <SECONDS>
If there is no timer set, nothing happens and it exits with 1.
If there is a timer set, it is extended by SECONDS
seconds. SECONDS
can also be negative, in which case it shortens the timer. Then it exits
with 0.
togglepause
If there is no timer set at all, it exits with 1. If there is a timer running, the timer gets paused and it exits with 0. If there is a timer set which is already paused, the timer gets resumed and it exits with 0.
cancel
If there is a timer running, the timer gets canceled. The ACTION
will not be
executed.
Note, when there is no timer active, then increase
does nothing.
So you might want to use the following command as a replacement for increase
.
polybar-timer.sh increase 60 || polybar-timer.sh new 1 'mytimer' 'paused' 'notify-send "Timer expired."'
It increases the existing timer if it's active, and creates a timer with label "mytimer" of lengths 1 minute if there is no timer currently running. So now e.g. scrolling up also does something when there is no timer active - it starts a new timer!
If you don't (want to) use dunstify
please see the dependencies section.