Tidied up documentation on Propagator

elements/core/propagator.go

@@ -23,7 +23,9 @@ type Propagator struct {
 
 // 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.
+// If iterator is nil, the function will return nil.
 func NewPropagator (iterator ChildIterator) (propagator *Propagator) {
+	if iterator == nil { return nil }
 	propagator = &Propagator {
 		iterator: iterator,
 	}
@@ -32,69 +34,88 @@ func NewPropagator (iterator ChildIterator) (propagator *Propagator) {
 
 // Focused returns whether or not this element or any of its children
 // are currently focused.
-func (propagator *Propagator) Focused () (focused bool)
+func (propagator *Propagator) Focused () (focused bool) {
+	
+}
 
 // Focus focuses this element, if its parent element grants the
 // request.
-func (propagator *Propagator) Focus ()
+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
+// element does not have children or there are no more focusable children in
-// selectable children in the given direction, it should return false
+// the given direction, it should return false and do nothing. Otherwise, it
-// and do nothing. Otherwise, it should select itself and any children
+// marks itself as focused along with any applicable children and returns
-// (if applicable) and return true.
+// true.
-func (propagator *Propagator) HandleFocus (direction input.KeynavDirection) (accepted bool)
+func (propagator *Propagator) HandleFocus (direction input.KeynavDirection) (accepted bool) {
+	
+}
 
-// HandleDeselection causes this element to mark itself and all of its
+// HandleDeselection causes this element to mark itself and all of its children
-// children as unfocused.
+// as unfocused.
-func (propagator *Propagator) HandleUnfocus ()
+func (propagator *Propagator) HandleUnfocus () {
+	
+}
 
-// OnFocusRequest sets a function to be called when this element wants
+// OnFocusRequest sets a function to be called when this element wants its
-// its parent element to focus it. Parent elements should return true if
+// parent element to focus it. Parent elements should return true if the request
-// the request was granted, and false if it was not. If the parent
+// was granted, and false if it was not. If the parent element returns true, the
-// element returns true, the element must act as if a HandleFocus call
+// element acts as if a HandleFocus call was made with KeynavDirectionNeutral.
-// was made with KeynavDirectionNeutral.
+func (propagator *Propagator) OnFocusRequest (func () (granted bool)) {
-func (propagator *Propagator) OnFocusRequest (func () (granted bool))
+	
+}
 
-// OnFocusMotionRequest sets a function to be called when this
+// OnFocusMotionRequest sets a function to be called when this element wants its
-// element wants its parent element to focus the element behind or in
+// parent element to focus the element behind or in front of it, depending on
-// front of it, depending on the specified direction. Parent elements
+// the specified direction. Parent elements should return true if the request
-// should return true if the request was granted, and false if it was
+// was granted, and false if it was not.
-// not.
+func (propagator *Propagator) OnFocusMotionRequest (func (direction input.KeynavDirection) (granted bool)) {
-func (propagator *Propagator) OnFocusMotionRequest (func (direction input.KeynavDirection) (granted bool))
+	
+}
 
-// HandleKeyDown is called when a key is pressed down or repeated while
+// HandleKeyDown propogates the keyboard event to the currently selected child.
-// this element has keyboard focus. It is important to note that not
+func (propagator *Propagator) HandleKeyDown (key input.Key, modifiers input.Modifiers) {
-// 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
+// HandleKeyUp propogates the keyboard event to the currently selected child.
-// keyboard focus.
+func (propagator *Propagator) HandleKeyUp (key input.Key, modifiers input.Modifiers) {
-func (propagator *Propagator) HandleKeyUp (key input.Key, modifiers input.Modifiers)
+	
+}
 
-// HandleMouseDown is called when a mouse button is pressed down on this
+// HandleMouseDown propagates the mouse event to the element under the mouse
-// element.
+// pointer.
-func (propagator *Propagator) HandleMouseDown (x, y int, button input.Button)
+func (propagator *Propagator) HandleMouseDown (x, y int, button input.Button) {
+	
+}
 
-// HandleMouseUp is called when a mouse button is released that was
+// HandleMouseUp propagates the mouse event to the element that the released
-// originally pressed down on this element.
+// mouse button was originally pressed on.
-func (propagator *Propagator) HandleMouseUp (x, y int, button input.Button)
+func (propagator *Propagator) HandleMouseUp (x, y int, button input.Button) {
+	
+}
 
-// HandleMouseMove is called when the mouse is moved over this element,
+// HandleMouseMove propagates the mouse event to the element that was last
-// or the mouse is moving while being held down and originally pressed
+// pressed down by the mouse if the mouse is currently being held down, else it
-// down on this element.
+// propagates the event to whichever element is underneath the mouse pointer.
-func (propagator *Propagator) HandleMouseMove (x, y int)
+func (propagator *Propagator) HandleMouseMove (x, y int) {
+	
+}
 
-// HandleScroll is called when the mouse is scrolled. The X and Y
+// HandleScroll propagates the mouse event to the element under the mouse
-// direction of the scroll event are passed as deltaX and deltaY.
+// pointer.
-func (propagator *Propagator) HandleMouseScroll (x, y int, deltaX, deltaY float64)
+func (propagator *Propagator) HandleMouseScroll (x, y int, deltaX, deltaY float64) {
+	
+}
 
-// SetTheme sets the element's theme to something fulfilling the
+// SetTheme sets the theme of all children to the specified theme.
-// theme.Theme interface.
+func (propagator *Propagator) SetTheme (theme.Theme) {
-func (propagator *Propagator) SetTheme (theme.Theme)
+	
+}
 
-// SetConfig sets the element's configuration to something fulfilling
+// SetConfig sets the theme of all children to the specified config.
-// the config.Config interface.
+func (propagator *Propagator) SetConfig (config.Config) {
-func (propagator *Propagator) SetConfig (config.Config)
+	
+}