From 6bb5b2d79cd18133353ae5b50b5928a26b8e128f Mon Sep 17 00:00:00 2001
From: Sasha Koshka <supergriffin64@gmail.com>
Date: Fri, 3 Mar 2023 20:31:30 -0500
Subject: [PATCH] Created the stub for Propagator

Unlike the previous poorly-defined ContainerCore idea, this struct
has one sole responsibility and that is propagating events to
children. There may be another struct called like ChildManager or
something in the future that also abstracts away logic for
adoption, canvas cutting, disowning, layout, etc.
---
 elements/core/propagator.go | 100 ++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 elements/core/propagator.go

diff --git a/elements/core/propagator.go b/elements/core/propagator.go
new file mode 100644
index 0000000..84296eb
--- /dev/null
+++ b/elements/core/propagator.go
@@ -0,0 +1,100 @@
+package core
+
+import "git.tebibyte.media/sashakoshka/tomo/input"
+import "git.tebibyte.media/sashakoshka/tomo/theme"
+import "git.tebibyte.media/sashakoshka/tomo/config"
+import "git.tebibyte.media/sashakoshka/tomo/elements"
+
+// ChildIterator represents an object that can iterate over a list of children,
+// calling a specified iterator function for each one. When keepGoing is false,
+// the iterator stops the current loop and OverChildren returns.
+type ChildIterator interface {
+	OverChildren (func (child elements.Element) (keepGoing bool))
+}
+
+// Propagator is a struct that can be embedded into elements that contain one or
+// more children in order to propagate events to them without having to write
+// all of the event handlers. It also implements standard behavior for focus
+// propagation and keyboard navigation.
+type Propagator struct {
+	iterator ChildIterator
+	drags    [10]elements.MouseTarget
+}
+
+// NewPropagator creates a new event propagator that uses the specified iterator
+// to access a list of child elements that will have events propagated to them.
+func NewPropagator (iterator ChildIterator) (propagator *Propagator) {
+	propagator = &Propagator {
+		iterator: iterator,
+	}
+	return
+}
+
+// Focused returns whether or not this element or any of its children
+// are currently focused.
+func (propagator *Propagator) Focused () (focused bool)
+
+// Focus focuses this element, if its parent element grants the
+// request.
+func (propagator *Propagator) Focus ()
+
+// HandleFocus causes this element to mark itself as focused. If the
+// element does not have children, it is disabled, or there are no more
+// selectable children in the given direction, it should return false
+// and do nothing. Otherwise, it should select itself and any children
+// (if applicable) and return true.
+func (propagator *Propagator) HandleFocus (direction input.KeynavDirection) (accepted bool)
+
+// HandleDeselection causes this element to mark itself and all of its
+// children as unfocused.
+func (propagator *Propagator) HandleUnfocus ()
+
+// OnFocusRequest sets a function to be called when this element wants
+// its parent element to focus it. Parent elements should return true if
+// the request was granted, and false if it was not. If the parent
+// element returns true, the element must act as if a HandleFocus call
+// was made with KeynavDirectionNeutral.
+func (propagator *Propagator) OnFocusRequest (func () (granted bool))
+
+// OnFocusMotionRequest sets a function to be called when this
+// element wants its parent element to focus the element behind or in
+// front of it, depending on the specified direction. Parent elements
+// should return true if the request was granted, and false if it was
+// not.
+func (propagator *Propagator) OnFocusMotionRequest (func (direction input.KeynavDirection) (granted bool))
+
+// HandleKeyDown is called when a key is pressed down or repeated while
+// this element has keyboard focus. It is important to note that not
+// every key down event is guaranteed to be paired with exactly one key
+// up event. This is the reason a list of modifier keys held down at the
+// time of the key press is given.
+func (propagator *Propagator) HandleKeyDown (key input.Key, modifiers input.Modifiers)
+
+// HandleKeyUp is called when a key is released while this element has
+// keyboard focus.
+func (propagator *Propagator) HandleKeyUp (key input.Key, modifiers input.Modifiers)
+
+// HandleMouseDown is called when a mouse button is pressed down on this
+// element.
+func (propagator *Propagator) HandleMouseDown (x, y int, button input.Button)
+
+// HandleMouseUp is called when a mouse button is released that was
+// originally pressed down on this element.
+func (propagator *Propagator) HandleMouseUp (x, y int, button input.Button)
+
+// HandleMouseMove is called when the mouse is moved over this element,
+// or the mouse is moving while being held down and originally pressed
+// down on this element.
+func (propagator *Propagator) HandleMouseMove (x, y int)
+
+// HandleScroll is called when the mouse is scrolled. The X and Y
+// direction of the scroll event are passed as deltaX and deltaY.
+func (propagator *Propagator) HandleMouseScroll (x, y int, deltaX, deltaY float64)
+
+// SetTheme sets the element's theme to something fulfilling the
+// theme.Theme interface.
+func (propagator *Propagator) SetTheme (theme.Theme)
+
+// SetConfig sets the element's configuration to something fulfilling
+// the config.Config interface.
+func (propagator *Propagator) SetConfig (config.Config)