vio

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: May 8, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package vio provides Vigo's terminal screen abstraction: cells, attributes, surfaces, palettes, glyph sets, and a Screen interface backed by tcell or a fake screen for tests.

Index

Constants

View Source 
const (
	Black        = tcell.ColorBlack
	Blue         = tcell.ColorNavy // BIOS "blue", the dark TV desktop
	Green        = tcell.ColorGreen
	Cyan         = tcell.ColorTeal
	Red          = tcell.ColorMaroon
	Magenta      = tcell.ColorPurple
	Brown        = tcell.ColorOlive
	LightGray    = tcell.ColorSilver
	DarkGray     = tcell.ColorGray
	LightBlue    = tcell.ColorBlue
	LightGreen   = tcell.ColorLime
	LightCyan    = tcell.ColorAqua
	LightRed     = tcell.ColorRed
	LightMagenta = tcell.ColorFuchsia
	Yellow       = tcell.ColorYellow
	White        = tcell.ColorWhite
)

Common Borland-style palette colors, named after their CGA/EGA originals.

View Source 
const (
	ShadeLight  rune = '░'
	ShadeMedium rune = '▒'
	ShadeDark   rune = '▓'
	ShadeFull   rune = '█'
)

Shading runes used for backgrounds, dimming, and gauges.

View Source 
const DesktopDot = ShadeLight

DesktopDot is the rune used by app.Background to fill the desktop. Classic Turbo Vision used CP437 0xB0 (the light shade '░'); the same glyph in Unicode is the closest visual match across modern terminals.

Variables

View Source 
var (
	Single = BorderSet{
		H: '─', V: '│',
		TL: '┌', TR: '┐', BL: '└', BR: '┘',
		LJ: '├', RJ: '┤', TJ: '┬', BJ: '┴', IX: '┼',
	}
	Double = BorderSet{
		H: '═', V: '║',
		TL: '╔', TR: '╗', BL: '╚', BR: '╝',
		LJ: '╠', RJ: '╣', TJ: '╦', BJ: '╩', IX: '╬',
	}
	// ASCII fallback used when the terminal can't render Unicode box-drawing
	// glyphs (e.g. LANG=C with no UTF-8 support).
	ASCII = BorderSet{
		H: '-', V: '|',
		TL: '+', TR: '+', BL: '+', BR: '+',
		LJ: '+', RJ: '+', TJ: '+', BJ: '+', IX: '+',
	}
)

Single-line and double-line border glyphs, matching the Turbo Vision classic frames.

View Source 
var BorlandClassic = Palette{
	{Fg: LightGray, Bg: Blue},
	{Fg: Black, Bg: LightGray},
	{Fg: DarkGray, Bg: LightGray},
	{Fg: Black, Bg: Green},
	{Fg: LightRed, Bg: LightGray},
	{Fg: Black, Bg: LightGray},
	{Fg: DarkGray, Bg: LightGray},
	{Fg: White, Bg: Black},
	{Fg: LightRed, Bg: LightGray},
	{Fg: LightGray, Bg: Blue},
	{Fg: Yellow, Bg: Blue},
	{Fg: White, Bg: Blue},
	{Fg: DarkGray, Bg: Black},
	{Fg: Black, Bg: LightGray},
	{Fg: Black, Bg: LightGray},
	{Fg: White, Bg: LightGray},
	{Fg: LightRed, Bg: LightGray},
	{Fg: Black, Bg: Green},
	{Fg: White, Bg: Green},
	{Fg: DarkGray, Bg: LightGray},
	{Fg: Yellow, Bg: Green},
	{Fg: White, Bg: Blue},
	{Fg: White, Bg: Cyan},
	{Fg: Black, Bg: LightGray},
	{Fg: Black, Bg: Cyan},
	{Fg: Black, Bg: Green},
	{Fg: Yellow, Bg: Green},
	{Fg: LightRed, Bg: Cyan},
	{Fg: Yellow, Bg: Cyan},
	{Fg: Black, Bg: Green},
	{Fg: Black, Bg: Cyan},
	{Fg: White, Bg: Green},
	{Fg: White, Bg: Cyan},
	{Fg: DarkGray, Bg: Cyan},
}

BorlandClassic is the default Turbo Vision palette (subset; full set is fleshed out as widgets ship in v0.2). Indices map 1..N as Turbo Vision did, leaving room for theme overlays.

Functions

This section is empty.

Types

type Attr 

type Attr struct {
	Fg, Bg Color
	Mod    Modifier
}

Attr describes the visual attributes of a single screen cell.

func NewAttr 

func NewAttr(fg, bg Color) Attr

NewAttr is a small convenience constructor.

func (Attr) Style 

func (a Attr) Style() tcell.Style

Style converts the attribute to a tcell.Style.

func (Attr) With 

func (a Attr) With(mod Modifier) Attr

With returns a copy of a with the given modifiers added.

func (Attr) Without 

func (a Attr) Without(mod Modifier) Attr

Without returns a copy of a with the given modifiers cleared.

type BorderSet 

type BorderSet struct {
	H, V               rune // horizontal, vertical
	TL, TR, BL, BR     rune // four corners
	LJ, RJ, TJ, BJ, IX rune // tee joins (left, right, top, bottom) and intersection
}

BorderSet is the rune set used to draw a rectangular frame.

type Cell 

type Cell struct {
	Rune rune
	Attr Attr
}

Cell is a single screen position: one rune plus its visual attributes. Wide characters (e.g. East Asian double-width or emoji) occupy two consecutive cells; the trailing cell carries Rune == 0 to mark continuation.

type Color 

type Color = tcell.Color

Color is the foreground or background color of a cell. It is type-aliased to tcell.Color to avoid forcing translations at call sites; vio is the only package that should know it is tcell underneath.

type FakeScreen 

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

FakeScreen is an in-memory Screen for tests. It keeps a Surface that reflects the latest Show() call, exposes a queueable event channel via PushEvent, and never blocks on terminal I/O.

func NewFakeScreen 

func NewFakeScreen(w, h int) *FakeScreen

NewFakeScreen returns a fake screen of the given size.

func (*FakeScreen) Cursor 

func (f *FakeScreen) Cursor() (x, y int, visible bool)

Cursor returns the last cursor state set by Application.

func (*FakeScreen) Events 

func (f *FakeScreen) Events() <-chan event.Event

Events returns the queue of pushed events.

func (*FakeScreen) Fini 

func (f *FakeScreen) Fini()

Fini closes the event channel, signaling any consumer to exit.

func (*FakeScreen) Init 

func (f *FakeScreen) Init() error

Init is a no-op; FakeScreen is ready to use as soon as it is constructed.

func (*FakeScreen) PushEvent 

func (f *FakeScreen) PushEvent(e event.Event)

PushEvent queues an event to be delivered to the consumer. Tests can drive an Application by pushing key/mouse events.

func (*FakeScreen) Resize 

func (f *FakeScreen) Resize(w, h int)

Resize changes the screen dimensions and emits a synthetic resize event.

func (*FakeScreen) SetCursor 

func (f *FakeScreen) SetCursor(x, y int, visible bool)

SetCursor records the cursor position for inspection.

func (*FakeScreen) Show 

func (f *FakeScreen) Show(s *Surface) error

Show records the supplied surface for inspection by tests.

func (*FakeScreen) Size 

func (f *FakeScreen) Size() (int, int)

Size returns the configured dimensions.

func (*FakeScreen) Surface 

func (f *FakeScreen) Surface() *Surface

Surface returns the surface as of the last Show call. The returned surface is shared with the screen and callers must not mutate it while tests are running, but for read-only snapshots (Snapshot, At) it is safe.

type Modifier 

type Modifier uint8

Modifier is a bitmask of attribute modifiers (bold, italic, underline...). 

const (
	ModNone Modifier = 0
	ModBold Modifier = 1 << iota
	ModItalic
	ModUnderline
	ModReverse
	ModBlink
	ModStrike
)

Modifier flags.

type Palette 

type Palette []Attr

Palette is an ordered list of attributes. Views look up attributes by a 1-indexed slot number to decouple their drawing code from concrete colors; themes can swap palettes at runtime without touching any view's Draw.

Slot 0 is conventionally reserved for an "unset" attribute (transparent fall-through). The first usable slot is 1.

func (Palette) Map 

func (p Palette) Map(i byte) Attr

Map returns the attribute at slot `i` (1-indexed). Out-of-range slots fall back to the first attribute in the palette, or to Attr{} on an empty palette, silently, to match Turbo Vision's tolerant indexing scheme.

type Point 

type Point struct {
	X, Y int
}

Point is a row/column coordinate. X grows right, Y grows down. Both are 0-indexed.

func (Point) Add 

func (p Point) Add(q Point) Point

Add returns p shifted by q.

func (Point) Sub 

func (p Point) Sub(q Point) Point

Sub returns p shifted by -q.

type Rect 

type Rect struct {
	X, Y, W, H int
}

Rect is an axis-aligned rectangle in cell coordinates. (X, Y) is the top-left corner and W, H are the width and height in cells. A rect with W <= 0 or H <= 0 is empty.

func R 

func R(x, y, w, h int) Rect

R is a convenience constructor.

func (Rect) Bottom 

func (r Rect) Bottom() int

Bottom returns the Y coordinate of the row immediately past the rect.

func (Rect) Contains 

func (r Rect) Contains(p Point) bool

Contains reports whether p lies inside r.

func (Rect) Inset 

func (r Rect) Inset(n int) Rect

Inset returns a rect shrunk uniformly by n cells on every side.

func (Rect) Intersect 

func (r Rect) Intersect(o Rect) Rect

Intersect returns the largest rect contained in both r and o; the result is empty when there is no overlap.

func (Rect) IsEmpty 

func (r Rect) IsEmpty() bool

IsEmpty reports whether the rect has no cells.

func (Rect) Right 

func (r Rect) Right() int

Right returns the X coordinate of the column immediately past the rect.

func (Rect) Translate 

func (r Rect) Translate(dx, dy int) Rect

Translate returns r shifted by (dx, dy).

type Screen 

type Screen interface {
	// Init opens the terminal, switches to the alternate screen, hides the
	// cursor, and starts the event pump. It is illegal to call any other
	// method before Init returns nil.
	Init() error

	// Fini restores the terminal state. It is safe to call multiple times.
	Fini()

	// Size returns the current screen dimensions.
	Size() (w, h int)

	// Show flushes the supplied surface to the terminal. The surface size
	// must match Screen.Size().
	Show(s *Surface) error

	// Events returns the channel of input events. The channel is closed when
	// the screen is finalized.
	Events() <-chan event.Event

	// SetCursor positions the hardware cursor. visible == false hides it.
	SetCursor(x, y int, visible bool)
}

Screen is the contract every backend implements: a sized cell grid, an event source, and a flush primitive. The vio package ships two implementations: a tcell-backed real screen and an in-memory fake screen suitable for tests.

func NewTcellScreen 

func NewTcellScreen() Screen

NewTcellScreen returns a Screen backed by github.com/gdamore/tcell/v2.

type Surface 

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

Surface is an in-memory grid of Cells. It is the single drawing target the view tree composes onto each frame; the active Screen flushes it to the terminal at the end of every frame.

Surfaces are not safe for concurrent mutation. The framework is single- threaded for UI work; background goroutines must post events instead.

func NewSurface 

func NewSurface(w, h int) *Surface

NewSurface allocates a surface of the given size, with all cells set to the zero Cell (rune 0, Attr{}).

func (*Surface) At 

func (s *Surface) At(x, y int) Cell

At returns the cell at (x, y). If (x, y) is out of bounds, the zero Cell is returned.

func (*Surface) Box 

func (s *Surface) Box(r Rect, b BorderSet, attr Attr)

Box draws a rectangular frame around r using the supplied border set and attribute. The frame is drawn on the boundary cells of r; r's interior is untouched.

func (*Surface) Clear 

func (s *Surface) Clear(attr Attr)

Clear fills the entire surface with a space character in attr.

func (*Surface) DrawShadow 

func (s *Surface) DrawShadow(r Rect)

DrawShadow paints the Turbo Vision drop-shadow: two columns to the right and one row below r, dimmed to dark-gray-on-black.

func (*Surface) DrawString 

func (s *Surface) DrawString(x, y int, str string, attr Attr) int

DrawString writes str starting at (x, y) and stops at the right edge of the surface. It returns the number of runes drawn.

func (*Surface) FillRect 

func (s *Surface) FillRect(r Rect, ch rune, attr Attr)

FillRect fills r with ch and attr, clipped to the surface.

func (*Surface) Resize 

func (s *Surface) Resize(w, h int)

Resize re-allocates the surface to (w, h). The contents are reset to zero. Callers should follow with a Clear or full re-draw.

func (*Surface) Set 

func (s *Surface) Set(x, y int, ch rune, attr Attr)

Set writes a single cell. Out-of-bounds writes are silently dropped, which matches Turbo Vision's clipping behavior and removes a class of off-by-one crashes.

func (*Surface) Size 

func (s *Surface) Size() (w, h int)

Size returns the surface dimensions.

func (*Surface) Snapshot 

func (s *Surface) Snapshot() []string

Snapshot returns a copy of every cell row, joined into a slice of strings. Cells with rune 0 are rendered as spaces. Intended only for tests and debugging.

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.