layer_shika/
lib.rs

1//! layer-shika: A Wayland layer shell library with Slint UI integration
2//!
3//! This crate provides a high-level API for creating Wayland widget components
4//! with Slint-based user interfaces. It's built on a clean architecture with three
5//! internal layers (domain, adapters, composition), but users should only depend on
6//! this root crate.
7//!
8//! # Architecture Note
9//!
10//! layer-shika is internally organized as a Cargo workspace with three implementation
11//! crates:
12//! - `layer-shika-domain`: Core domain models and business logic
13//! - `layer-shika-adapters`: Wayland and rendering implementations
14//! - `layer-shika-composition`: Public API composition layer
15//!
16//! **Users should never import from these internal crates directly.** This allows
17//! the internal architecture to evolve without breaking semver guarantees on the
18//! public API.
19//!
20//! # Module Organization
21//!
22//! The API is organized into conceptual facets:
23//!
24//! - [`shell`] – Main runtime and shell composition types
25//! - [`window`] – Surface configuration, layers, anchors, and popup types
26//! - [`output`] – Output (monitor) info, geometry, and policies
27//! - [`event`] – Event loop handles and contexts
28//! - [`slint_integration`] – Slint framework re-exports and wrappers
29//! - [`calloop`] – Event loop types for custom event sources
30//!
31//! # Quick Start (Fluent Builder)
32//!
33//! Single-surface use case with the fluent builder API:
34//!
35//! ```rust,no_run
36//! use layer_shika::prelude::*;
37//!
38//! Shell::from_file("ui/bar.slint")
39//!     .surface("Main")
40//!         .height(42)
41//!         .anchor(AnchorEdges::top_bar())
42//!         .exclusive_zone(42)
43//!     .build()?
44//!     .run()?;
45//! # Ok::<(), layer_shika::Error>(())
46//! ```
47//!
48//! **See the [simple-bar example](https://codeberg.org/waydeer/layer-shika/src/examples/simple-bar) for a complete working implementation.**
49//!
50//! # Declarative Configuration
51//!
52//! For reusable, programmatically generated, or externally sourced configurations:
53//!
54//! ```rust,no_run
55//! use layer_shika::prelude::*;
56//!
57//! let config = ShellConfig {
58//!     ui_source: CompiledUiSource::file("ui/bar.slint"),
59//!     surfaces: vec![
60//!         SurfaceComponentConfig::with_config("Bar", SurfaceConfig {
61//!             dimensions: SurfaceDimension::new(0, 42),
62//!             anchor: AnchorEdges::top_bar(),
63//!             exclusive_zone: 42,
64//!             ..Default::default()
65//!         }),
66//!     ],
67//! };
68//!
69//! Shell::from_config(config)?.run()?;
70//! # Ok::<(), layer_shika::Error>(())
71//! ```
72//!
73//! **See the [declarative-config example](https://codeberg.org/waydeer/layer-shika/src/examples/declarative-config) for a complete working implementation.**
74//!
75//! # Multi-Surface Shell
76//!
77//! Same API naturally extends to multiple surfaces:
78//!
79//! ```rust,no_run
80//! use layer_shika::prelude::*;
81//!
82//! Shell::from_file("ui/shell.slint")
83//!     .surface("TopBar")
84//!         .height(42)
85//!         .anchor(AnchorEdges::top_bar())
86//!     .surface("Dock")
87//!         .height(64)
88//!         .anchor(AnchorEdges::bottom_bar())
89//!     .build()?
90//!     .run()?;
91//! # Ok::<(), layer_shika::Error>(())
92//! ```
93//!
94//! **See the [multi-surface example](https://codeberg.org/waydeer/layer-shika/src/examples/multi-surface) for a complete working implementation.**
95//!
96//! # Pre-compiled Slint
97//!
98//! For explicit compilation control:
99//!
100//! ```rust,no_run
101//! use layer_shika::prelude::*;
102//!
103//! let compilation = Shell::compile_file("ui/shell.slint")?;
104//!
105//! Shell::from_compilation(compilation)
106//!     .surface("TopBar")
107//!         .output_policy(OutputPolicy::AllOutputs)
108//!         .height(42)
109//!     .surface("Dock")
110//!         .output_policy(OutputPolicy::PrimaryOnly)
111//!         .height(64)
112//!     .build()?
113//!     .run()?;
114//! # Ok::<(), layer_shika::Error>(())
115//! ```
116//!
117//! # Examples
118//!
119//! Comprehensive examples demonstrating all features are available in the
120//! [examples directory](https://codeberg.org/waydeer/layer-shika/src/examples).
121//!
122//! Run any example with: `cargo run -p <example-name>`
123
124#![allow(clippy::pub_use)]
125
126pub mod prelude;
127
128pub mod event;
129pub mod output;
130pub mod shell;
131pub mod slint_integration;
132pub mod window;
133
134pub use layer_shika_composition::{
135    CallbackContext, Error, Handle, Result, SurfaceHandle, SurfaceInstanceId, SurfaceTarget,
136};
137
138pub use shell::{
139    CompiledUiSource, DEFAULT_COMPONENT_NAME, DEFAULT_SURFACE_NAME, LayerSurfaceHandle, Output,
140    Selection, Selector, Shell, ShellBuilder, ShellConfig, ShellControl, ShellEventContext,
141    ShellRuntime, ShellSurfaceConfigHandler, Surface, SurfaceComponentConfig, SurfaceConfigBuilder,
142    SurfaceDefinition, SurfaceInfo,
143};
144
145pub use window::{
146    AnchorEdges, AnchorStrategy, KeyboardInteractivity, Layer, PopupHandle, PopupPlacement,
147    PopupPositioningMode, PopupRequest, PopupSize,
148};
149
150pub use output::{OutputGeometry, OutputHandle, OutputInfo, OutputPolicy, OutputRegistry};
151
152pub use event::{EventDispatchContext, EventLoopHandle, ShellEventLoop};
153
154pub use slint_integration::{PopupWindow, slint, slint_interpreter};
155
156pub mod calloop {
157    pub use layer_shika_composition::calloop::*;
158}
layer_shika/lib.rs

layer_shika/
lib.rs
