diff options
| -rw-r--r-- | README.md | 131 |
1 files changed, 129 insertions, 2 deletions
@@ -1,10 +1,137 @@ # Polydoro -Pomodoro widget for polybar and friends. Pretty rusty, I'd say! +Pomodoro widget for polybar and friends <img src="/polydoro/plain/polydoro.png" alt="Polydoro Artwork" height="100"/> -## Licence +Polydoro is a pomodoro timer made for polybar, lemonbar and probably other status bars. +There is a single daemon and there can be multiple listeners, so all your bars can show +the same widget. It can be controlled through the polydoro command, which can even be +added to your statusbar (clicked, etc) or can be controlled through your window manager's +keybindings. + +# Usage + +## Starting the daemon + +Use `polydoro -d` to start a daemon. (I'd recommend adding this to your `.xprofile`, etc) + +If you attempt to start multiple daemons, it'll +return an error. If you're sure all other instances have been killed, you need to delete +`/tmp/polydorod.sock` and `/tmp/polydorocmd.sock` before starting the daemon again. + +## Hooking it up with polybar + +Use this module: + +``` ini +[module/polydoro] +type = custom/script +exec = polydoro -l +tail = true + +# optional +click-left = polydoro toggle +click-middle = polydoro skip +click-right = polydoro reset +``` + +## Controlling polydoro: + +The `polydoro` command can be used to send commands to the daemon. +You can do a `polydoro -h` for details. + +### Available commands: + +#### polydoro run + +This is used to start the timer, or resume the timer if it's paused. +Otherwise, this command is ignored. + +#### polydoro pause + +Pause a running timer. If the timer is idle (not started yet) or already paused, +this command is ignored. + +#### polydoro toggle + +This will conditionally perform a run or a pause operation, whichever is applicable. +This command is useful for polybar's click response, as we don't have much room for +multiple commands. + +#### polydoro skip + +This skips the currently running timer and moves on to the next timer. If the timer is +idle (not started yet) or paused, this command is ignored. + +#### polydoro soft-reset + +Jump to the beginning of the current timer, i.e reset the current timer. + +#### polydoro hard-reset + +Jump to the beginning of the first timer, i.e go back to the initial state. + +#### polydoro reset + +Conditionally perform a soft or a hard reset. If soft-reset is applicable, do that. +Otherwise, do a hard reset (running this command twice in a row would always do a +hard reset). This command is useful for polybar's click response, as we don't have +much room for multiple commands. + +## Configuration + +Config is passed as environment variables. + +### Daemon config + +In the polydoro daemon we have the following options: + +**Note: All duration values are in seconds.** + +| Variable | Description | Default Value | +| --------------------- | ------------------------------------- | ----------------- | +| `WORK_DURATION` | Duration of the work timer | 1500 (25 minutes) | +| `BREAK_DURATION` | Duration of the short break timer | 300 (5 minutes) | +| `LONG_BREAK_DURATION` | Duration of the long break timer | 1200 (20 minutes) | +| `LONG_BREAK_INTERVAL` | Number of work cycles till long break | 4 | + +Example: + +```fish +WORK_DURATION=1200 polydoro -d +``` + +### Listener config + +It is possible to format the output given by each listener individually. Through some +polybar formatting magic it's also possible to have different foreground colors, +background colors, and even nerd fonts. + +We have two (optional) variables that can be used in formatting. + +- `{time}` shows the remaining time in mm:ss format +- `{counter}` shows the sequence number of the cycle (starting from 1) + +| Variable | Default Value | +| -------------------------- | --------------------------------- | +| `FORMAT_WORK` | `WORK {counter} - {time}` | +| `FORMAT_WORK_IDLE` | `(WORK) {counter}` | +| `FORMAT_WORK_PAUSED` | `[WORK] {counter} - {time}` | +| `FORMAT_BREAK` | `BREAK {counter} - {time}` | +| `FORMAT_BREAK_IDLE` | `(BREAK) {counter}` | +| `FORMAT_BREAK_PAUSED` | `[BREAK] {counter} - {time}` | +| `FORMAT_LONG_BREAK` | `LONG BREAK {counter} - {time}` | +| `FORMAT_LONG_BREAK_IDLE` | `(LONG BREAK) {counter}` | +| `FORMAT_LONG_BREAK_PAUSED` | `[LONG BREAK] {counter} - {time}` | + +Example: + +```fish +FORMAT_WORK="working - {time}" FORMAT_BREAK="taking a break - {time}" polydoro -l +``` + +# Licence Licenced under GNU General Public Licence V3 |