docs

Author: willmcgugan

docs/guide/input.md

@@ -232,6 +232,9 @@ Textual will send a [MouseCapture](../events/mouse_capture.md) event when the mo
 
 Textual will send a [Enter](../events/enter.md) event to a widget when the mouse cursor first moves over it, and a [Leave](../events/leave.md) event when the cursor moves off a widget.
 
+Both `Enter` and `Leave` _bubble_, so a widget may receive these events from a child widget.
+You can check the initial widget these events were send to by comparing the `node` attribute against `self` in the message handler.
+
 ### Click events
 
 There are three events associated with clicking a button on your mouse. When the button is initially pressed, Textual sends a [MouseDown](../events/mouse_down.md) event, followed by [MouseUp](../events/mouse_up.md) when the button is released. Textual then sends a final [Click](../events/click.md) event.

src/textual/widget.py

@@ -544,7 +544,13 @@ def is_anchored(self) -> bool:
 
     @property
     def is_mouse_over(self) -> bool:
-        """Is the mouse currently over this widget?"""
+        """Is the mouse currently over this widget?
+
+        Note this will be `True` if the mouse pointer is within the widget's region, even if
+        the mouse pointer is not directly over the widget (there could be another widget between
+        the mouse pointer and self).
+
+        """
         if not self.screen.is_active:
             return False
         for widget, _ in self.screen.get_widgets_at(*self.app.mouse_position):