From 25e396809b0adc73eac6b04dc14b1b1da65bc4ae Mon Sep 17 00:00:00 2001 From: Dominic Clifton Date: Tue, 17 Dec 2024 12:02:20 +0100 Subject: [PATCH 1/3] Pile - Improve documentation. Add `must_use` attribute on `Pile::push`. --- src/widgets/pile.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/widgets/pile.rs b/src/widgets/pile.rs index df5ba3f6d..8e5c5f3dd 100644 --- a/src/widgets/pile.rs +++ b/src/widgets/pile.rs @@ -49,6 +49,8 @@ impl PileData { impl Pile { /// Returns a placeholder that can be used to show/close a piled widget /// before it has been constructed. + /// + /// See [`PiledWidget`] for important lifetime information. #[must_use] pub fn new_pending(&self) -> PendingPiledWidget { let mut pile = self.data.lock(); @@ -67,6 +69,9 @@ impl Pile { /// When the last clone of the returned [`PiledWidget`] is dropped, `widget` /// will be removed from the pile. If it is the currently visible widget, /// the next widget in the pile will be made visible. + /// + /// See [`PiledWidget`] for important lifetime information. + #[must_use] pub fn push(&self, widget: impl MakeWidget) -> PiledWidget { self.new_pending().finish(widget) } @@ -164,6 +169,8 @@ pub struct PendingPiledWidget(Option); impl PendingPiledWidget { /// Place `widget` in the pile and returns a handle to the placed widget. + /// + /// See [`PiledWidget`] for important lifetime information. #[allow(clippy::must_use_candidate)] pub fn finish(mut self, widget: impl MakeWidget) -> PiledWidget { let piled = self.0.take().assert("finished called once"); @@ -185,6 +192,12 @@ impl std::ops::Deref for PendingPiledWidget { } /// A widget that has been added to a [`Pile`]. +/// +/// If this is dropped, the widget will be removed from the Pile. +/// +/// This can happen in application which creates a 'bottom layer' for the pile +/// which is only supposed to be used by the pile itself. If you don't want the 'bottom layer' to +/// be removed immediately after creation you need to retain a reference to it. #[derive(Clone, Debug)] pub struct PiledWidget(Arc); @@ -218,6 +231,7 @@ struct PiledWidgetData { impl Drop for PiledWidgetData { fn drop(&mut self) { + println!("drop called"); let mut pile = self.pile.data.lock(); pile.hide_id(self.id); pile.widgets.remove(self.id); From 172bbc93f9b24a25f043cd971d10a826c6825841 Mon Sep 17 00:00:00 2001 From: Dominic Clifton Date: Tue, 17 Dec 2024 12:14:42 +0100 Subject: [PATCH 2/3] Macros - Improve documentation for `cushy::main`. --- cushy-macros/src/lib.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/cushy-macros/src/lib.rs b/cushy-macros/src/lib.rs index 713f3532c..7c2d98cec 100644 --- a/cushy-macros/src/lib.rs +++ b/cushy-macros/src/lib.rs @@ -28,5 +28,12 @@ mod cushy_main; #[manyhow(proc_macro_derive(LinearInterpolate))] pub use animation::linear_interpolate; +/// This macro extracts the body of `main` and uses it as the closure for the `on_startup` for the +/// [`cushy::PendingApp`]. +/// +/// Lifetimes: +/// +/// Due to how this macro works variables in the closure will be dropped at the end of the +/// method body, and *NOT* when the application terminates. #[manyhow(proc_macro_attribute)] pub use cushy_main::main; From 0e03ff978aefd9d58481229fb1cbfd31349e8aa8 Mon Sep 17 00:00:00 2001 From: Jonathan Johnson Date: Sun, 5 Jan 2025 13:26:38 -0800 Subject: [PATCH 3/3] Tweaked PiledWidget changes --- cushy-macros/src/lib.rs | 7 ------- src/lib.rs | 3 ++- src/widgets/pile.rs | 19 ++++++++++--------- 3 files changed, 12 insertions(+), 17 deletions(-) diff --git a/cushy-macros/src/lib.rs b/cushy-macros/src/lib.rs index 7c2d98cec..713f3532c 100644 --- a/cushy-macros/src/lib.rs +++ b/cushy-macros/src/lib.rs @@ -28,12 +28,5 @@ mod cushy_main; #[manyhow(proc_macro_derive(LinearInterpolate))] pub use animation::linear_interpolate; -/// This macro extracts the body of `main` and uses it as the closure for the `on_startup` for the -/// [`cushy::PendingApp`]. -/// -/// Lifetimes: -/// -/// Due to how this macro works variables in the closure will be dropped at the end of the -/// method body, and *NOT* when the application terminates. #[manyhow(proc_macro_attribute)] pub use cushy_main::main; diff --git a/src/lib.rs b/src/lib.rs index 00e339d61..edf094f00 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -44,7 +44,8 @@ pub use app::{ /// macro can be used to remove a few lines of code. /// /// The function body is executed during application startup, and the app will -/// continue running until the last window is closed. +/// continue running until the last window is closed. **Local variables in the +/// function will be dropped before the application runs.** /// /// This attribute must be attached to a `main(&mut PendingApp)` or `main(&mut /// App)` function. Either form supports a return type or no return type. diff --git a/src/widgets/pile.rs b/src/widgets/pile.rs index 8e5c5f3dd..a6dcc9699 100644 --- a/src/widgets/pile.rs +++ b/src/widgets/pile.rs @@ -49,9 +49,6 @@ impl PileData { impl Pile { /// Returns a placeholder that can be used to show/close a piled widget /// before it has been constructed. - /// - /// See [`PiledWidget`] for important lifetime information. - #[must_use] pub fn new_pending(&self) -> PendingPiledWidget { let mut pile = self.data.lock(); let id = pile.widgets.push(None); @@ -165,13 +162,16 @@ impl Widget for WidgetPile { } /// A placeholder for a widget in a [`Pile`]. +#[must_use] pub struct PendingPiledWidget(Option); impl PendingPiledWidget { /// Place `widget` in the pile and returns a handle to the placed widget. /// - /// See [`PiledWidget`] for important lifetime information. - #[allow(clippy::must_use_candidate)] + /// When the last clone of the returned [`PiledWidget`] is dropped, `widget` + /// will be removed from the pile. If it is the currently visible widget, + /// the next widget in the pile will be made visible. + #[must_use] pub fn finish(mut self, widget: impl MakeWidget) -> PiledWidget { let piled = self.0.take().assert("finished called once"); let mut pile = piled.0.pile.data.lock(); @@ -193,11 +193,13 @@ impl std::ops::Deref for PendingPiledWidget { /// A widget that has been added to a [`Pile`]. /// -/// If this is dropped, the widget will be removed from the Pile. +/// When the last clone of a `PiledWidget` is dropped, the widget will be +/// removed from the Pile. /// /// This can happen in application which creates a 'bottom layer' for the pile -/// which is only supposed to be used by the pile itself. If you don't want the 'bottom layer' to -/// be removed immediately after creation you need to retain a reference to it. +/// which is only supposed to be used by the pile itself. If you don't want the +/// 'bottom layer' to be removed immediately after creation you need to retain a +/// reference to it. #[derive(Clone, Debug)] pub struct PiledWidget(Arc); @@ -231,7 +233,6 @@ struct PiledWidgetData { impl Drop for PiledWidgetData { fn drop(&mut self) { - println!("drop called"); let mut pile = self.pile.data.lock(); pile.hide_id(self.id); pile.widgets.remove(self.id);