# fluxKeyboardLayout

A Window Maker style keyboard layout display/switcher dockapp for the Fluxbox
slit. Shows the current XKB layout with a country flag and indicator dots.
Left-click cycles through configured layouts via setxkbmap.

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

## Screenshot

```
┌──────────┐
│   KBD    │
│──────────│
│  🇺🇸     │  ← country flag
│   US     │
│──────────│
│  ● ○ ○  │  ← layout indicator dots
└──────────┘
```

## Installation

Requires Rust and a working X11 environment.

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

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

## Usage

```
fluxKeyboardLayout [OPTIONS]
```

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

### Options

| Flag | Description |
|---|---|
| `--layouts LIST` | Comma-separated layout specs to cycle through |
| `--size SIZE` | Window size: 64, 96 (default), or 128 pixels |
| `--font PATH` | Path to a TTF/OTF font file |
| `--background`, `--bg` | Run in background |
| `--write-config [PATH]` | Write annotated config file and exit |
| `--configure` | Interactive configuration wizard |
| `--help` | Show help message |

### Layout format

Layouts are specified as `layout` or `layout(variant)`:
- `us` — US QWERTY
- `us(dvorak)` — US Dvorak
- `de` — German
- `us(colemak)` — Colemak

### Click behavior

| Button | Action |
|---|---|
| Left click | Cycle to next keyboard layout (or run `left_click` command) |
| Middle click | Run `middle_click` command (if configured) |
| Right click | Open character map (or run `right_click` command) |

### Label auto-generation

Layout labels are generated automatically:
- `dvorak` → DVK, `colemak` → CMK, `colemak_dh` → CDH
- `workman` → WKM, `norman` → NRM
- Otherwise: first 3 chars of variant, or uppercase layout name

### Flags

Built-in procedural flags are included for many countries (US, GB, DE, FR, IT,
SE, NO, JP, BR, etc.). Custom flag PNGs can be placed at
`~/.local/share/fluxKeyboardLayout/<layout>.png`.

## Configuration

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

Generate an annotated config with auto-detected charmap programs:

```sh
fluxKeyboardLayout --write-config
```

Or use the interactive wizard:

```sh
fluxKeyboardLayout --configure
```

### Config options

```ini
# Keyboard layouts to cycle through
layouts = us, us(dvorak), de

# Custom display labels (comma-separated, matching layouts order)
labels = US, DVK, DE

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

# Font file path (leave unset for auto-detect via fontconfig)
font = /path/to/font.ttf

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

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

# Override left click action (default: cycle layouts)
left_click =

# Middle click action
middle_click =

# Override right click action (default: open character map)
right_click =

# Run as daemon
background = true
```

### Right-click charmap discovery

If `right_click` is not configured, fluxKeyboardLayout probes PATH for:
gucharmap, gnome-characters, kcharselect, xcharmap, charmap.

### External change detection

fluxKeyboardLayout re-queries `setxkbmap -query` every 2 seconds to detect
layout changes made by other tools.

### Font discovery

Font is resolved in order:
1. `--font` flag or `font` config option
2. fontconfig (`fc-match monospace`)
3. Hardcoded paths (DejaVu Sans Mono, Liberation Mono, Noto Sans Mono)

## License

[CC0 1.0](LICENSE) — Public Domain