From b052006922b2bc4eae3449ba4831730caae2d5f1 Mon Sep 17 00:00:00 2001
From: gravestench <dknuth0101@gmail.com>
Date: Mon, 2 Nov 2020 09:14:03 +0000
Subject: [PATCH] add comment explaining significance of input handler return
 value (#895)

---
 d2common/d2interface/input_handlers.go | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/d2common/d2interface/input_handlers.go b/d2common/d2interface/input_handlers.go
index 07a45ed1..8389f075 100644
--- a/d2common/d2interface/input_handlers.go
+++ b/d2common/d2interface/input_handlers.go
@@ -3,42 +3,47 @@ package d2interface
 // InputEventHandler is an event handler
 type InputEventHandler interface{}
 
+/*
+	NOTE: The return values of the handler methods below are used to prevent
+	other bound handlers from being called (if the handler returns `true`).
+*/
+
 // KeyDownHandler represents a handler for a keyboard key pressed event
 type KeyDownHandler interface {
-	OnKeyDown(event KeyEvent) bool
+	OnKeyDown(event KeyEvent) (preventPropagation bool)
 }
 
 // KeyRepeatHandler represents a handler for a keyboard key held-down event; between a pressed and released.
 type KeyRepeatHandler interface {
-	OnKeyRepeat(event KeyEvent) bool
+	OnKeyRepeat(event KeyEvent) (preventPropagation bool)
 }
 
 // KeyUpHandler represents a handler for a keyboard key release event
 type KeyUpHandler interface {
-	OnKeyUp(event KeyEvent) bool
+	OnKeyUp(event KeyEvent) (preventPropagation bool)
 }
 
 // KeyCharsHandler represents a handler associated with a keyboard character pressed event
 type KeyCharsHandler interface {
-	OnKeyChars(event KeyCharsEvent) bool
+	OnKeyChars(event KeyCharsEvent) (preventPropagation bool)
 }
 
 // MouseButtonDownHandler represents a handler for a mouse button pressed event
 type MouseButtonDownHandler interface {
-	OnMouseButtonDown(event MouseEvent) bool
+	OnMouseButtonDown(event MouseEvent) (preventPropagation bool)
 }
 
 // MouseButtonRepeatHandler represents a handler for a mouse button held-down event; between a pressed and released.
 type MouseButtonRepeatHandler interface {
-	OnMouseButtonRepeat(event MouseEvent) bool
+	OnMouseButtonRepeat(event MouseEvent) (preventPropagation bool)
 }
 
 // MouseButtonUpHandler represents a handler for a mouse button release event
 type MouseButtonUpHandler interface {
-	OnMouseButtonUp(event MouseEvent) bool
+	OnMouseButtonUp(event MouseEvent) (preventPropagation bool)
 }
 
 // MouseMoveHandler represents a handler for a mouse button release event
 type MouseMoveHandler interface {
-	OnMouseMove(event MouseMoveEvent) bool
+	OnMouseMove(event MouseMoveEvent) (preventPropagation bool)
 }