From d032299fc584b64bbb07daef1d17f14ff154125b Mon Sep 17 00:00:00 2001
From: Jonathan Johnson <jon@khonsulabs.com>
Date: Fri, 25 Oct 2024 10:00:57 -0700
Subject: [PATCH] Document mouse event handling more thoroughly

Refs #198
---
 src/dialog.rs |  3 +--
 src/widget.rs | 42 +++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 42 insertions(+), 3 deletions(-)

diff --git a/src/dialog.rs b/src/dialog.rs
index 9ab6370..0ddda77 100644
--- a/src/dialog.rs
+++ b/src/dialog.rs
@@ -277,8 +277,7 @@ impl MessageBox {
 
     /// Opens this dialog in the given target.
     ///
-    /// A target can be a [`Modal`] layer, a
-    /// [`ModalHandle`](crate::widgets::layers::ModalHandle), a
+    /// A target can be a [`Modal`] layer, a [`ModalHandle`], a
     /// [`WindowHandle`](crate::window::WindowHandle), or an
     /// [`App`](crate::App).
     pub fn open(&self, open_in: &impl OpenMessageBox) {
diff --git a/src/widget.rs b/src/widget.rs
index 9eeed47..809456f 100644
--- a/src/widget.rs
+++ b/src/widget.rs
@@ -319,18 +319,37 @@ pub trait Widget: Send + Debug + 'static {
     fn unmounted(&mut self, context: &mut EventContext<'_>) {}
 
     /// Returns true if this widget should respond to mouse input at `location`.
+    ///
+    /// This function is critical for how event propagation works for these
+    /// functions:
+    ///
+    /// - [`Self::hover`]
+    /// - [`Self::unhover`]
+    /// - [`Self::mouse_down`]
+    /// - [`Self::mouse_up`]
+    /// - [`Self::mouse_drag`]
+    /// - [`Self::mouse_wheel`]
+    ///
+    /// See [Hover State: Hit Testing](Self#hover-state-hit-testing) for an
+    /// explanation of how these events work together.
     #[allow(unused_variables)]
     fn hit_test(&mut self, location: Point<Px>, context: &mut EventContext<'_>) -> bool {
         false
     }
 
     /// The widget is currently has a cursor hovering it at `location`.
+    ///
+    /// This function will not be invoked if [`Self::hit_test`] returns false.
+    /// See [Hover State: Hit Testing](Self#hover-state-hit-testing) for more
+    /// information on how hover state is handled in Cushy.
     #[allow(unused_variables)]
     fn hover(&mut self, location: Point<Px>, context: &mut EventContext<'_>) -> Option<CursorIcon> {
         None
     }
 
     /// The widget is no longer being hovered.
+    ///
+    /// This function will only be invoked after [`Self::hover`].
     #[allow(unused_variables)]
     fn unhover(&mut self, context: &mut EventContext<'_>) {}
 
@@ -381,7 +400,14 @@ pub trait Widget: Send + Debug + 'static {
     /// event has been handled or not.
     ///
     /// If an event is handled, the widget will receive callbacks for
-    /// [`mouse_drag`](Self::mouse_drag) and [`mouse_up`](Self::mouse_up).
+    /// [`mouse_drag`](Self::mouse_drag) and [`mouse_up`](Self::mouse_up). See
+    /// [Mouse Button Events](Self#mouse-button-events) for more information on
+    /// how mouse events work in Cushy.
+    ///
+    /// This function will only be invoked if it or a child is the currently
+    /// hovered widget. See [Hover State: Hit
+    /// Testing](Self#hover-state-hit-testing) for more information on how hover
+    /// state is handled in Cushy.
     #[allow(unused_variables)]
     fn mouse_down(
         &mut self,
@@ -395,6 +421,10 @@ pub trait Widget: Send + Debug + 'static {
 
     /// A mouse button is being held down as the cursor is moved across the
     /// widget.
+    ///
+    /// This function will only be invoked if [`Self::mouse_down`] returns
+    /// [`HANDLED`]. See [Mouse Button Events](Self#mouse-button-events) for
+    /// more information on how mouse events work in Cushy.
     #[allow(unused_variables)]
     fn mouse_drag(
         &mut self,
@@ -406,6 +436,10 @@ pub trait Widget: Send + Debug + 'static {
     }
 
     /// A mouse button is no longer being pressed.
+    ///
+    /// This function will only be invoked if [`Self::mouse_down`] returns
+    /// [`HANDLED`]. See [Mouse Button Events](Self#mouse-button-events) for
+    /// more information on how mouse events work in Cushy.
     #[allow(unused_variables)]
     fn mouse_up(
         &mut self,
@@ -438,6 +472,12 @@ pub trait Widget: Send + Debug + 'static {
 
     /// A mouse wheel event has been sent to this widget. Returns whether the
     /// event has been handled or not.
+    ///
+    /// This function will only be invoked if it or a child is the currently
+    /// hovered widget. See [Hover State: Hit
+    /// Testing](Self#hover-state-hit-testing) for more information on how hover
+    /// state is handled in Cushy.
+    #[allow(unused_variables)]
     #[allow(unused_variables)]
     fn mouse_wheel(
         &mut self,