From c8114d846754eba74c5189d8f6297095ae997457 Mon Sep 17 00:00:00 2001 From: faiface Date: Tue, 9 May 2017 16:27:55 +0200 Subject: [PATCH] add Text doc --- text/text.go | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/text/text.go b/text/text.go index 48eed6a..de7d317 100644 --- a/text/text.go +++ b/text/text.go @@ -37,9 +37,40 @@ func RangeTable(table *unicode.RangeTable) []rune { return runes } +// Text allows text drawing. +// +// To create a Text object, use the New constructor: +// txt := text.New(face, text.ASCII) +// +// As suggested by the constructor, a Text object is always associated with one font face and a +// fixed set of runes. For example, the Text we create above can draw text using the font face +// contained in the `face` variable and is capable of drawing ASCII characters. +// +// Here we create a Text object which can draw ASCII and Katakana characters: +// txt := text.New(face, text.ASCII, text.RangeTable(unicode.Katakana)) +// +// Similarly to IMDraw, Text functions as a buffer. It implements io.Writer interface, so writing +// text to it is really simple: +// fmt.Print(txt, "Hello, world!") +// +// Finally, if we want the written text to show up on some other Target, we can draw it: +// txt.Draw(target) +// +// Text exports two important fields: Orig and Dot. Dot is the position where the next character +// will be written. Dot is automatically moved when writing to a Text object, but you can also +// manipulate it manually. Orig specifies the text origin, usually the top-left dot position. Dot is +// always aligned to Orig when writing newlines. +// +// To reset the Dot to the Orig, just assign it: +// txt.Dot = txt.Orig type Text struct { + // Orig specifies the text origin, usually the top-left dot position. Dot is always aligned + // to Orig when writing newlines. Orig pixel.Vec - Dot pixel.Vec + + // Dot is the position where the next character will be written. Dot is automatically moved + // when writing to a Text object, but you can also manipulate it manually + Dot pixel.Vec atlas *Atlas @@ -59,6 +90,21 @@ type Text struct { dirty bool } +// New creates a new Text capable of drawing runes contained in the provided rune sets, plus +// unicode.ReplacementChar using the provided font.Face. +// +// Do not destroy or close the font.Face after creating a Text. Although Text caches most of the +// stuff (pre-drawn glyphs, etc.), it still uses the face for a few things. +// +// Here we create a Text capable of drawing ASCII characters using the Go Regular font. +// ttf, err := truetype.Parse(goregular.TTF) +// if err != nil { +// panic(err) +// } +// face := truetype.NewFace(ttf, &truetype.Options{ +// Size: 14, +// }) +// txt := text.New(face, text.ASCII) func New(face font.Face, runeSets ...[]rune) *Text { runes := []rune{unicode.ReplacementChar} for _, set := range runeSets { @@ -89,10 +135,13 @@ func New(face font.Face, runeSets ...[]rune) *Text { return txt } +// Atlas returns the underlying Text's Atlas containing all of the pre-drawn glyphs. The Atlas is +// also useful for getting values such as the recommended line height. func (txt *Text) Atlas() *Atlas { return txt.atlas } +// SetMatrix sets a Matrix by which the text will be transformed before drawing to another Target. func (txt *Text) SetMatrix(m pixel.Matrix) { if txt.mat != m { txt.mat = m @@ -100,6 +149,7 @@ func (txt *Text) SetMatrix(m pixel.Matrix) { } } +// SetColorMask sets a color by which the text will be masked before drawingto another Target. func (txt *Text) SetColorMask(c color.Color) { rgba := pixel.ToRGBA(c) if txt.col != rgba { @@ -108,10 +158,14 @@ func (txt *Text) SetColorMask(c color.Color) { } } +// Bounds returns the bounding box of the text currently written to the Text excluding whitespace. +// +// If the Text is empty, a zero rectangle is returned. func (txt *Text) Bounds() pixel.Rect { return txt.bounds } +// BoundsOf returns the bounding box of s if it was to be written to the Text right now. func (txt *Text) BoundsOf(s string) pixel.Rect { dot := txt.Dot prevR := txt.prevR @@ -139,6 +193,7 @@ func (txt *Text) BoundsOf(s string) pixel.Rect { return bounds } +// Color sets the text color. This does not affect any previously written text. func (txt *Text) Color(c color.Color) { rgba := pixel.ToRGBA(c) for i := range txt.glyph { @@ -146,14 +201,18 @@ func (txt *Text) Color(c color.Color) { } } +// LineHeight sets the vertical distance between two lines of text. This does not affect any +// previously written text. func (txt *Text) LineHeight(height float64) { txt.lineHeight = height } +// TabWidth sets the horizontal tab width. Tab characters will align to the multiples of this width. func (txt *Text) TabWidth(width float64) { txt.tabWidth = width } +// Clear removes all written text from the Text. func (txt *Text) Clear() { txt.prevR = -1 txt.bounds = pixel.Rect{} @@ -161,24 +220,30 @@ func (txt *Text) Clear() { txt.dirty = true } +// Write writes a slice of bytes to the Text. This method never fails, always returns len(p), nil. func (txt *Text) Write(p []byte) (n int, err error) { txt.buf = append(txt.buf, p...) txt.drawBuf() return len(p), nil } +// WriteString writes a string to the Text. This method never fails, always returns len(s), nil. func (txt *Text) WriteString(s string) (n int, err error) { txt.buf = append(txt.buf, s...) txt.drawBuf() return len(s), nil } +// WriteByte writes a byte to the Text. This method never fails, always returns nil. +// +// Writing a multi-byte rune byte-by-byte is perfectly supported. func (txt *Text) WriteByte(c byte) error { txt.buf = append(txt.buf, c) txt.drawBuf() return nil } +// WriteRune writes a rune to the Text. This method never fails, always returns utf8.RuneLen(r), nil. func (txt *Text) WriteRune(r rune) (n int, err error) { var b [4]byte n = utf8.EncodeRune(b[:], r) @@ -187,6 +252,8 @@ func (txt *Text) WriteRune(r rune) (n int, err error) { return n, nil } +// Draw draws all text written to the Text to the provided Target. The text is transformed by the +// Text's matrix and color mask. func (txt *Text) Draw(t pixel.Target) { if txt.dirty { txt.trans.SetLen(txt.tris.Len())