# Icing: The sweet coating on your desktop 🍰

**`icing`** is a small, fast X11 wallpaper setter written in Rust.

It sets a wallpaper directly on the X11 root window, without daemons, background services, or unnecessary dependencies.
Configuration is optional, and the app exits immediately after setting the wallpaper.

## Features

* Simple CLI usage
* Optional config file
* Two image scaling modes: **Fill** and **Stretch**
* Minimal dependencies
* X11 only (Wayland not supported)

---

## Usage

### Set wallpaper once (no config change)

```sh
icing --set /path/to/image.png
```
Sets the wallpaper immediately but does **not** update the config file.

### Update config and set wallpaper

```sh
icing --update /path/to/image.png
```

* Writes the image path to the config file
* Sets the wallpaper immediately
* Future runs of `icing` will reuse this image

### Use config only

```sh
icing
```  

Uses the image path and settings from the config file.  
Fails if no config exists.  

### Optional arguments

```sh
--mode fill|stretch
```  

Overrides the default or configured scaling mode (see below).


## Configuration

Config file location:

```text
~/.config/candywidgets/icing/config.toml
```

Example config:

```toml
background_image = "/path/to/image.png"
mode = "fill"
```

### Config options

| Key                | Description                        |
| ------------------ | ---------------------------------- |
| `background_image` | Path to the wallpaper image        |
| `mode`             | Scaling mode (`fill` or `stretch`) |

If `mode` is missing, **`fill` is used by default**.

Invalid modes cause `icing` to exit with an error.


## Scaling modes

| `fill` (default)                | `stretch`                                |
| ------------------------------- | ---------------------------------------- |
| Covers the entire screen        | Covers the entire screen                 |
| Aspect ratio preserved          | Aspect ratio not preserved               |
| Excess image cropped (centered) | Image may be stretched and distorted     |
| Best choice for most wallpapers | Useful for exact fits or abstract images |


## Installation

### Build from source

```sh
git clone https://git.candifloss.cc/candifloss/icing.git
cd icing
cargo build --release
```

Binary will be located at:

```text
target/release/icing
```

Optionally move it to your `$PATH` (for example `/usr/bin/`) if desired.


## Requirements

* X11 (Xorg)
* A window manager
* Rust (for building)


## Future plans

* Multi-monitor support via `--monitor <MONITOR>`

  ```sh
  icing --monitor HDMI-1 --set image.png
  icing --monitor HDMI-2 --set image2.jpg --mode stretch
  ```

* Probably not:

  * Additional scaling modes (unless they make sense)
  * Wayland support


## Notes

* `icing` does not run in the background
* No daemon, no config watcher
* Intended to be called explicitly (startup scripts, keybindings, etc.)

---

## License

GPL-3.0-or-later