# fluxPics

A Window Maker style picture viewer dockapp for the Fluxbox slit. Displays
images from a directory with aspect-ratio-preserving Lanczos3 scaling.
Left-click opens the current image in a viewer, right-click advances to the
next image.

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

## Screenshot

```
┌──────────────┐
│              │
│   [image]    │  ← scaled image with letterboxing
│              │
└──────────────┘
```

## Installation

Requires Rust and a working X11 environment.

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

The release build is stripped and LTO-optimized. No runtime dependencies beyond
libc and libX11. No font dependency — image only, no text rendering.

## Usage

```
fluxPics [OPTIONS]
```

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

### Options

| Flag | Description |
|---|---|
| `--size SIZE` | Window size: 64, 96 (default), or 128 pixels |
| `--directory PATH` | Directory containing images |
| `--interval SECS` | Auto-advance interval in seconds (0 = manual only) |
| `--viewer CMD` | Image viewer command |
| `--background`, `--bg` | Run in background |
| `--write-config [PATH]` | Write annotated config file and exit |
| `--configure` | Interactive configuration wizard |
| `--help` | Show help message |

### Click behavior

| Button | Action |
|---|---|
| Left click | Open current image in viewer (or run `left_click` command) |
| Middle click | Run `middle_click` command (if configured) |
| Right click | Advance to next image (or run `right_click` command) |

### Image formats

PNG, JPEG, GIF, BMP, and WebP are supported.

### Viewer auto-detection

Viewer is resolved in order:
1. `--viewer` CLI flag
2. `viewer` config option
3. Auto-detect: feh, imv, eog, eom, ristretto, gpicview, xdg-open

### Image cycling

Images cycle through the directory contents. On wrap-around, the directory is
re-scanned to pick up new files. Optional shuffle mode uses an xorshift PRNG
(no external random number crate).

### Rendering

Images are scaled with Lanczos3 interpolation preserving aspect ratio, centered
with black letterboxing and a sunken border.

## Configuration

Config file: `~/.config/fluxPics/config`

Generate an annotated config:

```sh
fluxPics --write-config
```

Or use the interactive wizard:

```sh
fluxPics --configure
```

### Config options

```ini
# Directory containing images (required)
directory = ~/Pictures

# Auto-advance interval in seconds (0 = manual only)
interval = 0

# Shuffle images
shuffle = false

# Image viewer command (auto-detected if not set)
viewer = feh

# Window size: 64, 96, or 128 pixels
size = 96

# Left click command (default: open in viewer)
left_click =

# Middle click command
middle_click =

# Right click command (default: next image)
right_click =

# Run in the background
background = true
```

## License

[CC0 1.0](LICENSE) — Public Domain