# 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

`icing` can be used in two ways.

1. Specify a wallpaper explicitly as an argument  

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

Sets the wallpaper immediately without modifying the config file.  

2. Use the config file

```sh
icing
```

Run without arguments to apply the wallpaper defined in the config file.
Fails if no config exists.

See below for config instructions.


### Additional options

#### `--mode`  

Use the `--mode` option to specify the image scaling mode.

```sh
icing --set /path/to/image.png --mode fill
```

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


#### `--update`  
Use the `--update` flag to persist the new settings to the config file.

```sh
icing --set /path/to/image.png --update  
icing --set /path/to/image.png --mode stretch --update
```

- Sets the wallpaper  
- Writes the settings to the config file  
- Future runs of `icing` will reuse these settings  


## 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