display

package
v0.0.0-...-e2c65c2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 16, 2018 License: Apache-2.0 Imports: 10 Imported by: 0

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.

Also included are colors, palettes, and rendering models for terminal displays supporting 0, 3, 4, 8, and 24 bit color.

Finally a cursor that tracks the known state of the terminal cursor is included; it is useful for appending ANSI escape sequences that incrementally modify the terminal cursor state .

Index

Constants

This section is empty.

Variables

View Source 
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],
	}
)
View Source 
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.

View Source 
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 *foreground* 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 ColorModel 

type ColorModel func(buf []byte, cur Cursor, fg, bg color.RGBA) ([]byte, Cursor)

ColorModel renders colors to a partiular terminal color rendering protocol. 

var (
	// Model0 is the monochrome color model, which does not print escape
	// sequences for any colors.
	Model0 ColorModel = renderNoColor

	// Model3 supports the first 8 color terminal palette.
	Model3 ColorModel = Palette3.Render

	// Model4 supports the first 16 color terminal palette, the same as Model3
	// but doubled for high intensity variants.
	Model4 ColorModel = Palette4.Render

	// Model8 supports a 256 color terminal palette, comprised of the 16
	// previous colors, a 6x6x6 color cube, and a 24 gray scale.
	Model8 ColorModel = Palette8.Render

	// Model24 supports all 24 bit colors, and renders only to 24-bit terminal
	// sequences.
	Model24 ColorModel = renderJustColor24

	// ModelCompat24 supports all 24 bit colors, using palette colors only for exact
	// matches.
	ModelCompat24 ColorModel = renderCompatColor24
)

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

	// Visibility indicates whether the cursor is visible.
	Visibility Visibility
}

Cursor models the known or unknown states of a cursor.

func Render 

func Render(buf []byte, cur Cursor, over *Display, renderColor ColorModel) ([]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, renderColor ColorModel) ([]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; implicitly invalidates the cursor position since its behavior is inconsistent across terminal implementations.

func (Cursor) ClearLine 

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

ClearLine erases the current line.

func (Cursor) Go 

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

Go moves the cursor to another position, preferring 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, which 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) Draw 

func (d *Display) Draw(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 *foreground* 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 (*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) RGBAAt 

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

RGBAAt is a faster version of At.

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) SetRGBA 

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

SetRGBA is a faster Set.

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 Terminal 

type Terminal struct {
	*Display
	// contains filtered or unexported fields
}

Terminal manages rendering a display buffer rendered to a terminal.

func NewTerminal 

func NewTerminal(out *os.File) (*Terminal, error)

NewTerminal takes control of a terminal, readying it for rendering by putting it in raw mode, clearing it, and hiding the cursor.

func (*Terminal) Close 

func (term *Terminal) Close() error

Close the terminal, clearing it and restoring state.

func (*Terminal) Render 

func (term *Terminal) Render() error

Render the display buffer to the terminal.

func (*Terminal) UpdateSize 

func (term *Terminal) UpdateSize() error

UpdateSize updates the terminal buffer to match the terminal's current size.

type TerminalPalette 

type TerminalPalette color.Palette

TerminalPalette is a limited palette of color for legacy terminals. 

var (
	// Palette3 contains the first 8 Colors.
	Palette3 TerminalPalette

	// Palette4 contains the first 16 Colors.
	Palette4 TerminalPalette

	// Palette8 contains all 256 paletted virtual terminal colors.
	Palette8 TerminalPalette
)

func (TerminalPalette) Render 

func (tp TerminalPalette) Render(buf []byte, cur Cursor, fg, bg color.RGBA) ([]byte, Cursor)

Render the given colors to their closest palette equivalents.

type Visibility 

type Visibility int

Visibility represents the visibility of a Cursor. 

const (
	// Hidden represents a hidden cursor.
	Hidden Visibility = iota + 1

	// Visible represents a normal cursor.
	Visible
)

func (Visibility) String 

func (v Visibility) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.