masonry: document widget timer lifecycle

Clarify that `request_anim_frame` and `Widget::on_anim_frame` are for frame-cadenced visual updates, while delayed one-shot UI behavior should use widget timers.

Update the pass-system and widget-implementation docs to describe timer delivery through `Update::Timer`, the non-bubbling delivery model, and the usual `Option<TimerToken>` request/cancel pattern.

Author: waywardmonkeys

masonry/src/doc/implementing_widget.md

@@ -48,6 +48,7 @@ In the course of a frame, Masonry will run a series of passes over the widget tr
 - `on_pointer_event`, `on_text_event` and `on_access_event` are called once after a user-initiated event (like a mouse click or keyboard input).
 - `on_anim_frame` is called once per frame for animated widgets.
 - `update` is called many times during a frame, with various events reflecting changes in the widget's state (for instance, it gets or loses text focus).
+- `update` is also where timers requested by the widget are delivered as `Update::Timer`.
 - `measure` and `layout` are called during Masonry's layout pass.
   `measure` computes the preferred size of the widget on a single axis.
   `layout` receives a chosen size and lays out its children accordingly.
@@ -162,6 +163,12 @@ impl Widget for ColorRectangle {
 }
 ```
 
+Use `on_anim_frame` for visual state that should advance with frame cadence, such as continuous motion or interpolation.
+For delayed one-shot behavior, use a timer instead.
+For example, a widget can store an `Option<TimerToken>`, set it with `ctx.request_timer(delay)`, then compare it against `Update::Timer(token)` in `update`.
+If the delayed behavior should continue, request a new one-shot timer from that `Update::Timer` branch.
+Cancel the stored token with `ctx.cancel_timer(token)` when the state that made the timer relevant no longer applies.
+
 ### Layout
 
 Next we implement layout:
@@ -348,6 +355,11 @@ Most context types include these methods for requesting future passes:
 - `request_accessibility_update()`
 - `request_layout()`
 - `request_anim_frame()`
+- `request_timer()`
+- `cancel_timer()`
+
+Use `request_anim_frame()` for frame-cadenced animation.
+Use `request_timer()` for delayed one-shot UI behavior such as cursor blinking, tooltip delays, debounce, or long press recognition.
 
 
 ### Using context in `ColorRectangle`

masonry_core/src/core/contexts.rs

@@ -1644,6 +1644,11 @@ impl_context_method!(
         }
 
         /// Requests an animation frame.
+        ///
+        /// Use this for visual state that should advance with frame cadence,
+        /// such as continuous motion or interpolation. For delayed one-shot UI
+        /// behavior like cursor blinking, tooltip delays, debounce, or long
+        /// press recognition, prefer [`request_timer`](Self::request_timer).
         pub fn request_anim_frame(&mut self) {
             trace!("request_anim_frame");
             self.widget_state.request_anim = true;

masonry_core/src/core/widget.rs

@@ -195,6 +195,10 @@ pub trait Widget: AsDynWidget + Any {
     /// [`request_anim`](UpdateCtx::request_anim_frame) unless the animation
     /// has finished.
     ///
+    /// Use timers instead of animation frames for delayed one-shot UI behavior
+    /// such as cursor blinking, tooltip delays, debounce, or long press
+    /// recognition.
+    ///
     /// On the first frame when transitioning from idle to animating, `interval`
     /// will be 0. (This logic is presently per-window but might change to
     /// per-widget to make it more consistent). Otherwise it is in nanoseconds.

masonry_core/src/doc/pass_system.md

@@ -48,6 +48,16 @@ It runs in depth-first preorder on all animated widgets in the tree.
 
 The animation pass may be considered as a special event pass: it's not triggered by user interaction, and it doesn't bubble, but it's also triggered externally and sets off the rewrite passes.
 
+### Timer delivery
+
+Widget timers are delayed callbacks requested with context methods such as [`UpdateCtx::request_timer`].
+When a timer expires, Masonry delivers [`Update::Timer`] to the widget that requested it.
+
+Timer delivery does not bubble to ancestors.
+Like the animation pass, it is triggered externally by the host event loop and sets off the rewrite passes after delivery.
+Timers are best for delayed one-shot UI behavior such as cursor blinking, tooltip delays, debounce, and long press recognition.
+Use animation frames instead for visual state that should advance with frame cadence.
+
 
 ## Rewrite passes
 
@@ -255,6 +265,8 @@ They can access the layout of children if they have already been laid out.
 [`RegisterCtx`]: crate::core::RegisterCtx
 [`QueryCtx`]: crate::core::QueryCtx
 [`WidgetAdded`]: crate::core::Update::WidgetAdded
+[`Update::Timer`]: crate::core::Update::Timer
+[`UpdateCtx::request_timer`]: crate::core::UpdateCtx::request_timer
 [`Ime::Disabled`]: crate::core::Ime::Disabled
 [`FocusChanged`]: crate::core::Update::FocusChanged
 [`ChildFocusChanged`]: crate::core::Update::ChildFocusChanged