diff --git a/crates/mogwai/src/step.rs b/crates/mogwai/src/step.rs index edebb82..cae35a5 100644 --- a/crates/mogwai/src/step.rs +++ b/crates/mogwai/src/step.rs @@ -12,8 +12,8 @@ //! |------|----------|----------| //! | [`Step`] | `&self` | `step` only awaits event listeners (interior mutability). Lets a parent race multiple children concurrently. | //! | [`StepMut`] | `&mut self` | `step` mutates the widget's own fields or drives a mutable resource. Children cannot be raced concurrently. | -//! | [`StepWith`] | `&self` | A container of `T`-typed children that races a per-child future (supplied by a closure) against its own event. | -//! | [`StepWithMut`] | `&mut self` | Same, but with exclusive access to each child. | +//! | [`StepWith`] | `&self` | A container of `T`-typed children that races a per-child future (supplied by a closure) against its own event. Return type is a GAT `Output`. | +//! | [`StepWithMut`] | `&mut self` | Same, but with exclusive access to each child. Return type is a GAT `Output`. | //! //! ## Object safety //! @@ -97,6 +97,10 @@ pub trait StepMut { /// pattern: the container owns `N` children of type `T`, and the caller /// decides how each child produces a future of type `Ev`. /// +/// The return type is a generic associated type (GAT) `Output` so a +/// container can produce a different event type depending on the child event +/// `Ev` (e.g. an enum with `Tabs(Self::TabEvent)` and `Panes(Ev)` variants). +/// /// ## Example /// /// ```no_run @@ -113,11 +117,11 @@ pub trait StepMut { /// } /// /// impl StepWith for List { -/// type Output = (); +/// type Output = (); /// fn step_with( /// &self, /// f: impl for<'a> FnMut(&'a T) -> Pin + 'a>>, -/// ) -> impl Future +/// ) -> impl Future> /// where /// Ev: 'static, /// { @@ -129,8 +133,10 @@ pub trait StepMut { /// } /// ``` pub trait StepWith { - /// The event produced by the container's own step. - type Output: 'static; + /// The event produced by a single step, parameterized by the child event + /// `Ev`. This is a generic associated type so containers can return a + /// type that *contains* `Ev` (e.g. an enum with a `Panes(Ev)` variant). + type Output: 'static; /// Race the container's own event future against a future produced by /// `f` for each child. The first to resolve wins. @@ -142,7 +148,7 @@ pub trait StepWith { fn step_with( &self, f: impl for<'a> FnMut(&'a T) -> Pin + 'a>>, - ) -> impl Future + ) -> impl Future> where Ev: 'static; } @@ -154,6 +160,11 @@ pub trait StepWith { /// container owns `N` children of type `T` mutably, and the caller decides how /// each produces a future of type `Ev`. /// +/// The return type is a generic associated type (GAT) `Output` so a +/// container can produce a different event type depending on the child event +/// `Ev` (e.g. `TabPanelEvent` with `Tabs(...)` and `Panes(Ev)` +/// variants). +/// /// ## Example /// /// ```no_run @@ -167,11 +178,11 @@ pub trait StepWith { /// } /// /// impl StepWithMut

for TabPanel { -/// type Output = (); +/// type Output = (); /// fn step_with_mut( /// &mut self, /// f: impl for<'a> FnMut(&'a mut P) -> Pin + 'a>>, -/// ) -> impl Future +/// ) -> impl Future> /// where /// Ev: 'static, /// { @@ -183,8 +194,10 @@ pub trait StepWith { /// } /// ``` pub trait StepWithMut { - /// The event produced by the container's own step. - type Output: 'static; + /// The event produced by a single step, parameterized by the child event + /// `Ev`. This is a generic associated type so containers can return a + /// type that *contains* `Ev` (e.g. `TabPanelEvent`). + type Output: 'static; /// Race the container's own event future against a future produced by /// `f` for each child (with mutable access). The first to resolve wins. @@ -196,7 +209,7 @@ pub trait StepWithMut { fn step_with_mut( &mut self, f: impl for<'a> FnMut(&'a mut T) -> Pin + 'a>>, - ) -> impl Future + ) -> impl Future> where Ev: 'static; }