candifloss
960ca4489a
- Description - Usage instructions - Config instructions - Install instructions - Requirements - Future plans - Notes
160 lines
2.9 KiB
Markdown
160 lines
2.9 KiB
Markdown
# 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
|
|
|