API Reference on TUI

Component

Mon, 01 Jan 0001 00:00:00 +0000

Component is the core interface for TUI applications.

Interface

 go
 
 
type Component interface {
 Init() Cmd
 Update(msg Msg) (Component, Cmd)
 Render(buf *Buffer, area Rect)
}

Init

 go
 
func Init() Cmd

Called once when the application starts. Return a Cmd to run an initial command (start a timer, fetch data), or nil for no initial action.

Update

 go
 
func Update(msg Msg) (Component, Cmd)

Called when a message arrives (key press, mouse event, timer tick, custom message). Update state and return the component and an optional command. Return a different Component to swap the root component entirely.

Buffer

Mon, 01 Jan 0001 00:00:00 +0000

Buffer is a 2D grid of cells representing terminal content. The framework creates buffers automatically; components write into them during Render.

Creating Buffers

 go
 
buf := tui.NewBuffer(width, height)

Typically you receive a buffer from the framework rather than creating one.

Writing Content

Method	Description
`SetChar(x, y, rune, Style)`	Set a single character
`SetString(x, y, string, Style) int`	Write a string, returns cells written
`SetStringInRect(string, Rect, Style) int`	Write with wrapping, returns lines used
`Fill(Rect, Cell)`	Fill area with a cell
`FillStyle(Rect, Style)`	Apply style to area, preserving characters
`DrawHLine(x, y, width, rune, Style)`	Draw horizontal line
`DrawVLine(x, y, height, rune, Style)`	Draw vertical line

Reading Content

Method	Description
`Get(x, y) Cell`	Read cell at position (emptyCell if out of bounds)

Buffer Operations

Method	Description
`Clear()`	Reset all cells to empty
`Resize(width, height)`	Change dimensions, discard content
`Merge(other, offsetX, offsetY)`	Overlay another buffer at offset
`AddImage(ImagePlacement)`	Register an image for KGP rendering

Diff-Based Rendering

The framework uses Diff internally to produce minimal terminal updates:

Style & Color

Mon, 01 Jan 0001 00:00:00 +0000

Color

Color represents a terminal color. The zero value is “no color” (terminal default).

Constructors

Function	Description
`RGB(r, g, b uint8)`	24-bit true color
`Hex(string)`	From hex string (`"#FF6432"` or `"FF6432"`)
`ANSI256(uint8)`	256-color palette index

ANSI 16 Constants

Standard: Black, Red, Green, Yellow, Blue, Magenta, Cyan, White

Bright: BrightBlack, BrightRed, BrightGreen, BrightYellow, BrightBlue, BrightMagenta, BrightCyan, BrightWhite

Methods

Method	Description
`IsZero() bool`	True if this is the default (no) color

Style

Style defines visual attributes for a cell. It is a value type with a chainable builder.

Layout

Mon, 01 Jan 0001 00:00:00 +0000

The layout system splits rectangular areas according to constraints.

Functions

VSplit

 go
 
func VSplit(area Rect, constraints ...Constraint) []Rect

Splits vertically (top to bottom). Returns one Rect per constraint.

HSplit

 go
 
func HSplit(area Rect, constraints ...Constraint) []Rect

Splits horizontally (left to right). Returns one Rect per constraint.

Layout

 go
 
func Layout(area Rect, dir Direction, constraints []Constraint) []Rect

General-purpose split with explicit direction (Horizontal or Vertical).

Events

Mon, 01 Jan 0001 00:00:00 +0000

All events implement the Msg interface. The framework sends them to your Update method.

Keyboard

 go
 
 
type KeyMsg struct {
 Type KeyType
 Rune rune // only valid when Type == KeyRune
 Alt bool
}

Key Types

Constant	Description
`KeyRune`	Regular character (check `Rune` field)
`KeyEnter`	Enter/Return
`KeyTab` / `KeyBacktab`	Tab / Shift+Tab
`KeyBackspace` / `KeyDelete`	Backspace / Delete
`KeyEscape`	Escape
`KeySpace`	Space
`KeyUp` / `KeyDown` / `KeyLeft` / `KeyRight`	Arrow keys
`KeyHome` / `KeyEnd`	Home / End
`KeyPageUp` / `KeyPageDown`	Page Up / Page Down
`KeyInsert`	Insert
`KeyF1` through `KeyF12`	Function keys
`KeyCtrlA` through `KeyCtrlZ`	Ctrl+letter combinations

Pattern Matching

 go
 
 
switch msg := msg.(type) {
case tui.KeyMsg:
 switch msg.Type {
 case tui.KeyCtrlC:
 return a, tui.QuitCmd()
 case tui.KeyRune:
 switch msg.Rune {
 case 'q':
 return a, tui.QuitCmd()
 }
 }
}

Mouse

 go
 
 
type MouseMsg struct {
 X, Y int
 Button MouseButton
 Action MouseAction
 Alt, Ctrl, Shift bool
}

Button	Description
`MouseLeft` / `MouseMiddle` / `MouseRight`	Standard buttons
`MouseWheelUp` / `MouseWheelDown`	Scroll wheel
`MouseNone`	No button (motion event)

Action	Description
`MousePress`	Button pressed
`MouseRelease`	Button released
`MouseMotion`	Mouse moved

Resize

 go
 
 
type ResizeMsg struct {
 Width, Height int
}

Sent when the terminal dimensions change.

Image

Mon, 01 Jan 0001 00:00:00 +0000

Complete KGP image integration. All functions return escape sequence strings ready to flush to the terminal.

ImagePlacement

ImagePlacement describes an image to render at a terminal position. Use the chainable With* methods to configure.

Creating Placements

 go
 
func NewImagePlacement(x, y, cols, rows int) ImagePlacement

Data Sources

Method	Description
`WithPNG([]byte)`	PNG-encoded data
`WithRGBA([]byte, w, h)`	Raw 32-bit RGBA pixels
`WithRGB([]byte, w, h)`	Raw 24-bit RGB pixels
`WithImage(image.Image)`	Convert Go image to PNG
`WithImageRGBA(image.Image)`	Convert Go image to RGBA
`WithImageRGB(image.Image)`	Convert Go image to RGB
`WithImageID(uint32)`	Reference a pre-transmitted image

Transmission Methods

Method	Description
`WithFile(path, format)`	Read from filesystem
`WithFileOffset(path, format, offset, size)`	Read byte range from file
`WithTempFile(path, format)`	Temp file (terminal auto-deletes)
`WithSharedMemory(name, size, format)`	POSIX shared memory

Display Options

Method	Description
`WithCrop(x, y, w, h)`	Source rectangle for cropping
`WithCellOffset(x, y)`	Pixel offset within starting cell
`WithZIndex(int)`	Layering (negative = below text)
`WithCursorMove(bool)`	Advance cursor after placement
`WithCompression()`	ZLIB compress RGBA/RGB data
`WithVirtual()`	Unicode placeholder mode
`WithRelativeTo(parentID, placeID, offsetH, offsetV)`	Relative positioning

ID Management

Method	Description
`WithID(uint32)`	Set image ID
`WithImageNumber(uint32)`	Set client-side image number
`WithPlacementID(uint32)`	Set placement ID
`WithResponseSuppression(mode)`	Control terminal responses

Image Manager

ImageManager tracks transmitted images and manages lifecycle.

Animation

Mon, 01 Jan 0001 00:00:00 +0000

KGP animation support for building, transmitting, and controlling animated images.

Animation Builder

 go
 
anim := tui.NewAnimation(imageID)

Adding Frames

Method	Description
`AddFrame(data, format, w, h, gapMS)`	Raw pixel data
`AddPNGFrame(pngData, gapMS)`	PNG data
`AddImageFrame(image.Image, gapMS)`	Go image (converted to PNG)
`AddRGBAFrame(data, w, h, gapMS)`	Raw RGBA pixels
`AddRGBFrame(data, w, h, gapMS)`	Raw RGB pixels
`AddSolidFrame(w, h, r, g, b, a, gapMS)`	Solid color frame

Frame Options

Method	Description
`SetFrameComposition(idx, mode, bgFrame)`	Set composition mode
`SetFrameBackground(idx, r, g, b, a)`	Set background color

Fields

Field	Description
`ImageID`	Target image ID
`Frames`	Slice of `AnimationFrame`
`LoopCount`	0=default, 1=infinite, N>1 loops N-1 times
`DefaultGap`	Default frame gap in ms

Encoding

 go
 
func (a *Animation) Encode() string

Returns escape sequences for all frames after the first (frame 1 is the base image, transmitted separately).

Widgets

Mon, 01 Jan 0001 00:00:00 +0000

All widgets are in the tui/widget package. Interactive widgets follow the pattern:

 go
 
 
widget, cmd = widget.Update(msg) // in Update
widget.Render(buf, area) // in Render

Most widgets support SetBlock(tui.Block) for borders and titles.

Text

Static text display with alignment.

 go
 
func NewText(content string) *Text

Method	Description
`SetStyle(Style)`	Text style
`SetAlignment(Alignment)`	`AlignLeft`, `AlignCenter`, `AlignRight`
`SetBlock(Block)`	Border

Input

Single-line text input with cursor.

 go
 
func NewInput(placeholder string) *Input

Field	Description
`Value`	Current text value
`Focused`	Whether input accepts keys

Method	Description
`Update(Msg) (*Input, Cmd)`	Handle key events
`Focus() Cmd`	Return focus command
`SetBlock(Block)`	Border
`SetStyle(Style)`	Text style

Keyboard: Home, End, Left, Right, Backspace, Delete, Ctrl+U, Ctrl+K, Ctrl+W.