setroot 0.1.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
70
71
72
73

# 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,ignore
fn set_background() -> Result<(), 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,
            setroot::ImageView::from(&image))?;
    }
    // Set the background.
    root_pixmap.set_background()?;
    Ok(())
}

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

enum Error { /* TODO */ }
```


## Features

The crate defines the following Cargo feature:

* `image`, enabled by default, includes dependency on `image` crate and allows
  `image::RgbImage` objects to be passed as arguments to `put_image` function.


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