# fluxTimer

A Window Maker style countdown / alarm timer dockapp for the Fluxbox slit.
Shows time remaining in the dock window, pops up a custom alert with a
user-supplied message when the timer ends, and plays a sound that can be
silenced with one click.

Part of the [Flux Dock Apps Suite](https://osugisakae.com/software/flux-dock-apps/).

## Screenshot

```
Idle              Running           Alerting
┌──────────┐    ┌──────────┐    ┌──────────┐
│ TIMER    │    │ TIMER    │    │ TIMER    │
│──────────│    │──────────│    │──────────│
│   IDLE   │    │  04:37   │    │  ALARM!  │
│          │    │ END 15:42│    │  L:OPEN  │
│  L:SET   │    │ NORMAL   │    │  M:STOP  │
└──────────┘    └──────────┘    └──────────┘
```

## Installation

Requires Rust and a working X11 environment.

```sh
cargo build --release
cp target/release/fluxTimer ~/.local/bin/
```

The release build is stripped and LTO-optimized. No runtime dependencies
beyond libc, libX11, and an audio player (`mpv`, `ffplay`, `paplay`, `aplay`,
or `play` - first one found on PATH is used).

## Usage

```
fluxTimer [OPTIONS]
```

Add `fluxTimer` to your Fluxbox startup to embed it in the slit.

### Options

| Flag | Description |
|---|---|
| `--size SIZE` | Window size: 64, 96 (default), or 128 pixels |
| `--font PATH` | Path to a TTF/OTF font file |
| `--importance LEVEL` | Default importance: low, normal, critical |
| `--sound PATH` | Audio file for the current importance level |
| `--player CMD` | Audio player command (auto-detected otherwise) |
| `--background`, `--bg` | Run in background |
| `--write-config [PATH]` | Write annotated config file and exit |
| `--configure` | Interactive configuration wizard |
| `--help` | Show help message |

## Interaction

All interaction happens through clicks on the dock window:

| Click | State | Action |
|---|---|---|
| Left | idle | Open the **set timer** popup |
| Left | running | Pause the timer |
| Left | paused | Resume the timer |
| Left | alerting | Open the **alert popup** (shows message + Stop Sound button) |
| Middle | idle | Reload config file |
| Middle | running/paused/alerting | Cancel the timer (silences sound) |
| Right | any | Quick-restart the last timer (falls back to setup popup) |

Any of these defaults can be overridden by setting `left_click`, `middle_click`,
or `right_click` in the config file to a shell command.

## Setting a timer

Left-click the dock window to open the setup popup. It lets you choose:

- **Mode** — Countdown (a duration) or Alarm (a clock time)
- **Time** — a number of minutes (`5`, `0.5`), `M:SS` (`1:30`),
  `H:MM:SS` (`2:15:00`), or `HH:MM` in alarm mode (`15:30` for 3:30 PM)
- **Level** — low, normal, critical (selects the sound and whether it loops)
- **Message** — custom text shown in the alert popup when the timer fires

Keyboard: Tab cycles text fields, Enter starts the timer, Escape cancels.
Mouse: click a toggle to select it.

## When the timer fires

The dock window flashes `ALARM!` and the importance-appropriate sound plays.
Left-click opens the alert popup, which shows your custom message plus
**Stop Sound** and **Dismiss** buttons. Middle-click on the dock window
cancels silently.

## Sounds

Drop audio files into `~/.config/fluxTimer/sounds/` and they are picked up
automatically:

- `low.{ogg,mp3,wav}` — low-importance timers
- `default.{ogg,mp3,wav}` — normal-importance timers
- `critical.{ogg,mp3,wav}` — critical-importance timers (loops by default)

Or point to specific files via `low_audio`, `default_audio`, `critical_audio`
in the config.

## Configuration

The config lives at `~/.config/fluxTimer/config`. Generate an annotated
one with:

```sh
fluxTimer --write-config
```

Or walk through an interactive wizard:

```sh
fluxTimer --configure
```

See the annotated `config` file in this repo for all options.

## License

CC0 1.0 Universal (public domain). See `LICENSE`.