setroot 0.2.0

A library for setting desktop background image
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

# setroot

A library for setting desktop background image.  It provides methods and types
for a) querying screen’s monitor configuration, b) creating a pixmap which can
be used as a background image and c) changing the root background.

The library serves the purpose similar to applications such as `Esetroot`,
`xsetroot`, `fvwm-root` etc.  Since it communicates directly with the X display
it does not require external applications to accomplish its task.


## Example usage

```rust,no_run
fn set_background() -> Result<(), setroot::Error> {
    // Connect to X display server.
    let display = setroot::Display::open()?;
    // Create a pixmap to use as the background.
    let root_pixmap = display.root_pixmap()?;
    // Query monitor configuration of the screen.
    let monitors = display.monitors()?;
    // Iterate over all monitors and draw background for each
    // of them.
    for monitor in monitors {
        // Load an image to fit the monitor.
        let image: image::RgbImage =
            load_image_for_dimension(
                monitor.width, monitor.height)?;
        // Draw the image onto the pixmap.
        root_pixmap.put_image(monitor.x, monitor.y, image)?;
    }
    // Set the background.
    root_pixmap.set_background()?;
    Ok(())
}

fn load_image_for_dimension(
    width: u16,
    height: u16,
) -> Result<image::RgbImage, setroot::Error> {
    todo!()
}
```


## Features

The crate defines the following Cargo feature:

* `image`, enabled by default, adds support for `image` crate and its
  `DynamicImage` type which can be rendered via `put_image` method and are
  automatically converted into proper format in sRGB colour space.


## Limitations

The library has currently tho following limitations:

* It does not offer features for resizing images or tiling images.  It is left
  to the user to prepare correctly sized image that can be draw on the root
  pixmap.

* It works with X11 display servers only and requires RandR 1.5+ extension to be
  present.  This covers vast majority of X11 displays but might not work on
  Wayland desktops or in non-Unix-like environments.

* It assumes the X display server uses 24/32-bit True Colour visual, i.e. that
  colours are represented as 32-bit numbers with 8 bits per channel.  This
  should cover *vast* majority of cases and system configurations.