Repository files navigation

This script implements asimple andcustomizable timer for your bar.

• specify a command to execute when the timer expires (e.g. notify-send, shell script, ...)
• interactive:
  • e.g. scroll to increase / decrease timer
  • click to start predefined timers
  • while changing a timer a notification displays when the timer will expire
  • pause timer
• different icons for different kind of timers

(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 namedpolybar-timer, it is a general script and you can use it for every bar.In particular, if you usewaybar, then you can find a waybar-specific implementation of this timerhere.You cancustomize behaviour and appearance in a simple way.

Use cases: pomodoro timer, self-reminder when next meeting begins, tea/pasta timer, ...

This script works perfectlywithout any dependencies.

1. Downloadpolybar-timer.sh from this repo.
2. Make it executable. (chmod +x polybar-timer.sh)
3. Copy-paste theexample configuration from below into your polybar config.
4. Customize. (seeCustomization section)

[module/timer]type = custom/scriptexec = /path/to/polybar-timer.sh tail'TIMER' 5tail = trueclick-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 thedocumentation.

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 theirDEFAULTVALUE is used.

If want to understand or edit the script, I highly recommend to run atail process (see below) in a terminal window without any bar.This way you will see what the bar seesand 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 polybarexec field.It runs an infinite loop that calls theupdate routine everySECONDS seconds.We will call the process which runs thistail routine thetail process.

• update <PID>

  This routine is resposible for updating the output (i.e. what you see on the bar) and for handling theACTION 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 havejust executed some of the commands below. For example, if you havecreated a timer withnew, you want to callupdate on the tail process right after.PID needs to be the pid of the tail process.(this isprovided by polybar with%pid%)
  The update routine (triggered automatically every few seconds and whenever you callupdate) does the following:

  1. If there is a timer running and its expiry time is <= now, then it executesACTION and kills the timer.
  2. It prints the current output. This is either<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 thefollowing commands you can control the timer. If you want the bar toto update immediately after a change, you should callupdate right after, for examplepolybar-timer.sh increase 60 ; polybar-timer.sh update <pid of tail process>'.

• new <MINUTES> <TIMER_LABEL_RUNNING> <TIMER_LABEL_PAUSED> [ACTION=""]

  1. If there is a timer already running this timer gets killed.
  2. Creates a timer of lengthMINUTES minutes andTIMER_LABEL_RUNNING as itslabel and sets its action toACTION. (ACTION will be executed once the timer expires.) If this timer gets paused at some point, the label will be replaced byTIMER_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 bySECONDS seconds.SECONDS can also be negative, in which case it shortens the timer. Then it exitswith 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. TheACTION willnot beexecuted.

Note, when there is no timer active, thenincrease does nothing.So you might want to use the following command as a replacement forincrease.

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!