Skip to content

Commit 2600434

Browse files
jbirnickjbirnick
committed
bla
0 parents  commit 2600434

8 files changed

+254
-0
lines changed

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2023 Johann Birnick
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# waybar-timer
2+
3+
This script implements a **simple** and **customizable** timer for your bar.
4+
5+
- specify a command to execute when the timer expires (e.g. notify-send, shell script, ...)
6+
- interactive:
7+
* e.g. scroll to increase / decrease timer
8+
* click to start predefined timers
9+
* while changing a timer a notification displays when the timer will expire
10+
* pause timer
11+
12+
![screenshot set timer](screenshots/setTimer.gif) (set a timer)
13+
14+
![screenshot cancel timer](screenshots/cancelTimer.gif) (cancel a timer)
15+
16+
![screenshot set predefined timer](screenshots/predefinedTimer.gif) (start predefined timer)
17+
18+
![screenshot set predefined timer 2 and increase it](screenshots/predefinedTimer2.gif) (start other predefined timer and increase it)
19+
20+
![screenshot see expiry time](screenshots/expiryTimePreview.gif) (watch expiry time when you change a timer)
21+
22+
Even though the repo is named [`waybar-timer`](#), it is a general script and you can use it for every bar.
23+
In particular, if you use [**polybar**](https://github.com/polybar/polybar), then you can find a polybar-specific implementation of this timer [here](https://github.com/jbirnick/polybar-timer).
24+
You can **customize behaviour and appearance in a simple way**.
25+
26+
Use cases: pomodoro timer, self-reminder when next meeting begins, tea/pasta timer, ...
27+
28+
## Dependencies
29+
30+
Inside the script `dunstify` is called to view the mentioned notification for the expiry time.
31+
But this is not necessary. (Just beautiful.) If you do not use Dunst then you need to edit two lines in the script according to [this issue](https://github.com/jbirnick/polybar-timer/issues/3), and still everything (but the preview of the expiry time) **will work fine without dependencies**.
32+
33+
## Installation
34+
35+
1. Download [waybar-timer.sh](https://raw.githubusercontent.com/jbirnick/waybar-timer/master/waybar-timer.sh) from this repo.
36+
2. Make it executable. (`chmod +x waybar-timer.sh`)
37+
3. Copy-paste the [example configuration](#example-configuration) from below into your waybar config and style it.
38+
4. Customize. (see [Customization section](#customization))
39+
40+
## Example Configuration
41+
42+
```json
43+
"custom/timer": {
44+
"exec": "/path/to/waybar-timer.sh updateandprint",
45+
"exec-on-event": true,
46+
"return-type": "json",
47+
"interval": 5,
48+
"signal": 4,
49+
"format": "{icon} {}",
50+
"format-icons": {
51+
"standby": "STANDBY",
52+
"running": "RUNNING",
53+
"paused": "PAUSE"
54+
},
55+
"on-click": "/path/to/waybar-timer.sh new 25 'notify-send \"Session finished\"'",
56+
"on-click-middle": "/path/to/waybar-timer.sh cancel",
57+
"on-click-right": "/path/to/waybar-timer.sh togglepause",
58+
"on-scroll-up": "/path/to/waybar-timer.sh increase 60 || /path/to/waybar-timer.sh new 1 'notify-send -u critical \"Timer expired.\"'",
59+
"on-scroll-down": "/path/to/waybar-timer.sh increase -60"
60+
}
61+
```
62+
The first modification you probably want to make is to replace the `format-icons` by some actually stylish icons.
63+
64+
Furthermore you can style the module using the `timer` class, for example:
65+
```
66+
.timer {
67+
background-color: #ffee82;
68+
color: #242424;
69+
margin: 0 10px;
70+
padding: 0 10px;
71+
}
72+
```
73+
74+
## Customization
75+
76+
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.
77+
78+
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](#documentation).
79+
80+
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.
81+
82+
## Documentation
83+
84+
Notation: `<...>` are necessary arguments. `[...=DEFAULTVALUE]` are optional arguments,
85+
and if you do not specify them their `DEFAULTVALUE` is used.
86+
87+
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.
88+
This way you will see what the bar sees
89+
and you will understand how the updates work.
90+
91+
The main command of the script is:
92+
93+
- #### `updateandprint`
94+
This routine will return the current the output (i.e. what you see on the bar) and handle the `ACTION` if the timer expired.
95+
Namely:
96+
1. If there is a timer running and its expiry time is <= now, then it executes `ACTION` and kills the timer.
97+
2. It prints the output info for waybar, in particular the number of remaining minutes.
98+
99+
Now the following commands allow you to control the timer.
100+
101+
- #### `new <MINUTES> [ACTION=""]`
102+
1. If there is a timer already running this timer gets killed.
103+
2. Creates a timer of length `MINUTES` minutes and sets its action to `ACTION`. (`ACTION` will be executed once the timer expires.)
104+
105+
- #### `increase <SECONDS>`
106+
If there is no timer set, nothing happens and it exits with 1.
107+
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
108+
with 0.
109+
110+
- #### `togglepause`
111+
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.
112+
113+
- #### `cancel`
114+
If there is a timer running, the timer gets canceled. The `ACTION` will _not_ be
115+
executed.
116+
117+
## Tips & Tricks
118+
119+
Note, when there is no timer active, then [`increase`](#increase-seconds) does nothing.
120+
So you might want to use the following command as a replacement for [`increase`](#increase-seconds).
121+
```
122+
waybar-timer.sh increase 60 || waybar-timer.sh new 1 'mytimer' 'notify-send "Timer expired."'
123+
```
124+
It increases the existing timer if it's active, and creates a timer with label
125+
"mytimer" of lengths 1 minute if there is no timer currently running.
126+
So now e.g. scrolling up also does something when there is no timer active - it starts a new timer!
127+
128+
## Known Issues
129+
130+
If you don't (want to) use `dunstify` please see the [dependencies section](#dependencies).

‎screenshots/cancelTimer.gif

8.25 KB
Loading

‎screenshots/expiryTimePreview.gif

19.7 KB
Loading

‎screenshots/predefinedTimer.gif

7.67 KB
Loading

‎screenshots/predefinedTimer2.gif

9.97 KB
Loading

‎screenshots/setTimer.gif

9.56 KB
Loading

‎waybar-timer.sh

+103
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
#!/bin/bash
2+
3+
### AUTHOR: Johann Birnick (github: jbirnick)
4+
### PROJECT REPO: https://github.com/jbirnick/waybar-timer
5+
6+
## FUNCTIONS
7+
8+
now () { date --utc +%s; }
9+
10+
killTimer () { rm -rf /tmp/waybar-timer ; }
11+
timerSet () { [ -e /tmp/waybar-timer/ ] ; }
12+
timerPaused () { [ -f /tmp/waybar-timer/paused ] ; }
13+
14+
timerExpiry () { cat /tmp/waybar-timer/expiry ; }
15+
timerAction () { cat /tmp/waybar-timer/action ; }
16+
17+
secondsLeftWhenPaused () { cat /tmp/waybar-timer/paused ; }
18+
minutesLeftWhenPaused () { echo $(( ( $(secondsLeftWhenPaused) + 59 ) / 60 )) ; }
19+
secondsLeft () { echo $(( $(timerExpiry) - $(now) )) ; }
20+
minutesLeft () { echo $(( ( $(secondsLeft) + 59 ) / 60 )) ; }
21+
22+
printExpiryTime () { dunstify -u low -r -12345 "Timer expires at $( date -d "$(secondsLeft) sec" +%H:%M)" ;}
23+
printPaused () { dunstify -u low -r -12345 "Timer paused" ; }
24+
removePrinting () { dunstify -C -12345 ; }
25+
26+
updateTail () {
27+
# check whether timer is expired
28+
if timerSet
29+
then
30+
if { timerPaused && [ $(minutesLeftWhenPaused) -le 0 ] ; } || { ! timerPaused && [ $(minutesLeft) -le 0 ] ; }
31+
then
32+
eval $(timerAction)
33+
killTimer
34+
removePrinting
35+
fi
36+
fi
37+
38+
# update output
39+
if timerSet
40+
then
41+
if timerPaused
42+
then
43+
echo "{\"text\": \"$(minutesLeftWhenPaused)\", \"alt\": \"paused\", \"tooltip\": \"Timer paused\", \"class\": \"timer\" }"
44+
else
45+
echo "{\"text\": \"$(minutesLeft)\", \"alt\": \"running\", \"tooltip\": \"Timer expires at $( date -d "$(secondsLeft) sec" +%H:%M)\", \"class\": \"timer\" }"
46+
fi
47+
else
48+
echo "{\"text\": \"0\", \"alt\": \"standby\", \"tooltip\": \"No timer set\", \"class\": \"timer\" }"
49+
fi
50+
}
51+
52+
## MAIN CODE
53+
54+
case $1 in
55+
updateandprint)
56+
updateTail
57+
;;
58+
new)
59+
killTimer
60+
mkdir /tmp/waybar-timer
61+
echo "$(( $(now) + 60*${2} ))" > /tmp/waybar-timer/expiry
62+
echo "${3}" > /tmp/waybar-timer/action
63+
printExpiryTime
64+
;;
65+
increase)
66+
if timerSet
67+
then
68+
if timerPaused
69+
then
70+
echo "$(( $(secondsLeftWhenPaused) + ${2} ))" > /tmp/waybar-timer/paused
71+
else
72+
echo "$(( $(timerExpiry) + ${2} ))" > /tmp/waybar-timer/expiry
73+
printExpiryTime
74+
fi
75+
else
76+
exit 1
77+
fi
78+
;;
79+
cancel)
80+
killTimer
81+
removePrinting
82+
;;
83+
togglepause)
84+
if timerSet
85+
then
86+
if timerPaused
87+
then
88+
echo "$(( $(now) + $(secondsLeftWhenPaused) ))" > /tmp/waybar-timer/expiry
89+
rm -f /tmp/waybar-timer/paused
90+
printExpiryTime
91+
else
92+
secondsLeft > /tmp/waybar-timer/paused
93+
rm -f /tmp/waybar-timer/expiry
94+
printPaused
95+
fi
96+
else
97+
exit 1
98+
fi
99+
;;
100+
*)
101+
echo "Please read the manual at https://github.com/jbirnick/waybar-timer ."
102+
;;
103+
esac

0 commit comments

Comments
 (0)