fixed doc comments

Author: xarvic

CHANGELOG.md

@@ -74,7 +74,7 @@ You can find its changes [documented below](#070---2021-01-01).
 - Added `compute_max_intrinsic` method to the `Widget` trait, which determines the maximum useful dimension of the widget ([#2172] by [@sjoshid])
 - Windows: Dark mode support for the title bar ([#2196] by [@dristic])
 - `ZStack` widget ([#2235] by [@xarvic])
-- `Lifecycle::ViewStateChanged`, `InternalLifecycle::RouteViewStateChanged`, `ChangeCtx`, and `RequestCtx` ([2149] by [@xarvic])
+- `Lifecycle::ViewStateChanged`, `InternalLifecycle::RouteViewStateChanged`, `ChangeCtx`, and `RequestCtx` ([#2149] by [@xarvic])
 
 ### Changed
 

druid/src/contexts.rs

@@ -161,8 +161,10 @@ pub struct State<'a, 'b> {
 
 /// Convenience trait for code generic over contexts.
 ///
-/// Methods to do with commands and timers.
-/// Available to all contexts but PaintCtx.
+/// Methods that deal with commands and timers.
+/// Available to all contexts but [`PaintCtx`].
+///
+/// [`PaintCtx`](PaintCtx)
 pub trait ChangeCtx<'b> {
     /// Submit a [`Command`] to be run after this event is handled. See [`submit_command`].
     ///
@@ -494,7 +496,7 @@ impl_context_method!(EventCtx<'_, '_>, UpdateCtx<'_, '_>, {
     /// preferences of a child widget. (If that isn't what you want, use [`set_cursor`] instead.)
     ///
     /// [`clear_cursor`]: EventCtx::clear_cursor
-    /// [`set_cursor`]: EventCtx::override_cursor
+    /// [`set_cursor`]: EventCtx::set_cursor
     /// [`hot`]: EventCtx::is_hot
     /// [`active`]: EventCtx::is_active
     pub fn override_cursor(&mut self, cursor: &Cursor) {
@@ -505,21 +507,28 @@ impl_context_method!(EventCtx<'_, '_>, UpdateCtx<'_, '_>, {
     /// Clear the cursor icon.
     ///
     /// This undoes the effect of [`set_cursor`] and [`override_cursor`].
-    ///
+    ///[`PaintCtx`]
     /// [`override_cursor`]: EventCtx::override_cursor
     /// [`set_cursor`]: EventCtx::set_cursor
+    /// [`override_cursor`]: EventCtx::override_cursor
     pub fn clear_cursor(&mut self) {
         trace!("clear_cursor");
         self.widget_state.cursor_change = CursorChange::Default;
     }
 });
 
-//methods on event, update and layout.
+// methods on event, update and layout.
 impl_context_method!(EventCtx<'_, '_>, UpdateCtx<'_, '_>, LayoutCtx<'_, '_>, {
-    /// Indicate that your view_context has changed.
+    /// Indicate that your [`ViewContext`] has changed.
+    ///
+    /// This event is sent after layout is done and before paint is called. Note that you can still
+    /// receive this event even if there was no prior call to layout.
+    ///
+    /// Widgets must call this method after changing the clip region of their children.
+    /// Changes to the other parts of [`ViewContext`] (cursor position and global origin) are tracked
+    /// internally.
     ///
-    /// Widgets must call this method after changing the clip region of thier children.
-    /// The other parts of view_context (cursor_position and global origin) are tracked internally.
+    /// [`ViewContext`](crate::ViewContext)
     pub fn view_context_changed(&mut self) {
         self.widget_state.view_context_changed = true;
     }

druid/src/core.rs

@@ -14,14 +14,13 @@
 
 //! The fundamental druid types.
 
-use druid::contexts::ChangeCtx;
 use std::collections::VecDeque;
 use tracing::{trace, trace_span, warn};
 
 use crate::bloom::Bloom;
 use crate::command::sys::{CLOSE_WINDOW, SUB_WINDOW_HOST_TO_PARENT, SUB_WINDOW_PARENT_TO_HOST};
 use crate::commands::SCROLL_TO_VIEW;
-use crate::contexts::ContextState;
+use crate::contexts::{ChangeCtx, ContextState};
 use crate::kurbo::{Affine, Insets, Point, Rect, Shape, Size};
 use crate::sub_window::SubWindowUpdate;
 use crate::{
@@ -82,6 +81,10 @@ pub struct WidgetState {
     /// `size` these constitute the child's layout rect.
     origin: Point,
     /// The origin of the parent in the window coordinate space;
+    //TODO: decide whether we should remove this. With this PR (https://github.com/linebender/druid/pull/2149)
+    // the position of a widget can change during event, but its global position only gets updated
+    // after layout while calling some_pod.layout_rect() gives you the correct local position every
+    // time.
     pub(crate) parent_window_origin: Point,
     /// A flag used to track and debug missing calls to set_origin.
     is_expecting_set_origin_call: bool,
@@ -125,7 +128,12 @@ pub struct WidgetState {
     /// Some of our children have the `view_context_changed` flag set.
     pub(crate) children_view_context_changed: bool,
 
+    /// indicate that the [`ViewContext`] changed.
     ///
+    /// When this flag is set, the associated widget will receive a LifeCycle::ViewContextChanged
+    /// event.
+    ///
+    /// [`ViewContext`](crate::ViewContext)
     pub(crate) view_context_changed: bool,
 
     /// Any descendant is active.
@@ -359,7 +367,7 @@ impl<T, W: Widget<T>> WidgetPod<T, W> {
     ///
     /// Returns `true` if the hot state changed.
     ///
-    /// The provided `child_state` should be merged up if this returns `true`.
+    /// The WidgetPod should merge up its state when `true` is returned.
     fn set_hot_state(
         &mut self,
         state: &mut ContextState,
@@ -1070,7 +1078,7 @@ impl<T: Data, W: Widget<T>> WidgetPod<T, W> {
                 ));
 
                 self.set_hot_state(ctx.state, view_context.last_mouse_position, data, env);
-                self.state.parent_window_origin = view_context.parent_window_origin;
+                self.state.parent_window_origin = view_context.window_origin;
 
                 self.state.children_view_context_changed = false;
                 self.state.view_context_changed = false;

druid/src/event.rs

@@ -14,11 +14,11 @@
 
 //! Events.
 
-use crate::kurbo::{Rect, Size};
 use std::ops::{Add, Sub};
 
 use druid_shell::{Clipboard, KeyEvent, TimerToken};
 
+use crate::kurbo::{Rect, Size};
 use crate::mouse::MouseEvent;
 use crate::{Command, Notification, Point, WidgetId};
 
@@ -304,7 +304,12 @@ pub enum LifeCycle {
     ///
     /// [`EventCtx::is_focused`]: struct.EventCtx.html#method.is_focused
     FocusChanged(bool),
+    /// Called when the [`ViewContext`] of this widget changed.
     ///
+    /// See [`view_context_changed`] on how and when to request this event.
+    ///
+    /// [`view_context_changed`](EventCtx::view_context_changed)
+    /// [`ViewContext`](ViewContext)
     ViewContextChanged(ViewContext),
     /// Internal druid lifecycle event.
     ///
@@ -334,7 +339,8 @@ pub enum InternalLifeCycle {
     },
     /// Used to route the `DisabledChanged` event to the required widgets.
     RouteDisabledChanged,
-    /// The parents widget origin in window coordinate space has changed.
+
+    /// Used to route the `ViewContextChanged` event to the required widgets.
     RouteViewContextChanged(ViewContext),
     /// For testing: request the `WidgetState` of a specific widget.
     ///
@@ -351,7 +357,7 @@ pub enum InternalLifeCycle {
     /// For testing: request the `DebugState` of a specific widget.
     ///
     /// This is useful if you need to get a best-effort description of the
-    /// state of this widget and its children. You can dispatch this event,
+    /// state of this widget and its children. You can dispatch this event,set_hot
     /// specifying the widget in question, and that widget will
     /// set its state in the provided `Cell`, if it exists.
     DebugRequestDebugState {
@@ -364,18 +370,25 @@ pub enum InternalLifeCycle {
     DebugInspectState(StateCheckFn),
 }
 
-/// Information about the widgets surroundings.
+/// Information about the widget's surroundings.
+///
+/// The global origin is also saved in the widget state.
+///
+/// When the ViewContext of widget changes it receives a `ViewContextChanged` event.
 #[derive(Debug, Copy, Clone)]
 pub struct ViewContext {
-    /// The origin of this widget's parent relative to the window.
-    pub parent_window_origin: Point,
+    /// The origin of this widget relative to the window.
+    ///
+    /// This is written from the perspective of the Widget and not the Pod.
+    /// For the Pod this is its parent's window origin.
+    pub window_origin: Point,
 
-    /// The last position the cursor was on, relative to the widget.
+    /// The last position the cursor was at, relative to the widget.
     pub last_mouse_position: Option<Point>,
 
     /// The visible area, this widget is contained in, relative to the widget.
     ///
-    /// The area may be larger than the widgets paint_rect.
+    /// The area may be larger than the widgets `paint_rect`.
     pub clip: Rect,
 }
 
@@ -444,7 +457,7 @@ impl LifeCycle {
 
     /// Returns an event for a widget which maybe is overlapped by another widget.
     ///
-    /// When ignore is set to `true` the widget will set its hot state to `false` even if the cursor
+    /// When `ignore` is set to `true` the widget will set its hot state to `false` even if the cursor
     /// is inside its bounds.
     pub fn ignore_hot(&self, ignore: bool) -> Self {
         if ignore {
@@ -490,11 +503,11 @@ impl InternalLifeCycle {
 }
 
 impl ViewContext {
-    /// Transforms the `ViewContext` into the coordinate_space of its child.
+    /// Transforms the `ViewContext` into the coordinate space of its child.
     pub(crate) fn for_child_widget(&self, child_origin: Point) -> Self {
         let child_origin = child_origin.to_vec2();
         ViewContext {
-            parent_window_origin: self.parent_window_origin.add(child_origin),
+            window_origin: self.window_origin.add(child_origin),
             last_mouse_position: self.last_mouse_position.map(|pos| pos.sub(child_origin)),
             clip: self.clip.sub(child_origin),
         }

druid/src/widget/clip_box.rs

@@ -87,10 +87,10 @@ impl Viewport {
         }
     }
 
-    /// Sets the component selected by axis of viewport origin to `pos`, while trying to keep the
+    /// Sets the component selected by `axis` of viewport origin to `pos`, while trying to keep the
     /// view rectangle inside the content rectangle.
     ///
-    /// Returns true if the position changed. Note that the valid values for the viewport origin
+    /// Returns `true` if the position changed. Note that the valid values for the viewport origin
     /// are constrained by the size of the child, and so the origin might not get set to exactly
     /// `pos`.
     pub fn pan_to_on_axis(&mut self, axis: Axis, pos: f64) -> bool {
@@ -374,7 +374,7 @@ impl<T, W: Widget<T>> ClipBox<T, W> {
         })
     }
 
-    /// Pans the minimal distance to show the target rect.
+    /// Pans the minimal distance to show the `region`.
     ///
     /// If the target region is larger than the viewport, we will display the
     /// portion that fits, prioritizing the portion closest to the origin.

druid/src/widget/scroll.rs

@@ -65,7 +65,7 @@ impl<T, W: Widget<T>> Scroll<T, W> {
         self.clip.pan_by(ctx, data, env, delta)
     }
 
-    /// Scroll the minimal distance to show the target rect.
+    /// Scroll the minimal distance to show the target `region`.
     ///
     /// If the target region is larger than the viewport, we will display the
     /// portion that fits, prioritizing the portion closest to the origin.

druid/src/window.rs

@@ -185,7 +185,7 @@ impl<T: Data> Window<T> {
         if self.root.state().children_view_context_changed && !self.root.state().needs_layout {
             let event =
                 LifeCycle::Internal(InternalLifeCycle::RouteViewContextChanged(ViewContext {
-                    parent_window_origin: Point::ORIGIN,
+                    window_origin: Point::ORIGIN,
                     last_mouse_position: self.last_mouse_pos,
                     clip: self.size.to_rect(),
                 }));