From 298225a2714c43fa45146b36f461c7f08cc1dc2b Mon Sep 17 00:00:00 2001 From: drendog Date: Thu, 11 Dec 2025 17:54:56 +0100 Subject: [PATCH] docs: add more docs --- crates/composition/src/event_loop.rs | 23 +++++++++++++++++ crates/composition/src/lib.rs | 2 ++ crates/composition/src/selection.rs | 5 ++++ crates/composition/src/selector.rs | 25 +++++++++++++++++++ crates/composition/src/shell.rs | 17 +++++++++++++ crates/composition/src/shell_config.rs | 13 ++++++++++ crates/composition/src/shell_runtime.rs | 2 ++ crates/composition/src/system.rs | 12 +++++++++ crates/domain/src/config.rs | 4 +++ crates/domain/src/dimensions.rs | 4 +++ .../src/value_objects/anchor_strategy.rs | 8 ++++++ crates/domain/src/value_objects/dimensions.rs | 3 +++ crates/domain/src/value_objects/handle.rs | 7 ++++++ .../value_objects/keyboard_interactivity.rs | 4 +++ crates/domain/src/value_objects/layer.rs | 8 ++++++ crates/domain/src/value_objects/margins.rs | 1 + .../domain/src/value_objects/output_info.rs | 2 ++ .../domain/src/value_objects/output_policy.rs | 4 +++ .../value_objects/popup_positioning_mode.rs | 12 +++++++++ .../domain/src/value_objects/popup_request.rs | 10 ++++++++ crates/domain/src/value_objects/ui_source.rs | 5 ++++ 21 files changed, 171 insertions(+) diff --git a/crates/composition/src/event_loop.rs b/crates/composition/src/event_loop.rs index adb3ba4..9c08d9d 100644 --- a/crates/composition/src/event_loop.rs +++ b/crates/composition/src/event_loop.rs @@ -14,6 +14,10 @@ pub trait FromAppState<'a> { fn from_app_state(app_state: &'a mut AppState) -> Self; } +/// Main event loop for the shell runtime +/// +/// Manages the Wayland event loop and custom event sources. +/// Created internally by `Shell` and started via `Shell::run()`. pub struct ShellEventLoop { inner: Rc>, } @@ -33,6 +37,10 @@ impl ShellEventLoop { } } +/// Handle for registering custom event sources with the event loop +/// +/// Allows adding timers, channels, and file descriptors to the event loop. +/// Obtained via `Shell::event_loop_handle()`. pub struct EventLoopHandle { system: Weak>, } @@ -42,6 +50,9 @@ impl EventLoopHandle { Self { system } } + /// Register a custom event source with the event loop + /// + /// Returns a registration token that can be used to remove the source later. pub fn insert_source(&self, source: S, callback: F) -> Result where S: EventSource + 'static, @@ -60,6 +71,9 @@ impl EventLoopHandle { }) } + /// Add a timer that fires after the specified duration + /// + /// Callback receives the deadline and can return `TimeoutAction::ToInstant` to reschedule. pub fn add_timer(&self, duration: Duration, mut callback: F) -> Result where F: FnMut(Instant, &mut AppState) -> TimeoutAction + 'static, @@ -70,6 +84,9 @@ impl EventLoopHandle { }) } + /// Add a timer that fires at a specific instant + /// + /// Callback receives the deadline and can return `TimeoutAction::ToInstant` to reschedule. pub fn add_timer_at(&self, deadline: Instant, mut callback: F) -> Result where F: FnMut(Instant, &mut AppState) -> TimeoutAction + 'static, @@ -80,6 +97,9 @@ impl EventLoopHandle { }) } + /// Add a channel for sending messages to the event loop from any thread + /// + /// Returns a registration token and sender. Messages sent via the sender trigger the callback. pub fn add_channel( &self, mut callback: F, @@ -97,6 +117,9 @@ impl EventLoopHandle { Ok((token, sender)) } + /// Add a file descriptor to be monitored for readability or writability + /// + /// Callback is invoked when the file descriptor becomes ready according to the interest. pub fn add_fd( &self, fd: T, diff --git a/crates/composition/src/lib.rs b/crates/composition/src/lib.rs index f700f7e..58e7f07 100644 --- a/crates/composition/src/lib.rs +++ b/crates/composition/src/lib.rs @@ -54,8 +54,10 @@ pub mod calloop { pub use layer_shika_adapters::platform::calloop::*; } +/// Result type alias using layer-shika's Error pub type Result = StdResult; +/// Error types for layer-shika operations #[derive(Debug, thiserror::Error)] pub enum Error { #[error("Adapter error: {0}")] diff --git a/crates/composition/src/selection.rs b/crates/composition/src/selection.rs index fc34bf7..2bf9794 100644 --- a/crates/composition/src/selection.rs +++ b/crates/composition/src/selection.rs @@ -5,6 +5,11 @@ use crate::{ }; use layer_shika_domain::errors::DomainError; +/// A selection of surfaces matching a selector +/// +/// Provides methods to interact with all matching surfaces at once, such as +/// setting up callbacks, modifying properties, or accessing component instances. +/// Created via `Shell::select()`. pub struct Selection<'a> { shell: &'a Shell, selector: Selector, diff --git a/crates/composition/src/selector.rs b/crates/composition/src/selector.rs index 43f5f4f..e0a47ff 100644 --- a/crates/composition/src/selector.rs +++ b/crates/composition/src/selector.rs @@ -2,19 +2,31 @@ use crate::{OutputHandle, OutputInfo}; use std::fmt::{Debug, Formatter, Result as FmtResult}; use std::sync::Arc; +/// Runtime information about a surface instance #[derive(Debug, Clone)] pub struct SurfaceInfo { + /// Surface component name pub name: String, + /// Handle to the output displaying this surface pub output: OutputHandle, } +/// Selector for targeting surfaces when setting up callbacks or runtime configuration +/// +/// Use `Surface::named()` to target a specific surface, or combine selectors for complex targeting. #[derive(Clone)] pub enum Surface { + /// Select all surfaces All, + /// Select surface by exact name Named(String), + /// Select any surface matching one of the given names Any(Vec), + /// Select surfaces matching a custom predicate Filter(Arc bool + Send + Sync>), + /// Invert selection Not(Box), + /// Union of multiple selectors Or(Vec), } @@ -86,15 +98,24 @@ impl Debug for Surface { } } +/// Selector for targeting outputs (monitors) in runtime operations #[derive(Clone)] pub enum Output { + /// Select all outputs All, + /// Select the primary output Primary, + /// Select the currently active output Active, + /// Select output by handle Handle(OutputHandle), + /// Select output by name Named(String), + /// Select outputs matching a custom predicate Filter(Arc bool + Send + Sync>), + /// Invert selection Not(Box), + /// Union of multiple selectors Or(Vec), } @@ -179,6 +200,10 @@ impl Debug for Output { } } +/// Combined surface and output selector for precise targeting +/// +/// Combines a surface selector with an output selector to target specific +/// surface instances on specific outputs. #[derive(Clone, Debug)] pub struct Selector { pub surface: Surface, diff --git a/crates/composition/src/shell.rs b/crates/composition/src/shell.rs index 7274dfa..9d60fbf 100644 --- a/crates/composition/src/shell.rs +++ b/crates/composition/src/shell.rs @@ -31,6 +31,7 @@ use std::cell::RefCell; use std::path::{Path, PathBuf}; use std::rc::Rc; +/// Default Slint component name used when none is specified pub const DEFAULT_COMPONENT_NAME: &str = "Main"; enum CompilationSource { @@ -39,6 +40,10 @@ enum CompilationSource { Compiled(Rc), } +/// Builder for configuring and creating a Shell with one or more surfaces +/// +/// Created via `Shell::from_file()`, `Shell::from_source()`, or `Shell::from_compilation()`. +/// Chain `.surface()` calls to configure multiple surfaces, then call `.build()` or `.run()`. pub struct ShellBuilder { compilation: CompilationSource, surfaces: Vec, @@ -118,6 +123,11 @@ impl ShellBuilder { } } +/// Builder for configuring a single surface within a Shell +/// +/// Created by calling `.surface()` on `ShellBuilder`. Chain configuration methods +/// like `.height()`, `.anchor()`, `.exclusive_zone()`, then either start a new surface +/// with `.surface()` or finalize with `.build()` or `.run()`. pub struct SurfaceConfigBuilder { shell_builder: ShellBuilder, component: String, @@ -218,6 +228,10 @@ impl SurfaceConfigBuilder { type OutputConnectedHandler = Box; type OutputDisconnectedHandler = Box; +/// Main runtime for managing Wayland layer-shell surfaces with Slint UI +/// +/// Manages the lifecycle of one or more layer surfaces, event loop integration, +/// and Slint component instantiation. Create via builder methods or `from_config()`. pub struct Shell { inner: Rc>, registry: SurfaceRegistry, @@ -1069,6 +1083,9 @@ impl ShellRuntime for Shell { } } +/// Context providing access to shell state within custom event source callbacks +/// +/// Obtained via event source callbacks registered through `EventLoopHandle`. pub struct ShellEventContext<'a> { app_state: &'a mut AppState, } diff --git a/crates/composition/src/shell_config.rs b/crates/composition/src/shell_config.rs index f657352..974669e 100644 --- a/crates/composition/src/shell_config.rs +++ b/crates/composition/src/shell_config.rs @@ -3,9 +3,15 @@ use layer_shika_domain::prelude::{SurfaceConfig, UiSource}; use std::path::PathBuf; use std::rc::Rc; +/// Source for Slint UI definition +/// +/// Specifies where to load the UI from: a `.slint` file, inline source code, or pre-compiled result. pub enum CompiledUiSource { + /// Load UI from a `.slint` file path File(PathBuf), + /// Parse UI from source code string Source(String), + /// Use pre-compiled Slint result Compiled(Rc), } @@ -56,14 +62,21 @@ impl From for CompiledUiSource { } } +/// Declarative configuration for creating a shell with multiple surfaces +/// +/// Use this for programmatic or externally-driven configuration. +/// For fluent builder API, use `Shell::from_file()` instead. pub struct ShellConfig { pub ui_source: CompiledUiSource, pub surfaces: Vec, } +/// Associates a Slint component name with its surface configuration #[derive(Debug, Clone)] pub struct SurfaceComponentConfig { + /// Name of the Slint component to instantiate pub component: String, + /// Surface configuration for this component pub config: SurfaceConfig, } diff --git a/crates/composition/src/shell_runtime.rs b/crates/composition/src/shell_runtime.rs index fba8b0a..3d96a7d 100644 --- a/crates/composition/src/shell_runtime.rs +++ b/crates/composition/src/shell_runtime.rs @@ -1,7 +1,9 @@ use layer_shika_adapters::platform::slint_interpreter::ComponentInstance; +/// Default surface name used internally pub const DEFAULT_SURFACE_NAME: &str = "main"; +/// Trait providing runtime access to shell components and event loop pub trait ShellRuntime { type LoopHandle; type Context<'a>; diff --git a/crates/composition/src/system.rs b/crates/composition/src/system.rs index d0e2ab7..f8cfa90 100644 --- a/crates/composition/src/system.rs +++ b/crates/composition/src/system.rs @@ -79,6 +79,10 @@ pub enum ShellCommand { Render, } +/// Handle for runtime control of shell operations +/// +/// Provides methods to manipulate surfaces, show popups, and request redraws. +/// Obtained from callbacks via the control parameter. #[derive(Clone)] pub struct ShellControl { sender: channel::Sender, @@ -166,6 +170,10 @@ impl ShellControl { } } +/// Handle for runtime control of a specific surface +/// +/// Allows modifying surface properties like size, anchor, layer, and margins at runtime. +/// Obtained via `ShellControl::surface()`. pub struct SurfaceControlHandle { name: String, sender: channel::Sender, @@ -316,6 +324,10 @@ impl SurfaceControlHandle { } } +/// Builder for applying multiple configuration changes to a surface at once +/// +/// Created via `SurfaceControlHandle::configure()`. Chain configuration methods +/// and call `.apply()` to commit all changes atomically. pub struct RuntimeSurfaceConfigBuilder { handle: SurfaceControlHandle, config: SurfaceConfig, diff --git a/crates/domain/src/config.rs b/crates/domain/src/config.rs index 8ee39af..3536330 100644 --- a/crates/domain/src/config.rs +++ b/crates/domain/src/config.rs @@ -6,6 +6,10 @@ use crate::value_objects::layer::Layer; use crate::value_objects::margins::Margins; use crate::value_objects::output_policy::OutputPolicy; +/// Complete configuration for a layer-shell surface +/// +/// Contains all positioning, sizing, and behavioral properties for a surface. +/// Use with `ShellConfig` for declarative configuration or build via `ShellBuilder`. #[derive(Debug, Clone)] pub struct SurfaceConfig { pub dimensions: SurfaceDimension, diff --git a/crates/domain/src/dimensions.rs b/crates/domain/src/dimensions.rs index 4e2954f..569c5d4 100644 --- a/crates/domain/src/dimensions.rs +++ b/crates/domain/src/dimensions.rs @@ -1,5 +1,6 @@ use crate::errors::DomainError; +/// Size in logical pixels, independent of display scaling #[derive(Debug, Clone, Copy, PartialEq)] pub struct LogicalSize { width: f32, @@ -65,6 +66,7 @@ impl Default for LogicalSize { } } +/// Size in physical device pixels #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct PhysicalSize { width: u32, @@ -109,6 +111,7 @@ impl Default for PhysicalSize { } } +/// Display scaling factor for converting between logical and physical pixels #[derive(Debug, Clone, Copy, PartialEq)] pub struct ScaleFactor(f32); @@ -182,6 +185,7 @@ impl TryFrom for ScaleFactor { } } +/// Position in logical pixels, independent of display scaling #[derive(Debug, Clone, Copy, PartialEq)] pub struct LogicalPosition { x: f32, diff --git a/crates/domain/src/value_objects/anchor_strategy.rs b/crates/domain/src/value_objects/anchor_strategy.rs index f22cb8c..cd1b4b6 100644 --- a/crates/domain/src/value_objects/anchor_strategy.rs +++ b/crates/domain/src/value_objects/anchor_strategy.rs @@ -1,11 +1,19 @@ +/// Strategy for calculating popup position relative to an anchor rectangle #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum AnchorStrategy { + /// Center popup horizontally below the anchor CenterBottom, + /// Center popup horizontally above the anchor CenterTop, + /// Position popup at anchor's bottom-left LeftBottom, + /// Position popup at anchor's bottom-right RightBottom, + /// Position popup at anchor's top-left LeftTop, + /// Position popup at anchor's top-right RightTop, + /// Position popup at cursor coordinates Cursor, } diff --git a/crates/domain/src/value_objects/dimensions.rs b/crates/domain/src/value_objects/dimensions.rs index e3e732a..a6d41c2 100644 --- a/crates/domain/src/value_objects/dimensions.rs +++ b/crates/domain/src/value_objects/dimensions.rs @@ -1,3 +1,6 @@ +/// Width and height of a layer surface in pixels +/// +/// Use 0 for either dimension to let the surface stretch along that axis based on anchor edges. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct SurfaceDimension { width: u32, diff --git a/crates/domain/src/value_objects/handle.rs b/crates/domain/src/value_objects/handle.rs index ec06214..a14b90e 100644 --- a/crates/domain/src/value_objects/handle.rs +++ b/crates/domain/src/value_objects/handle.rs @@ -38,6 +38,10 @@ pub struct Popup; #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct Surface; +/// Type-safe unique identifier for runtime resources +/// +/// Used as `OutputHandle`, `PopupHandle`, or `SurfaceHandle` to identify +/// specific instances of those resources. pub struct Handle { id: HandleId, _marker: PhantomData, @@ -111,6 +115,9 @@ impl Handle { } } +/// Unique identifier for an output (monitor) pub type OutputHandle = Handle; +/// Unique identifier for a popup window pub type PopupHandle = Handle; +/// Unique identifier for a layer surface pub type SurfaceHandle = Handle; diff --git a/crates/domain/src/value_objects/keyboard_interactivity.rs b/crates/domain/src/value_objects/keyboard_interactivity.rs index 218c9d8..e8d867d 100644 --- a/crates/domain/src/value_objects/keyboard_interactivity.rs +++ b/crates/domain/src/value_objects/keyboard_interactivity.rs @@ -1,7 +1,11 @@ +/// Controls how a surface receives keyboard input #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum KeyboardInteractivity { + /// Surface does not receive keyboard events None, + /// Surface always receives keyboard focus Exclusive, + /// Surface receives focus when clicked (default) OnDemand, } diff --git a/crates/domain/src/value_objects/layer.rs b/crates/domain/src/value_objects/layer.rs index 69e9358..980bd00 100644 --- a/crates/domain/src/value_objects/layer.rs +++ b/crates/domain/src/value_objects/layer.rs @@ -1,8 +1,16 @@ +/// Vertical stacking layer for layer-shell surfaces +/// +/// Determines which layer a surface appears in, affecting visibility and stacking order. +/// Defaults to `Top` for typical panels and bars. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Layer { + /// Lowest layer, typically for wallpapers Background, + /// Below normal windows Bottom, + /// Above normal windows, default for bars/panels Top, + /// Highest layer, above all other content Overlay, } diff --git a/crates/domain/src/value_objects/margins.rs b/crates/domain/src/value_objects/margins.rs index 01fbdc6..dccf1fd 100644 --- a/crates/domain/src/value_objects/margins.rs +++ b/crates/domain/src/value_objects/margins.rs @@ -1,3 +1,4 @@ +/// Spacing margins around a surface in pixels #[derive(Debug, Clone, Copy, Default)] pub struct Margins { pub top: i32, diff --git a/crates/domain/src/value_objects/output_info.rs b/crates/domain/src/value_objects/output_info.rs index f0089a0..4612611 100644 --- a/crates/domain/src/value_objects/output_info.rs +++ b/crates/domain/src/value_objects/output_info.rs @@ -1,5 +1,6 @@ use crate::value_objects::output_handle::OutputHandle; +/// Runtime information about a connected output (monitor) #[derive(Debug, Clone, PartialEq)] pub struct OutputInfo { handle: OutputHandle, @@ -10,6 +11,7 @@ pub struct OutputInfo { is_primary: bool, } +/// Physical geometry and properties of an output #[derive(Debug, Clone, PartialEq, Eq)] pub struct OutputGeometry { pub x: i32, diff --git a/crates/domain/src/value_objects/output_policy.rs b/crates/domain/src/value_objects/output_policy.rs index 4fa1090..04f8205 100644 --- a/crates/domain/src/value_objects/output_policy.rs +++ b/crates/domain/src/value_objects/output_policy.rs @@ -4,10 +4,14 @@ use std::rc::Rc; type OutputFilter = Rc bool>; +/// Determines which outputs (monitors) should display the surface #[derive(Clone)] pub enum OutputPolicy { + /// Display surface on all connected outputs (default) AllOutputs, + /// Display surface only on the primary output PrimaryOnly, + /// Custom filter function to determine output eligibility Custom(OutputFilter), } diff --git a/crates/domain/src/value_objects/popup_positioning_mode.rs b/crates/domain/src/value_objects/popup_positioning_mode.rs index e34643c..da8de18 100644 --- a/crates/domain/src/value_objects/popup_positioning_mode.rs +++ b/crates/domain/src/value_objects/popup_positioning_mode.rs @@ -1,13 +1,25 @@ +/// Alignment mode for popup positioning +/// +/// Determines how a popup is aligned relative to its placement point. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum PopupPositioningMode { + /// Align popup's top-left corner to placement point TopLeft, + /// Center popup horizontally at placement point, top edge aligned TopCenter, + /// Align popup's top-right corner to placement point TopRight, + /// Center popup vertically at placement point, left edge aligned CenterLeft, + /// Center popup both horizontally and vertically at placement point Center, + /// Center popup vertically at placement point, right edge aligned CenterRight, + /// Align popup's bottom-left corner to placement point BottomLeft, + /// Center popup horizontally at placement point, bottom edge aligned BottomCenter, + /// Align popup's bottom-right corner to placement point BottomRight, } diff --git a/crates/domain/src/value_objects/popup_request.rs b/crates/domain/src/value_objects/popup_request.rs index 57a91d9..1868582 100644 --- a/crates/domain/src/value_objects/popup_request.rs +++ b/crates/domain/src/value_objects/popup_request.rs @@ -3,6 +3,9 @@ pub use super::handle::PopupHandle; use super::popup_positioning_mode::PopupPositioningMode; +/// Configuration for showing a popup window +/// +/// Use `PopupRequest::builder()` to construct with fluent API. #[derive(Debug, Clone)] pub struct PopupRequest { pub component: String, @@ -39,10 +42,14 @@ impl PopupRequest { } } +/// Where to position a popup relative to the surface #[derive(Debug, Clone, Copy)] pub enum PopupPlacement { + /// At absolute logical position AtPosition { x: f32, y: f32 }, + /// At current cursor position AtCursor, + /// Relative to a logical rectangle AtRect { x: f32, y: f32, w: f32, h: f32 }, } @@ -71,9 +78,12 @@ impl PopupPlacement { } } +/// How to size a popup window #[derive(Debug, Clone, Copy)] pub enum PopupSize { + /// Fixed width and height in logical pixels Fixed { w: f32, h: f32 }, + /// Size automatically based on content Content, } diff --git a/crates/domain/src/value_objects/ui_source.rs b/crates/domain/src/value_objects/ui_source.rs index cf16cd9..6838a74 100644 --- a/crates/domain/src/value_objects/ui_source.rs +++ b/crates/domain/src/value_objects/ui_source.rs @@ -1,8 +1,13 @@ use std::path::PathBuf; +/// Source for UI definition at domain level +/// +/// Lower-level alternative to `CompiledUiSource`. Typically used internally. #[derive(Debug, Clone)] pub enum UiSource { + /// Load from a file path File(PathBuf), + /// Parse from source code string Source(String), }