Crate layer_shika

Expand description

layer-shika: A Wayland layer shell library with Slint UI integration

This crate provides a high-level API for creating Wayland widget components with Slint-based user interfaces. It’s built on a clean architecture with three internal layers (domain, adapters, composition), but users should only depend on this root crate.

§Architecture Note

layer-shika is internally organized as a Cargo workspace with three implementation crates:

layer-shika-domain: Core domain models and business logic
layer-shika-adapters: Wayland and rendering implementations
layer-shika-composition: Public API composition layer

Users should never import from these internal crates directly. This allows the internal architecture to evolve without breaking semver guarantees on the public API.

§Module Organization

The API is organized into conceptual facets:

shell – Main runtime and shell composition types
window – Surface configuration, layers, anchors, and popup types
output – Output (monitor) info, geometry, and policies
event – Event loop handles and contexts
slint_integration – Slint framework re-exports and wrappers
calloop – Event loop types for custom event sources

§Quick Start (Fluent Builder)

Single-surface use case with the fluent builder API:

use layer_shika::prelude::*;

Shell::from_file("ui/bar.slint")
    .surface("Main")
        .height(42)
        .anchor(AnchorEdges::top_bar())
        .exclusive_zone(42)
    .build()?
    .run()?;

See the simple-bar example for a complete working implementation.

§Declarative Configuration

For reusable, programmatically generated, or externally sourced configurations:

use layer_shika::prelude::*;

let config = ShellConfig {
    ui_source: CompiledUiSource::file("ui/bar.slint"),
    surfaces: vec![
        SurfaceComponentConfig::with_config("Bar", SurfaceConfig {
            dimensions: SurfaceDimension::new(0, 42),
            anchor: AnchorEdges::top_bar(),
            exclusive_zone: 42,
            ..Default::default()
        }),
    ],
};

Shell::from_config(config)?.run()?;

See the declarative-config example for a complete working implementation.

§Multi-Surface Shell

Same API naturally extends to multiple surfaces:

use layer_shika::prelude::*;

Shell::from_file("ui/shell.slint")
    .surface("TopBar")
        .height(42)
        .anchor(AnchorEdges::top_bar())
    .surface("Dock")
        .height(64)
        .anchor(AnchorEdges::bottom_bar())
    .build()?
    .run()?;

See the multi-surface example for a complete working implementation.

§Pre-compiled Slint

For explicit compilation control:

use layer_shika::prelude::*;

let compilation = Shell::compile_file("ui/shell.slint")?;

Shell::from_compilation(compilation)
    .surface("TopBar")
        .output_policy(OutputPolicy::AllOutputs)
        .height(42)
    .surface("Dock")
        .output_policy(OutputPolicy::PrimaryOnly)
        .height(64)
    .build()?
    .run()?;

§Examples

Comprehensive examples demonstrating all features are available in the examples directory.

Run any example with: cargo run -p <example-name>

Re-exports§

pub use slint_integration::slint;
pub use slint_integration::slint_interpreter;

Modules§

calloop
event
output
prelude: Prelude module re-exporting all public API types
shell
slint_integration
window

Structs§

AnchorEdges: Represents which edges of the output a layer surface should be anchored to.
CallbackContext: Context provided to callback handlers with surface and control information
EventDispatchContext
EventLoopHandle: Handle for registering custom event sources with the event loop
Handle: Type-safe unique identifier for runtime resources
LayerSurfaceHandle: Low-level handle for configuring layer-shell surface properties
OutputGeometry: Physical geometry and properties of an output
OutputInfo: Runtime information about a connected output (monitor)
OutputRegistry
PopupRequest: Configuration for showing a popup window
PopupWindow
Selection: A selection of surfaces matching a selector
Selector: Combined surface and output selector for precise targeting
Shell: Main runtime for managing Wayland layer-shell surfaces with Slint UI
ShellBuilder: Builder for configuring and creating a Shell with one or more surfaces
ShellConfig: Declarative configuration for creating a shell with multiple surfaces
ShellControl: Handle for runtime control of shell operations
ShellEventContext: Context providing access to shell state within custom event source callbacks
ShellEventLoop: Main event loop for the shell runtime
SurfaceComponentConfig: Associates a Slint component name with its surface configuration
SurfaceConfigBuilder: Builder for configuring a single surface within a Shell
SurfaceDefinition: Definition of a surface including component name and configuration
SurfaceInfo: Runtime information about a surface instance
SurfaceInstanceId

Enums§

AnchorStrategy: Strategy for calculating popup position relative to an anchor rectangle
CompiledUiSource: Source for Slint UI definition
Error: Error types for layer-shika operations
KeyboardInteractivity: Controls how a surface receives keyboard input
Layer: Vertical stacking layer for layer-shell surfaces
Output: Selector for targeting outputs (monitors) in runtime operations
OutputPolicy: Determines which outputs (monitors) should display the surface
PopupPlacement: Where to position a popup relative to the surface
PopupPositioningMode: Alignment mode for popup positioning
PopupSize: How to size a popup window
Surface: Selector for targeting surfaces when setting up callbacks or runtime configuration
SurfaceTarget

Constants§

DEFAULT_COMPONENT_NAME: Default Slint component name used when none is specified
DEFAULT_SURFACE_NAME: Default surface name used internally

Traits§

ShellRuntime: Trait providing runtime access to shell components and event loop
ShellSurfaceConfigHandler

Type Aliases§

OutputHandle: Unique identifier for an output (monitor)
PopupHandle: Unique identifier for a popup window
Result: Result type alias using layer-shika’s Error
SurfaceHandle: Unique identifier for a layer surface