wayle_wallpaper/lib.rs
1//! Wallpaper management via awww with cycling and theming support.
2//!
3//! # Quick Start
4//!
5//! ```rust,no_run
6//! use wayle_wallpaper::WallpaperService;
7//! use std::path::PathBuf;
8//!
9//! # async fn example() -> Result<(), wayle_wallpaper::Error> {
10//! let wp = WallpaperService::new().await?;
11//!
12//! // Set wallpaper on all monitors
13//! wp.set_wallpaper(PathBuf::from("/path/to/image.jpg"), None).await?;
14//!
15//! // Check current state
16//! for (monitor, state) in wp.monitors.get().iter() {
17//! println!("{}: {:?} (fit: {})", monitor, state.wallpaper, state.fit_mode);
18//! }
19//! # Ok(())
20//! # }
21//! ```
22//!
23//! # Directory Cycling
24//!
25//! ```rust,no_run
26//! # use wayle_wallpaper::{WallpaperService, CyclingMode};
27//! # use std::path::PathBuf;
28//! # use std::time::Duration;
29//! # async fn example() -> Result<(), wayle_wallpaper::Error> {
30//! # let wp = WallpaperService::new().await?;
31//! // Cycle through a directory
32//! wp.start_cycling(
33//! PathBuf::from("/path/to/wallpapers"),
34//! Duration::from_secs(300),
35//! CyclingMode::Sequential,
36//! )?;
37//!
38//! // Manual navigation
39//! wp.advance_cycle().await?;
40//! wp.rewind_cycle().await?;
41//!
42//! wp.stop_cycling();
43//! # Ok(())
44//! # }
45//! ```
46//!
47//! # Configuration
48//!
49//! | Method | Effect |
50//! |--------|--------|
51//! | `transition(TransitionConfig)` | Animation when changing wallpapers |
52//! | `color_extractor(ColorExtractorConfig)` | Tool and parameters for extracting dominant colors |
53//! | `theming_monitor(Option<String>)` | Which monitor drives color extraction |
54//! | `shared_cycle(bool)` | Sync cycling across monitors in shuffle mode |
55//! | `engine_active(bool)` | Toggle awww rendering (state tracking continues) |
56//!
57//! ```rust,no_run
58//! use wayle_wallpaper::{WallpaperService, TransitionConfig, TransitionType};
59//!
60//! # async fn example() -> Result<(), wayle_wallpaper::Error> {
61//! let wp = WallpaperService::builder()
62//! .transition(TransitionConfig {
63//! transition_type: TransitionType::Left,
64//! ..Default::default()
65//! })
66//! .build()
67//! .await?;
68//! # Ok(())
69//! # }
70//! ```
71//!
72//! # Reactive Properties
73//!
74//! All fields are [`Property<T>`](wayle_core::Property):
75//! - `.get()` - Current value snapshot
76//! - `.watch()` - Stream yielding on changes
77//!
78//! # Service Fields
79//!
80//! | Field | Type | Description |
81//! |-------|------|-------------|
82//! | `cycling` | `Option<CyclingConfig>` | Active cycling state |
83//! | `monitors` | `HashMap<String, MonitorState>` | Per-monitor wallpaper and fit mode |
84//! | `transition` | [`TransitionConfig`] | Animation settings |
85//!
86//! # Control Methods
87//!
88//! - `set_wallpaper()` - Apply wallpaper to one or all monitors
89//! - `start_cycling()` / `stop_cycling()` - Directory cycling
90//! - `advance_cycle()` / `rewind_cycle()` - Manual navigation
91//! - `set_fit_mode()` - Change scaling mode per monitor or globally
92//! - `set_transition()` - Configure animations
93//!
94//! # D-Bus Interface
95//!
96//! When `with_daemon()` is enabled, the service registers on the session bus.
97//!
98//! - **Service:** `com.wayle.Wallpaper1`
99//! - **Path:** `/com/wayle/Wallpaper`
100//! - **Interface:** `com.wayle.Wallpaper1`
101//!
102//! See [`dbus.md`](https://github.com/wayle-rs/wayle/blob/master/crates/wayle-wallpaper/dbus.md) for the full interface specification.
103
104mod backend;
105mod builder;
106mod dbus;
107pub mod error;
108mod service;
109mod tasks;
110pub mod types;
111mod wayland;
112
113pub use backend::{
114 BezierCurve, Position, TransitionAngle, TransitionConfig, TransitionDuration, TransitionFps,
115 TransitionStep, TransitionType, WaveDimensions,
116};
117pub use builder::WallpaperServiceBuilder;
118pub use dbus::{SERVICE_NAME, SERVICE_PATH, WallpaperProxy};
119pub use error::Error;
120pub use service::WallpaperService;
121pub use types::{
122 ColorExtractor, ColorExtractorConfig, CyclingConfig, CyclingMode, FitMode, MonitorState,
123};
124
125#[doc = include_str!("../README.md")]
126#[cfg(doctest)]
127pub struct ReadmeDocTests;