2bcac7dfbe80217b54ab834c693627765b887ea6 — Elias Naur 3 months ago 842d293
ui/text: document Editor

Signed-off-by: Elias Naur <mail@eliasnaur.com>
1 files changed, 37 insertions(+), 19 deletions(-)

M ui/text/editor.go
M ui/text/editor.go => ui/text/editor.go +37 -19
@@ 20,14 20,24 @@
 	"golang.org/x/image/math/fixed"
 )
 
+// Editor implements an editable and scrollable text area.
 type Editor struct {
-	Face       Face
-	Alignment  Alignment
+	Face      Face
+	Alignment Alignment
+	// SingleLine force the text to stay on a single line.
+	// SingleLine also sets the scrolling direction to
+	// horizontal.
 	SingleLine bool
-	Submit     bool
-
-	Material     ui.MacroOp
-	Hint         string
+	// Submit enabled translation of carriage return keys to SubmitEvents.
+	// If not enabled, carriage returns are inserted as newlines in the text.
+	Submit bool
+
+	// Material for drawing the text.
+	Material ui.MacroOp
+	// Hint contains the text displayed to the user when the
+	// Editor is empty.
+	Hint string
+	// Mmaterial is used to draw the hint.
 	HintMaterial ui.MacroOp
 
 	oldScale          int


@@ 59,7 69,11 @@
 	isEditorEvent()
 }
 
+// A ChangeEvent is generated for every user change to the text.
 type ChangeEvent struct{}
+
+// A SubmitEvent is generated when and Editor's Submit is set
+// and a carriage return key is pressed.
 type SubmitEvent struct{}
 
 const (


@@ 67,9 81,7 @@
 	maxBlinkDuration = 10 * time.Second
 )
 
-func (s ChangeEvent) isEditorEvent() {}
-func (s SubmitEvent) isEditorEvent() {}
-
+// Next returns the next available editor event, or false if none are available.
 func (e *Editor) Next(cfg ui.Config, queue input.Queue) (EditorEvent, bool) {
 	// Crude configuration change detection.
 	if scale := cfg.Px(ui.Sp(100)); scale != e.oldScale {


@@ 148,6 160,7 @@
 	return fixed.Int26_6(oneDp * 64)
 }
 
+// Focus requests the input focus for the Editor.
 func (e *Editor) Focus() {
 	e.requestFocus = true
 }


@@ 260,6 273,18 @@
 	return layout.Dimens{Size: e.viewSize, Baseline: baseline}
 }
 
+// Text returns the contents of the editor.
+func (e *Editor) Text() string {
+	return e.rr.String()
+}
+
+// SetText replaces the contents of the editor.
+func (e *Editor) SetText(s string) {
+	e.rr = editBuffer{}
+	e.carXOff = 0
+	e.prepend(s)
+}
+
 func (e *Editor) layout() {
 	e.adjustScroll()
 	if e.valid {


@@ 397,16 422,6 @@
 	e.invalidate()
 }
 
-func (e *Editor) Text() string {
-	return e.rr.String()
-}
-
-func (e *Editor) SetText(s string) {
-	e.rr = editBuffer{}
-	e.carXOff = 0
-	e.prepend(s)
-}
-
 func (e *Editor) append(s string) {
 	if e.SingleLine && s == "\n" {
 		return


@@ 590,3 605,6 @@
 	}
 	return true
 }
+
+func (s ChangeEvent) isEditorEvent() {}
+func (s SubmitEvent) isEditorEvent() {}