2bcac7dfbe80217b54ab834c693627765b887ea6 — Elias Naur 14 days 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() {}