text

Documentation

Overview

Package text handles rich-formatted text layout and drawing.

A Setter lays out styalized text into a bounding box by repeatedly calling Add or AddStyle, and then calling Set. Set returns a Text which contains the text from all previous calls to Add or AddStyle.

A Text can be queried for the byte-index of points and it can be drawn to a window. Rasterization of the lines of text is done lazily. Once finished, Text.Release releases the rasterized lines back to its setter to be reused by the next call to Set.

A typical use

First create a setter, add bytes to the setter, set it into a Text, and draw the Text.

When the text changes, release the old Text, re-add the bytes to the setter, re-set it into a new Text, and draw the new Text.

The new Text re-uses pre-rendered lines from the old text. In the common case, where little changed, drawing the new Text is very efficient.

Index

• type Options
• type Setter
  • func NewSetter(opts Options) *Setter
  • func (s *Setter) Add(text []byte)
  • func (s *Setter) AddStyle(sty *Style, text []byte)
  • func (s *Setter) Release()
  • func (s *Setter) Reset(opts Options)
  • func (s *Setter) Set() *Text
• type Style
• type Text
  • func (t *Text) Draw(at image.Point, scr screen.Screen, win screen.Window)
  • func (t *Text) DrawLines(at image.Point, scr screen.Screen, win screen.Window) int
  • func (t *Text) GlyphBox(index int) image.Rectangle
  • func (t *Text) Index(p image.Point) int
  • func (t *Text) LinesHeight() int
  • func (t *Text) Release()
  • func (t *Text) Size() image.Point
• Bugs

Types

type Options

type Options struct {
	// Size is the size of the Text returned by Set.
	Size image.Point

	// DefaultStyle dictates
	// the default background color of text,
	// the minimum line height of lines of text,
	// and the units of tab width.
	DefaultStyle Style

	// TabWidth is the number of DefaultStyle space-widths
	// between tab stops.
	TabWidth int

	// Padding is the number of pixels
	// between the borders of Bounds
	// and the Text.
	Padding int
}

Options control text layout by a setter.

type Setter

type Setter struct {
	// contains filtered or unexported fields
}

A Setter lays out text to fit in a rectangle.

func NewSetter

func NewSetter(opts Options) *Setter

NewSetter returns a new Setter.

func (*Setter) Add

func (s *Setter) Add(text []byte)

Add adds text to the Setter using the default style.

func (*Setter) AddStyle

func (s *Setter) AddStyle(sty *Style, text []byte)

AddStyle adds text to the Setter using the given style.

func (*Setter) Release

func (s *Setter) Release()

Release releases the resources of the Setter.

The Setter may continue to be used after calling Release.

func (*Setter) Reset

func (s *Setter) Reset(opts Options)

Reset clears any added lines, and resets the setter with new Options.

func (*Setter) Set

func (s *Setter) Set() *Text

Set returns the Text containing the text from all calls to Add or AddStyle since the previous call to Set.

Where possible, the returned Text uses pre-rasterized lines that were released to the Setter by the previous call to Text.Release.

type Style

type Style struct {
	Face   font.Face
	FG, BG color.Color
}

A Style describes a font face and colors.

type Text

type Text struct {
	// contains filtered or unexported fields
}

A Text is a type-set text. BUG(eaburns): The text often reaches into the setter's opts. If the opts change, the Text will be broken.

func (*Text) Draw

func (t *Text) Draw(at image.Point, scr screen.Screen, win screen.Window)

Draw draws the Text to the Window. The entire size is filled even if the lines of text do not occupy the entire space.

func (*Text) DrawLines

func (t *Text) DrawLines(at image.Point, scr screen.Screen, win screen.Window) int

DrawLines draws the lines of text and padding. If the lines stop short of the maximum height, bottom padding is drawn, but the full height is not filled. However, the entire width of each line is filled even if the line does not use the full width.

The return value is the first y pixel after the bottom padding.

func (*Text) GlyphBox

func (t *Text) GlyphBox(index int) image.Rectangle

GlyphBox returns the bounding box of the glyph at the given byte index. The box is translated to the location of the glyph relative to the upper-left of the text at point 0,0. Vertically, the bounds are not tight-fitting, but instead fit the line height.

If the corresponding rectangle does not fit in the Text size, the zero Rectangle is returned.

func (*Text) Index

func (t *Text) Index(p image.Point) int

Index returns the byte index into the text corresponding to the glyph at the given point. The point 0,0 is the top left of the text.

This method is designed with text selection in mind. As such, points outside follow these rules: If the point is above the start of the text, 0 is returned. If the point is below the end of the text, the length of the text is returned. If the point is to the left of a line, the first rune in that line is returned. If the point is to the right of the last rune in a line, the last rune in the line is returned, unless it is \n, in which case the second to last rune in the line is returned.

func (*Text) LinesHeight

func (t *Text) LinesHeight() int

LinesHeight returns the height of the lines of text. This may differ from Size().Y, because the lines may not occupy the entire vertical space allowed by the text.

func (*Text) Release

func (t *Text) Release()

Release releases the rasterized lines of the Text back to the Setter that created it for reuse by the next call to Set.

The Text should no longer be used after it is released.

To release the resources back to the operating system, first release them to the Setter using this method, then call Setter.Release.

func (*Text) Size

func (t *Text) Size() image.Point

Size returns the size of the Text.

Notes

Bugs

• The text often reaches into the setter's opts. If the opts change, the Text will be broken.