Merge branch 'text-widget/1/widget-options' into text-widget/2/write-…

…options

README.md

@@ -72,3 +72,7 @@ development](doc/widget_development.md) section.
 Run the [gaugedemo](widgets/gauge/demo/gaugedemo.go).
 
 [<img src="./images/gaugedemo.gif" alt="gaugedemo" type="image/png" width="100%">](widgets/gauge/demo/gaugedemo.go)
+
+## Disclaimer
+
+This is not an official Google product.

cell/color.go

@@ -40,6 +40,7 @@ var colorNames = map[Color]string{
 	ColorWhite:   "ColorWhite",
 }
 
+// The supported terminal colors.
 const (
 	ColorDefault Color = iota
 	ColorBlack

container/container.go

@@ -105,9 +105,8 @@ func (c *Container) hasWidget() bool {
 func (c *Container) usable() image.Rectangle {
 	if c.hasBorder() {
 		return area.ExcludeBorder(c.area)
-	} else {
-		return c.area
 	}
+	return c.area
 }
 
 // widgetArea returns the area in the container that is available for the
@@ -142,11 +141,11 @@ func (c *Container) widgetArea() (image.Rectangle, error) {
 // split splits the container's usable area into child areas.
 // Panics if the container isn't configured for a split.
 func (c *Container) split() (image.Rectangle, image.Rectangle) {
-	if ar := c.usable(); c.opts.split == splitTypeVertical {
+	ar := c.usable()
+	if c.opts.split == splitTypeVertical {
 		return area.VSplit(ar)
-	} else {
-		return area.HSplit(ar)
 	}
+	return area.HSplit(ar)
 }
 
 // createFirst creates and returns the first sub container of this container.

container/draw.go

@@ -133,8 +133,7 @@ func drawResize(c *Container, area image.Rectangle) error {
 		return err
 	}
 
-	_, err = draw.Text(cvs, "⇄", image.Point{0, 0})
-	if err != nil {
+	if err := draw.Text(cvs, "⇄", image.Point{0, 0}); err != nil {
 		return err
 	}
 	return cvs.Apply(c.term)

doc/widget_development.md

@@ -56,7 +56,7 @@ A typical unit test creates the expected fake terminal, executes the widget to
 get the actual fake terminal and compares the two:
 
 ```go
-TestWidget(t *testing.T) {
+func TestWidget(t *testing.T) {
   tests := []struct {
     desc    string
     canvas  image.Rectangle

draw/border.go

@@ -124,13 +124,12 @@ func drawTitle(c *canvas.Canvas, border image.Rectangle, opt *borderOptions) err
 		return err
 	}
 
-	_, err = Text(
+	return Text(
 		c, opt.title, start,
 		TextCellOpts(opt.titleCellOpts...),
 		TextOverrunMode(opt.titleOM),
 		TextMaxX(available.Max.X),
 	)
-	return err
 }
 
 // Border draws a border on the canvas.

draw/line_style.go

@@ -56,6 +56,7 @@ var lineStyleNames = map[LineStyle]string{
 	LineStyleLight: "LineStyleLight",
 }
 
+// Supported line styles.
 const (
 	LineStyleNone LineStyle = iota
 	LineStyleLight

draw/testdraw/testdraw.go

@@ -31,13 +31,10 @@ func MustBorder(c *canvas.Canvas, border image.Rectangle, opts ...draw.BorderOpt
 }
 
 // MustText draws the text on the canvas or panics.
-// Returns the number of written cells.
-func MustText(c *canvas.Canvas, text string, start image.Point, opts ...draw.TextOption) int {
-	cells, err := draw.Text(c, text, start, opts...)
-	if err != nil {
+func MustText(c *canvas.Canvas, text string, start image.Point, opts ...draw.TextOption) {
+	if err := draw.Text(c, text, start, opts...); err != nil {
 		panic(fmt.Sprintf("draw.Text => unexpected error: %v", err))
 	}
-	return cells
 }
 
 // MustRectangle draws the rectangle on the canvas or panics.

draw/text.go

@@ -125,11 +125,10 @@ func bounds(text string, maxRunes int, om OverrunMode) (string, error) {
 }
 
 // Text prints the provided text on the canvas starting at the provided point.
-// Returns the number of cells written.
-func Text(c *canvas.Canvas, text string, start image.Point, opts ...TextOption) (int, error) {
+func Text(c *canvas.Canvas, text string, start image.Point, opts ...TextOption) error {
 	ar := c.Area()
 	if !start.In(ar) {
-		return -1, fmt.Errorf("the requested start point %v falls outside of the provided canvas %v", start, ar)
+		return fmt.Errorf("the requested start point %v falls outside of the provided canvas %v", start, ar)
 	}
 
 	opt := &textOptions{}
@@ -138,7 +137,7 @@ func Text(c *canvas.Canvas, text string, start image.Point, opts ...TextOption)
 	}
 
 	if opt.maxX < 0 || opt.maxX > ar.Max.X {
-		return -1, fmt.Errorf("invalid TextMaxX(%v), must be a positive number that is <= canvas.width %v", opt.maxX, ar.Dx())
+		return fmt.Errorf("invalid TextMaxX(%v), must be a positive number that is <= canvas.width %v", opt.maxX, ar.Dx())
 	}
 
 	var wantMaxX int
@@ -151,15 +150,15 @@ func Text(c *canvas.Canvas, text string, start image.Point, opts ...TextOption)
 	maxRunes := wantMaxX - start.X
 	trimmed, err := bounds(text, maxRunes, opt.overrunMode)
 	if err != nil {
-		return -1, err
+		return err
 	}
 
 	cur := start
 	for _, r := range trimmed {
 		if err := c.SetCell(cur, r, opt.cellOpts...); err != nil {
-			return -1, err
+			return err
 		}
 		cur = image.Point{cur.X + 1, cur.Y}
 	}
-	return cur.X - start.X, nil
+	return nil
 }

draw/text_test.go

@@ -26,14 +26,13 @@ import (
 
 func TestText(t *testing.T) {
 	tests := []struct {
-		desc      string
-		canvas    image.Rectangle
-		text      string
-		start     image.Point
-		opts      []TextOption
-		want      func(size image.Point) *faketerm.Terminal
-		wantCells int
-		wantErr   bool
+		desc    string
+		canvas  image.Rectangle
+		text    string
+		start   image.Point
+		opts    []TextOption
+		want    func(size image.Point) *faketerm.Terminal
+		wantErr bool
 	}{
 		{
 			desc:   "start falls outside of the canvas",
@@ -65,7 +64,6 @@ func TestText(t *testing.T) {
 			want: func(size image.Point) *faketerm.Terminal {
 				return faketerm.MustNew(size)
 			},
-			wantCells: 0,
 		},
 		{
 			desc:   "text falls outside of the canvas on OverrunModeStrict",
@@ -93,7 +91,6 @@ func TestText(t *testing.T) {
 				testcanvas.MustApply(c, ft)
 				return ft
 			},
-			wantCells: 1,
 		},
 		{
 			desc:   "OverrunModeTrim trims longer text",
@@ -112,7 +109,6 @@ func TestText(t *testing.T) {
 				testcanvas.MustApply(c, ft)
 				return ft
 			},
-			wantCells: 2,
 		},
 		{
 			desc:   "text falls outside of the canvas on OverrunModeThreeDot",
@@ -130,7 +126,6 @@ func TestText(t *testing.T) {
 				testcanvas.MustApply(c, ft)
 				return ft
 			},
-			wantCells: 1,
 		},
 		{
 			desc:   "OverrunModeThreeDot trims longer text",
@@ -149,7 +144,6 @@ func TestText(t *testing.T) {
 				testcanvas.MustApply(c, ft)
 				return ft
 			},
-			wantCells: 2,
 		},
 		{
 			desc:   "requested MaxX is negative",
@@ -190,6 +184,15 @@ func TestText(t *testing.T) {
 			},
 			wantErr: true,
 		},
+		{
+			desc:   "text is empty, nothing to do",
+			canvas: image.Rect(0, 0, 1, 1),
+			text:   "",
+			start:  image.Point{0, 0},
+			want: func(size image.Point) *faketerm.Terminal {
+				return faketerm.MustNew(size)
+			},
+		},
 		{
 			desc:   "draws text",
 			canvas: image.Rect(0, 0, 3, 2),
@@ -204,7 +207,6 @@ func TestText(t *testing.T) {
 				testcanvas.MustApply(c, ft)
 				return ft
 			},
-			wantCells: 2,
 		},
 		{
 			desc:   "draws text with cell options",
@@ -223,7 +225,6 @@ func TestText(t *testing.T) {
 				testcanvas.MustApply(c, ft)
 				return ft
 			},
-			wantCells: 2,
 		},
 		{
 			desc:   "draws unicode character",
@@ -238,7 +239,6 @@ func TestText(t *testing.T) {
 				testcanvas.MustApply(c, ft)
 				return ft
 			},
-			wantCells: 1,
 		},
 		{
 			desc:   "draws multiple unicode characters",
@@ -255,7 +255,6 @@ func TestText(t *testing.T) {
 				testcanvas.MustApply(c, ft)
 				return ft
 			},
-			wantCells: 3,
 		},
 	}
 
@@ -266,7 +265,7 @@ func TestText(t *testing.T) {
 				t.Fatalf("canvas.New => unexpected error: %v", err)
 			}
 
-			gotCells, err := Text(c, tc.text, tc.start, tc.opts...)
+			err = Text(c, tc.text, tc.start, tc.opts...)
 			if (err != nil) != tc.wantErr {
 				t.Errorf("Text => unexpected error: %v, wantErr: %v", err, tc.wantErr)
 			}
@@ -286,10 +285,6 @@ func TestText(t *testing.T) {
 			if diff := faketerm.Diff(tc.want(c.Size()), got); diff != "" {
 				t.Errorf("Text => %v", diff)
 			}
-
-			if gotCells != tc.wantCells {
-				t.Errorf("Text => unexpected number of cells, got %d, want %d", gotCells, tc.wantCells)
-			}
 		})
 	}
 }

eventqueue/eventqueue.go

@@ -80,7 +80,7 @@ func (u *Unbound) empty() bool {
 	return u.first == nil
 }
 
-// Put puts an event onto the queue.
+// Push pushes an event onto the queue.
 func (u *Unbound) Push(e terminalapi.Event) {
 	u.mu.Lock()
 	defer u.mu.Unlock()
@@ -98,7 +98,7 @@ func (u *Unbound) Push(e terminalapi.Event) {
 	u.cond.Signal()
 }
 
-// Get gets an event from the queue. Returns nil if the queue is empty.
+// Pop pops an event from the queue. Returns nil if the queue is empty.
 func (u *Unbound) Pop() terminalapi.Event {
 	u.mu.Lock()
 	defer u.mu.Unlock()

mouse/mouse.go

@@ -36,6 +36,7 @@ var buttonNames = map[Button]string{
 	ButtonWheelDown: "ButtonWheelDown",
 }
 
+// Buttons recognized on the mouse.
 const (
 	buttonUnknown Button = iota
 	ButtonLeft

terminal/faketerm/faketerm.go

@@ -132,7 +132,7 @@ func (t *Terminal) String() string {
 	return b.String()
 }
 
-// Implements terminalapi.Terminal.Size.
+// Size implements terminalapi.Terminal.Size.
 func (t *Terminal) Size() image.Point {
 	t.mu.Lock()
 	defer t.mu.Unlock()
@@ -146,7 +146,7 @@ func (t *Terminal) Area() image.Rectangle {
 	return image.Rect(0, 0, s.X, s.Y)
 }
 
-// Implements terminalapi.Terminal.Clear.
+// Clear implements terminalapi.Terminal.Clear.
 func (t *Terminal) Clear(opts ...cell.Option) error {
 	t.mu.Lock()
 	defer t.mu.Unlock()
@@ -159,22 +159,22 @@ func (t *Terminal) Clear(opts ...cell.Option) error {
 	return nil
 }
 
-// Implements terminalapi.Terminal.Flush.
+// Flush implements terminalapi.Terminal.Flush.
 func (t *Terminal) Flush() error {
 	return nil // nowhere to flush to.
 }
 
-// Implements terminalapi.Terminal.SetCursor.
+// SetCursor implements terminalapi.Terminal.SetCursor.
 func (t *Terminal) SetCursor(p image.Point) {
 	log.Fatal("unimplemented")
 }
 
-// Implements terminalapi.Terminal.HideCursor.
+// HideCursor implements terminalapi.Terminal.HideCursor.
 func (t *Terminal) HideCursor() {
 	log.Fatal("unimplemented")
 }
 
-// Implements terminalapi.Terminal.SetCell.
+// SetCell implements terminalapi.Terminal.SetCell.
 func (t *Terminal) SetCell(p image.Point, r rune, opts ...cell.Option) error {
 	t.mu.Lock()
 	defer t.mu.Unlock()
@@ -193,7 +193,7 @@ func (t *Terminal) SetCell(p image.Point, r rune, opts ...cell.Option) error {
 	return nil
 }
 
-// Implements terminalapi.Terminal.Event.
+// Event implements terminalapi.Terminal.Event.
 func (t *Terminal) Event(ctx context.Context) terminalapi.Event {
 	if t.events == nil {
 		return terminalapi.NewErrorf("no event queue provided, use the WithEventQueue option when creating the fake terminal")
@@ -210,5 +210,5 @@ func (t *Terminal) Event(ctx context.Context) terminalapi.Event {
 	return ev
 }
 
-// Closes the terminal. This is a no-op on the fake terminal.
+// Close closes the terminal. This is a no-op on the fake terminal.
 func (t *Terminal) Close() {}