Allowing mouse overrides to specify that an event was consumed. Resolves #972, resolves #967

application.go

@@ -42,6 +42,11 @@ const (
 	MouseScrollDown
 	MouseScrollLeft
 	MouseScrollRight
+
+	// The following special value will not be provided as a mouse action but
+	// indicate that an overridden mouse event was consumed. See
+	// [Box.SetMouseCapture] for details.
+	MouseConsumed
 )
 
 // queuedUpdate represented the execution of f queued by
@@ -167,7 +172,8 @@ func (a *Application) GetInputCapture() func(event *tcell.EventKey) *tcell.Event
 // the original tcell mouse event and the semantic mouse action) before they are
 // forwarded to the appropriate mouse event handler. This function can then
 // choose to forward that event (or a different one) by returning it or stop
-// the event processing by returning a nil mouse event.
+// the event processing by returning a nil mouse event. In such a case, the
+// event is considered consumed and the screen will be redrawn.
 func (a *Application) SetMouseCapture(capture func(event *tcell.EventMouse, action MouseAction) (*tcell.EventMouse, MouseAction)) *Application {
 	a.mouseCapture = capture
 	return a

box.go

@@ -222,7 +222,11 @@ func (b *Box) WrapMouseHandler(mouseHandler func(MouseAction, *tcell.EventMouse,
 		if b.mouseCapture != nil {
 			action, event = b.mouseCapture(action, event)
 		}
-		if event != nil && mouseHandler != nil {
+		if event == nil {
+			if action == MouseConsumed {
+				consumed = true
+			}
+		} else if mouseHandler != nil {
 			consumed, capture = mouseHandler(action, event, setFocus)
 		}
 		return
@@ -247,6 +251,10 @@ func (b *Box) MouseHandler() func(action MouseAction, event *tcell.EventMouse, s
 // returning a nil mouse event, in which case the default handler will not be
 // called.
 //
+// When a nil event is returned, the returned mouse action value may be set to
+// [MouseConsumed] to indicate that the event was consumed and the screen should
+// be redrawn. Any other value will not cause a redraw.
+//
 // Providing a nil handler will remove a previously existing handler.
 //
 // Note that mouse events are ignored completely if the application has not been