diff --git a/selector/src/find.rs b/selector/src/find.rs index eb3f0fa0..37ffd713 100644 --- a/selector/src/find.rs +++ b/selector/src/find.rs @@ -8,7 +8,12 @@ use crate::target::Candidate; use std::any::Any; +/// An [`Operation`] that runs the [`Selector`] and stops after +/// the first [`Output`](Selector::Output) is produced. pub type Find = Finder>; + +/// An [`Operation`] that runs the [`Selector`] for the entire +/// widget tree and aggregates all of its [`Output`](Selector::Output). pub type FindAll = Finder>; #[derive(Debug)] diff --git a/selector/src/lib.rs b/selector/src/lib.rs index 4e56172b..5005dd66 100644 --- a/selector/src/lib.rs +++ b/selector/src/lib.rs @@ -1,4 +1,4 @@ -#![allow(missing_docs)] +//! Select data from the widget tree. use iced_core as core; mod find; @@ -10,13 +10,29 @@ pub use target::{Bounded, Candidate, Target, Text}; use crate::core::Point; use crate::core::widget; +/// A type that traverses the widget tree to "select" data and produce some output. pub trait Selector { + /// The output type of the [`Selector`]. + /// + /// For most selectors, this will normally be a [`Target`]. However, some + /// may selectors may want to return a more limited type to encode the selection + /// guarantees in the type system. + /// + /// For instance, the implementations of [`String`] and [`str`] of [`Selector`] + /// return a [`target::Text`] instead of a generic [`Target`], since they are + /// guaranteed to only select text. type Output; + /// Performs a selection of the given [`Candidate`], if applicable. + /// + /// This method traverses the widget tree in depth-first order. fn select(&mut self, candidate: Candidate<'_>) -> Option; + /// Returns a short description of the [`Selector`] for debugging purposes. fn description(&self) -> String; + /// Returns a [`widget::Operation`] that runs the [`Selector`] and stops after + /// the first [`Output`](Self::Output) is produced. fn find(self) -> Find where Self: Sized, @@ -24,6 +40,8 @@ pub trait Selector { Find::new(find::One::new(self)) } + /// Returns a [`widget::Operation`] that runs the [`Selector`] for the entire + /// widget tree and aggregates all of its [`Output`](Self::Output). fn find_all(self) -> FindAll where Self: Sized, diff --git a/selector/src/target.rs b/selector/src/target.rs index cd0c4bba..d2d20651 100644 --- a/selector/src/target.rs +++ b/selector/src/target.rs @@ -4,6 +4,8 @@ use crate::core::{Rectangle, Vector}; use std::any::Any; +/// A generic widget match produced during selection. +#[allow(missing_docs)] #[derive(Debug, Clone, PartialEq)] pub enum Target { Container { @@ -43,6 +45,7 @@ pub enum Target { } impl Target { + /// Returns the layout bounds of the [`Target`]. pub fn bounds(&self) -> Rectangle { match self { Target::Container { bounds, .. } @@ -54,6 +57,7 @@ impl Target { } } + /// Returns the visible bounds of the [`Target`], in screen coordinates. pub fn visible_bounds(&self) -> Option { match self { Target::Container { visible_bounds, .. } @@ -148,6 +152,10 @@ impl Bounded for Target { } } +/// A selection candidate. +/// +/// This is provided to [`Selector::select`](crate::Selector::select). +#[allow(missing_docs)] #[derive(Clone)] pub enum Candidate<'a> { Container { @@ -190,6 +198,7 @@ pub enum Candidate<'a> { } impl<'a> Candidate<'a> { + /// Returns the widget [`Id`] of the [`Candidate`]. pub fn id(&self) -> Option<&'a Id> { match self { Candidate::Container { id, .. } @@ -201,6 +210,7 @@ impl<'a> Candidate<'a> { } } + /// Returns the layout bounds of the [`Candidate`]. pub fn bounds(&self) -> Rectangle { match self { Candidate::Container { bounds, .. } @@ -212,6 +222,7 @@ impl<'a> Candidate<'a> { } } + /// Returns the visible bounds of the [`Candidate`], in screen coordinates. pub fn visible_bounds(&self) -> Option { match self { Candidate::Container { visible_bounds, .. } @@ -224,12 +235,20 @@ impl<'a> Candidate<'a> { } } +/// A bounded type has both layout bounds and visible bounds. +/// +/// This trait lets us write generic code over the [`Output`](crate::Selector::Output) +/// of a [`Selector`](crate::Selector). pub trait Bounded: std::fmt::Debug { + /// Returns the layout bounds. fn bounds(&self) -> Rectangle; + /// Returns the visible bounds, in screen coordinates. fn visible_bounds(&self) -> Option; } +/// A text match. +#[allow(missing_docs)] #[derive(Debug, Clone, PartialEq)] pub enum Text { Raw { @@ -245,12 +264,14 @@ pub enum Text { } impl Text { + /// Returns the layout bounds of the [`Text`]. pub fn bounds(&self) -> Rectangle { match self { Text::Raw { bounds, .. } | Text::Input { bounds, .. } => *bounds, } } + /// Returns the visible bounds of the [`Text`], in screen coordinates. pub fn visible_bounds(&self) -> Option { match self { Text::Raw { visible_bounds, .. }