158 lines
3.2 KiB
Markdown
158 lines
3.2 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
|
|
|
|
`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
|
|
|