display

Documentation

Overview

Package display models, composes, and renders virtual terminal displays using ANSI escape sequences. Models displays as three layers: a text layer and foreground and background color layers as images in any logical color space. The package includes colors, palettes, and rendering models for terminal displays supporting 0, 3, 4, 8, and 24 bit color. The package also includes a cursor that tracks the known position and colors of the cursor, appending ANSI escape sequences to incrementally modify that state.

Index

• Variables
• func Draw(dst *Display, r image.Rectangle, src *Display, sp image.Point, op draw.Op)
• func New2(r image.Rectangle) (*Display, *Display)
• type Cursor
  • func Render(buf []byte, cur Cursor, over *Display, model Model) ([]byte, Cursor)
  • func RenderOver(buf []byte, cur Cursor, over, under *Display, model Model) ([]byte, Cursor)
  • func (c Cursor) Clear(buf []byte) ([]byte, Cursor)
  • func (c Cursor) Go(buf []byte, to image.Point) ([]byte, Cursor)
  • func (c Cursor) Hide(buf []byte) ([]byte, Cursor)
  • func (c Cursor) Home(buf []byte) ([]byte, Cursor)
  • func (c Cursor) Reset(buf []byte) ([]byte, Cursor)
  • func (c Cursor) Show(buf []byte) ([]byte, Cursor)
  • func (c Cursor) WriteGlyph(buf []byte, s string) ([]byte, Cursor)
• type Display
  • func New(r image.Rectangle) *Display
  • func (d *Display) At(x, y int) (t string, f, b color.Color)
  • func (d *Display) Bounds() image.Rectangle
  • func (d *Display) Clear(r image.Rectangle)
  • func (d *Display) Fill(r image.Rectangle, t string, f, b color.Color)
  • func (d *Display) Set(x, y int, t string, f, b color.Color)
  • func (d *Display) SubDisplay(r image.Rectangle) *Display
• type Model

Variables

var (
	// Lost indicates that the cursor position is unknown.
	Lost = image.Point{-1, -1}

	// Start is a cursor state that makes no assumptions about the cursor's
	// position or colors, necessitating a seek from origin and explicit color
	// settings for the next text.
	Start = Cursor{
		Position:   Lost,
		Foreground: Transparent,
		Background: Transparent,
	}

	// Reset is a cursor state indicating that the cursor is at the origin
	// and that the foreground color is white (7), background black (0).
	// This is the state cur.Reset() returns to, and the state for which
	// cur.Reset() will append nothing to the buffer.
	Reset = Cursor{
		Position:   image.ZP,
		Foreground: Colors[7],
		Background: Colors[0],
	}
)

var (
	// Model0 is the monochrome color model, which does not print escape
	// sequences for any colors.
	Model0 = model{renderNoColor, renderNoColor}
	// Model3 supports the first 8 color terminal palette.
	Model3 = model{renderForegroundColor3, renderBackgroundColor3}
	// Model4 supports the first 16 color terminal palette, the same as Model3
	// but doubled for high intensity variants.
	Model4 = model{renderForegroundColor4, renderBackgroundColor4}
	// Model8 supports a 256 color terminal palette, comprised of the 16
	// previous colors, a 6x6x6 color cube, and a 24 gray scale.
	Model8 = model{renderForegroundColor8, renderBackgroundColor8}
	// Model24 supports all 24 bit colors, using palette colors only for exact
	// matches.
	Model24 = model{renderForegroundColor24, renderBackgroundColor24}
)

var (
	// Palette3 contains the first 8 Colors.
	Palette3 color.Palette
	// Palette4 contains the first 16 Colors.
	Palette4 color.Palette
	// Palette8 contains all 256 paletted virtual terminal colors.
	Palette8 color.Palette
)

var Colors = []color.RGBA{}/* 256 elements not displayed */

Colors contains the 256 color terminal palette. The first 8 correspond to 30-37 foreground and 40-47 background in ANSI escape sequences. The second 8 correspond to 90-97 and 100-107 or the high intensity variants of the first 8 in more advanced ANSI terminals. The next 6x6x6 colors are an RGB cube and the last 24 are shades of gray.

var Transparent = color.RGBA{}

Transparent is transparent in the RGBA color model.

Functions

func Draw

func Draw(dst *Display, r image.Rectangle, src *Display, sp image.Point, op draw.Op)

Draw composes one display over another. The bounds dictate the region of the destination. The offset dictates the position within the source. Draw will:

Overwrite the text layer for all non-empty text cells inside the rectangle. Fill the text with space " " to overdraw all cells.

Draw the foreground of the source over the foreground of the destination image. Typically, the foreground is transparent for all cells empty of text. Otherwise, this operation can have interesting results.

Draw the background of the source over the *background* of the destination image. This allows for translucent background colors on the source image partially obscuring the text of the destination image.

Draw the background of the source over the background of the destination image.

func New2

func New2(r image.Rectangle) (*Display, *Display)

New2 returns a pair of displays with the same rectangle, suitable for creating front and back buffers.

 bounds := term.Bounds()
	front, back := display.New2(bounds)

Types

type Cursor

type Cursor struct {
	// Position is the position of the cursor.
	// Negative values indicate that the X or Y position is not known,
	// so the next position change must be relative to the beginning of the
	// same line or possibly the origin.
	Position image.Point
	// Foreground is the foreground color for subsequent text.
	// Transparent indicates that the color is unknown, so the next text must
	// be preceded by an SGR (set graphics) ANSI sequence to set it.
	Foreground color.RGBA
	// Foreground is the foreground color for subsequent text.
	// Transparent indicates that the color is unknown, so the next text must
	// be preceded by an SGR (set graphics) ANSI sequence to set it.
	Background color.RGBA
}

Cursor models the known or unknown states of a cursor.

func Render

func Render(buf []byte, cur Cursor, over *Display, model Model) ([]byte, Cursor)

Render appends ANSI escape sequences to a byte slice to overwrite an entire terminal window, using the best matching colors in the terminal color model.

func RenderOver

func RenderOver(buf []byte, cur Cursor, over, under *Display, model Model) ([]byte, Cursor)

RenderOver appends ANSI escape sequences to a byte slice to update a terminal display to look like the front model, skipping cells that are the same in the back model, using escape sequences and the nearest matching colors in the given color model.

func (Cursor) Clear

func (c Cursor) Clear(buf []byte) ([]byte, Cursor)

Clear erases the whole display.

func (Cursor) Go

func (c Cursor) Go(buf []byte, to image.Point) ([]byte, Cursor)

Go moves the cursor to another position, prefering to use relative motion, using line relative if the column is unknown, using display origin relative only if the line is also unknown. If the column is unknown, use "\r" to seek to column 0 of the same line.

func (Cursor) Hide

func (c Cursor) Hide(buf []byte) ([]byte, Cursor)

Hide hides the cursor.

func (Cursor) Home

func (c Cursor) Home(buf []byte) ([]byte, Cursor)

Home seeks the cursor to the origin, using display absolute coordinates.

func (Cursor) Reset

func (c Cursor) Reset(buf []byte) ([]byte, Cursor)

Reset returns the terminal to default white on black colors.

func (Cursor) Show

func (c Cursor) Show(buf []byte) ([]byte, Cursor)

Show reveals the cursor.

func (Cursor) WriteGlyph

func (c Cursor) WriteGlyph(buf []byte, s string) ([]byte, Cursor)

WriteGlyph appends the given string's UTF8 bytes into the given buffer, invalidating the cursor if the string COULD HAVE rendered to more than one glyph; otherwise the cursor's X is advanced by 1.

type Display

type Display struct {
	Background *image.RGBA
	Foreground *image.RGBA
	Text       *textile.Textile
	Rect       image.Rectangle
}

Display models a terminal display's state as three images.

func New

func New(r image.Rectangle) *Display

New returns a new display with the given bounding rectangle. The rectangle need not rest at the origin.

func (*Display) At

func (d *Display) At(x, y int) (t string, f, b color.Color)

At returns the text and foreground and background colors at the given coordinates.

func (*Display) Bounds

func (d *Display) Bounds() image.Rectangle

Bounds returns the bounding rectangle of the display.

func (*Display) Clear

func (d *Display) Clear(r image.Rectangle)

Clear fills the display with transparent cells.

func (*Display) Fill

func (d *Display) Fill(r image.Rectangle, t string, f, b color.Color)

Fill overwrites every cell with the given text and foreground and background colors.

func (*Display) Set

func (d *Display) Set(x, y int, t string, f, b color.Color)

Set overwrites the text and foreground and background colors of the cell at the given position.

func (*Display) SubDisplay

func (d *Display) SubDisplay(r image.Rectangle) *Display

SubDisplay returns a mutable sub-region within the display, sharing the same memory.

type Model

type Model interface {
	// Render appends the ANSI sequence for changing the foreground and
	// background color to the nearest colors supported by the terminal color
	// model.
	Render(buf []byte, cur Cursor, fg, bg color.Color) ([]byte, Cursor)
}

Model is the interface for a terminal color rendering model.