From 2367f7863a27fcfc00efeb07cd20f8bc16a2f951 Mon Sep 17 00:00:00 2001 From: dtoniolo Date: Fri, 23 Aug 2024 15:14:12 +0200 Subject: [PATCH] Document how the state of a `Component` can be managed --- widget/src/lazy/component.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/widget/src/lazy/component.rs b/widget/src/lazy/component.rs index 659bc476ce..2bdfa2c095 100644 --- a/widget/src/lazy/component.rs +++ b/widget/src/lazy/component.rs @@ -31,6 +31,19 @@ use std::rc::Rc; /// /// Additionally, a [`Component`] is capable of producing a `Message` to notify /// the parent application of any relevant interactions. +/// +/// # State +/// A component can store its state in one of two ways: either as data within the +/// implementor of the trait, or in a type [`State`][Component::State] that is managed +/// by the runtime and provided to the trait methods. These two approaches are not +/// mutually exclusive and have opposite pros and cons. +/// +/// For instance, if a piece of state is needed by multiple components that reside +/// in different branches of the tree, then it's more convenient to let a common +/// ancestor store it and pass it down. +/// +/// On the other hand, if a piece of state is only needed by the component itself, +/// you can store it as part of its internal [`State`][Component::State]. #[cfg(feature = "lazy")] #[deprecated( since = "0.13.0",