From 9d949777c70ccbbbb4879fd387570092d77a98f2 Mon Sep 17 00:00:00 2001 From: drendog Date: Sun, 18 Jan 2026 22:55:31 +0100 Subject: [PATCH] docs: add more examples on docs comments --- crates/composition/src/selection.rs | 19 ++++- crates/composition/src/selector.rs | 85 +++++++++++++++++++++- crates/composition/src/system.rs | 7 +- crates/composition/src/value_conversion.rs | 1 + 4 files changed, 104 insertions(+), 8 deletions(-) diff --git a/crates/composition/src/selection.rs b/crates/composition/src/selection.rs index 7fb7063..24fb88a 100644 --- a/crates/composition/src/selection.rs +++ b/crates/composition/src/selection.rs @@ -93,7 +93,12 @@ impl<'a> Selection<'a> { /// Registers a callback handler for all matching surfaces /// - /// Handler receives a `CallbackContext` with surface identity and shell control. + /// ```ignore + /// shell.select(Surface::named("bar")) + /// .on_callback("clicked", |ctx| { + /// println!("Clicked: {}", ctx.surface_name()); + /// }); + /// ``` pub fn on_callback(&self, callback_name: &str, handler: F) -> &Self where F: Fn(crate::CallbackContext) -> R + Clone + 'static, @@ -104,7 +109,17 @@ impl<'a> Selection<'a> { self } - /// Registers a callback handler that receives arguments for all matching surfaces + /// Registers a callback handler that receives Slint arguments + /// + /// ```ignore + /// // Slint: callback item-clicked(string); + /// shell.select(Surface::named("menu")) + /// .on_callback_with_args("item-clicked", |args, ctx| { + /// if let Some(Value::String(item)) = args.get(0) { + /// println!("{} clicked {}", ctx.surface_name(), item); + /// } + /// }); + /// ``` pub fn on_callback_with_args(&self, callback_name: &str, handler: F) -> &Self where F: Fn(&[Value], crate::CallbackContext) -> R + Clone + 'static, diff --git a/crates/composition/src/selector.rs b/crates/composition/src/selector.rs index 80ccc98..44909d2 100644 --- a/crates/composition/src/selector.rs +++ b/crates/composition/src/selector.rs @@ -14,9 +14,30 @@ pub struct SurfaceInfo { pub instance_id: SurfaceInstanceId, } -/// Selector for targeting surfaces when setting up callbacks or runtime configuration +/// Selector for targeting surfaces in callbacks and runtime configuration /// -/// Combine with `.or()`, `.except()`, or `.on()` for complex targeting. +/// # Examples +/// +/// ```ignore +/// // Single surface by name +/// shell.select(Surface::named("bar")) +/// .on_callback("clicked", |ctx| { /* ... */ }); +/// +/// // Multiple surfaces +/// shell.select(Surface::any(["bar", "panel"])) +/// .set_property("visible", &Value::Bool(true)); +/// +/// // All except one +/// shell.select(Surface::all().except(Surface::named("hidden"))) +/// .on_callback("update", |ctx| { /* ... */ }); +/// +/// // Custom filter +/// shell.select(Surface::matching(|info| info.name.starts_with("popup"))) +/// .set_property("layer", &Value::String("overlay".into())); +/// +/// // Combine with output selector +/// Surface::named("bar").on(Output::primary()) +/// ``` #[derive(Clone)] pub enum Surface { /// Select all surfaces @@ -50,6 +71,10 @@ impl Surface { } /// Selects surfaces matching a custom predicate + /// + /// ```ignore + /// Surface::matching(|info| info.name.starts_with("widget")) + /// ``` pub fn matching(predicate: F) -> Self where F: Fn(&SurfaceInfo) -> bool + Send + Sync + 'static, @@ -58,6 +83,11 @@ impl Surface { } /// Combines this surface selector with an output selector + /// + /// ```ignore + /// Surface::named("bar").on(Output::primary()) + /// Surface::all().on(Output::named("HDMI-1")) + /// ``` pub fn on(self, output: Output) -> Selector { Selector { surface: self, @@ -66,12 +96,20 @@ impl Surface { } /// Inverts the selection to exclude matching surfaces + /// + /// ```ignore + /// Surface::all().except(Surface::named("hidden")) + /// ``` #[must_use] pub fn except(self, other: impl Into) -> Self { Self::Not(Box::new(other.into())) } /// Combines this selector with another using OR logic + /// + /// ```ignore + /// Surface::named("bar").or(Surface::named("panel")) + /// ``` #[must_use] pub fn or(self, other: impl Into) -> Self { match self { @@ -108,7 +146,23 @@ impl Debug for Surface { } } -/// Selector for targeting outputs (monitors) in runtime operations +/// Selector for targeting outputs (monitors) +/// +/// # Examples +/// +/// ```ignore +/// // Primary monitor only +/// shell.select(Surface::named("bar").on(Output::primary())) +/// .on_callback("clicked", |ctx| { /* ... */ }); +/// +/// // Specific output by name +/// shell.select(Output::named("HDMI-1")) +/// .set_property("scale", &Value::Number(1.5)); +/// +/// // Custom filter +/// shell.select(Output::matching(|info| info.scale().unwrap_or(1) > 1)) +/// .set_property("enable-hidpi", &Value::Bool(true)); +/// ``` #[derive(Clone)] pub enum Output { /// Select all outputs @@ -156,6 +210,10 @@ impl Output { } /// Selects outputs matching a custom predicate + /// + /// ```ignore + /// Output::matching(|info| info.is_primary()) + /// ``` pub fn matching(predicate: F) -> Self where F: Fn(&OutputInfo) -> bool + Send + Sync + 'static, @@ -164,12 +222,20 @@ impl Output { } /// Inverts the selection to exclude matching outputs + /// + /// ```ignore + /// Output::all().except(Output::primary()) + /// ``` #[must_use] pub fn except(self, other: impl Into) -> Self { Self::Not(Box::new(other.into())) } /// Combines this selector with another using OR logic + /// + /// ```ignore + /// Output::named("HDMI-1").or(Output::named("HDMI-2")) + /// ``` #[must_use] pub fn or(self, other: impl Into) -> Self { match self { @@ -220,7 +286,18 @@ impl Debug for Output { /// Combined surface and output selector for precise targeting /// -/// Targets specific surface instances on specific outputs. +/// Created by combining `Surface` and `Output` selectors: +/// +/// ```ignore +/// Surface::named("bar").on(Output::primary()) +/// ``` +/// +/// Or implicitly from either selector: +/// +/// ```ignore +/// shell.select(Surface::named("bar")) // All outputs +/// shell.select(Output::primary()) // All surfaces +/// ``` #[derive(Clone, Debug)] pub struct Selector { pub surface: Surface, diff --git a/crates/composition/src/system.rs b/crates/composition/src/system.rs index 9a25642..ffe5d77 100644 --- a/crates/composition/src/system.rs +++ b/crates/composition/src/system.rs @@ -102,9 +102,12 @@ pub enum ShellCommand { Render, } -/// Context provided to callback handlers with surface and control information +/// Context provided to callback handlers /// -/// Provides surface identity, output info, and control handle for runtime operations. +/// # Callback Signatures +/// +/// - Basic: `Fn(CallbackContext) -> impl IntoValue` +/// - With args: `Fn(&[Value], CallbackContext) -> impl IntoValue` pub struct CallbackContext { instance_id: SurfaceInstanceId, surface_name: String, diff --git a/crates/composition/src/value_conversion.rs b/crates/composition/src/value_conversion.rs index f3212dd..ac6e41f 100644 --- a/crates/composition/src/value_conversion.rs +++ b/crates/composition/src/value_conversion.rs @@ -1,5 +1,6 @@ use layer_shika_adapters::platform::slint_interpreter::Value; +/// Trait for callback return types pub trait IntoValue { fn into_value(self) -> Value; }