From a22293bda94443b8e287d94957beab835e45187b Mon Sep 17 00:00:00 2001
From: Oliver <480930+rivo@users.noreply.github.com>
Date: Wed, 3 Apr 2024 16:26:47 +0200
Subject: [PATCH] Clarifications on mouse handling, resolves #667

---
 box.go | 8 ++++++--
 doc.go | 7 +++++++
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/box.go b/box.go
index 59f8ac7..1b6ed5d 100644
--- a/box.go
+++ b/box.go
@@ -248,6 +248,10 @@ func (b *Box) MouseHandler() func(action MouseAction, event *tcell.EventMouse, s
 // called.
 //
 // Providing a nil handler will remove a previously existing handler.
+//
+// Note that mouse events are ignored completely if the application has not been
+// enabled for mouse events (see [Application.EnableMouse]), which is the
+// default.
 func (b *Box) SetMouseCapture(capture func(action MouseAction, event *tcell.EventMouse) (MouseAction, *tcell.EventMouse)) *Box {
 	b.mouseCapture = capture
 	return b
@@ -260,8 +264,8 @@ func (b *Box) InRect(x, y int) bool {
 	return x >= rectX && x < rectX+width && y >= rectY && y < rectY+height
 }
 
-// InInnerRect returns true if the given coordinate is within the bounds of the box's
-// inner rectangle (within the border, and padding).
+// InInnerRect returns true if the given coordinate is within the bounds of the
+// box's inner rectangle (within the border and padding).
 func (b *Box) InInnerRect(x, y int) bool {
 	rectX, rectY, width, height := b.GetInnerRect()
 	return x >= rectX && x < rectX+width && y >= rectY && y < rectY+height
diff --git a/doc.go b/doc.go
index 185a1ff..bfefa03 100644
--- a/doc.go
+++ b/doc.go
@@ -158,6 +158,13 @@ switch to a light (or other) theme.
 
 This package supports all unicode characters supported by your terminal.
 
+# Mouse Support
+
+If your terminal supports mouse events, you can enable mouse support for your
+application by calling [Application.EnableMouse]. Note that this may interfere
+with your terminal's default mouse behavior. Mouse support is disabled by
+default.
+
 # Concurrency
 
 Many functions in this package are not thread-safe. For many applications, this