# fluxLauncher

A Window Maker style app launcher dockapp for the Fluxbox slit.
Displays a 2x2 grid of application launcher buttons with auto-discovered
XDG icons.

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

## Screenshot

```
┌─────────┬─────────┐
│         │         │
│   [1]   │   [2]   │
├─────────┼─────────┤
│         │         │
│   [3]   │   [4]   │
└─────────┴─────────┘
```

## Installation

Requires Rust and a working X11 environment.

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

The release build is stripped and LTO-optimized. No runtime dependencies beyond
libc and libX11.

## Usage

```
fluxLauncher [OPTIONS]
```

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

### Options

| Flag | Description |
|---|---|
| `--size SIZE` | Window size: 64, 96 (default), or 128 pixels |
| `--background`, `--bg` | Run in background |
| `--write-config [PATH]` | Write annotated config file and exit |
| `--configure` | Interactive configuration wizard |
| `--help` | Show help message |

### Button layout

```
┌─────────┬─────────┐
│   [1]   │   [2]   │
├─────────┼─────────┤
│   [3]   │   [4]   │
└─────────┴─────────┘
```

| Button | Action |
|---|---|
| Left click | Launch the button's configured command |
| Middle click (on button) | Run per-button `middle` command if set |
| Middle click (fallback) | Run `middle_click` command, or reload config |
| Right click (on button) | Run per-button `right` command if set |

Each button highlights briefly on press for visual feedback. Icons are
auto-discovered from XDG icon directories — no font required.

### Icon auto-discovery

Icons are resolved in order for each button's command:

1. **hicolor theme** — `/usr/share/icons/hicolor/{size}/apps/{name}.png` (sizes sorted by closeness to cell pixels)
2. **pixmaps** — `/usr/share/pixmaps/{name}.png`
3. **.desktop file** — reads `Icon=` from `/usr/share/applications/{name}.desktop` or `~/.local/share/applications/`, re-searches with that icon name
4. **-bin variant** — tries `{name}-bin` (Gentoo packages like `firefox-bin`)
5. **Placeholder** — outlined rect with titlebar if nothing found

Override auto-discovery with `icon1 = /path/to/icon.png` in the config.

## Configuration

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

Generate an annotated config:

```sh
fluxLauncher --write-config
```

Or use the interactive wizard:

```sh
fluxLauncher --configure
```

### Config options

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

# Main color (R, G, B)
color = 0, 255, 0

# Dim color (R, G, B)
dim_color = 0, 200, 0

# Button commands — run via "sh -c", inheriting the desktop session
# environment. Program names, full paths, and arguments all work.
# You can also use gtk-launch, xdg-open, xdg-email, etc.
#   command1 = firefox                          # program in $PATH
#   command1 = /usr/bin/firefox --private-window # full path + args
#   command1 = gtk-launch firefox.desktop        # launch .desktop file
#   command1 = xdg-open ~/Documents              # default file handler
command1 = firefox
command2 = kitty
command3 = thunar
command4 = gimp

# Icon overrides (auto-discovered if omitted)
# icon1 = /path/to/icon.png

# Per-button middle/right click
# middle1 = command
# right1 = command

# Global middle click fallback (default: reload config)
# middle_click =

# Run in the background
background = true
```

## License

[CC0 1.0](LICENSE) — Public Domain