litescreen

Documentation

Overview

Package litescreen is a minimal tcell-free terminal renderer. It opens /dev/tty directly so the process's stdin/stdout remain free for piping, and implements a subset of the tcell.Screen surface (Init/Fini/Size/ SetContent/Clear/Show/ShowCursor/ChannelEvents) sufficient for fuzzy- finder-style TUIs. The intended downstream is gitgum/fuzzyfinder, but the package has no internal dependencies and can be used standalone.

The renderer was developed based on fzf's LightRenderer (junegunn/fzf, src/tui/light.go). The architecture, ANSI handling approach, and several specific techniques — opening /dev/tty for I/O, using DSR (\e[6n) to discover cursor position, scrolling via makeSpace, the ESC-disambiguation timeout — all come from there. Code is freshly written, not copied, but credit is due. fzf is MIT-licensed; see LICENSE-fzf at the repo root.

Index

• type Options
• type Screen
  • func New(height int) (*Screen, error)
  • func NewWithOptions(opts Options) (*Screen, error)
  • func (s *Screen) ChannelEvents(out chan<- tcell.Event, quit <-chan struct{})
  • func (s *Screen) Clear()
  • func (s *Screen) Fini()
  • func (s *Screen) Init() error
  • func (s *Screen) SetContent(x, y int, mainc rune, combc []rune, style tcell.Style)
  • func (s *Screen) Show()
  • func (s *Screen) ShowCursor(x, y int)
  • func (s *Screen) Size() (int, int)

Types

type Options

type Options struct {
	// Height policy. See New for semantics.
	Height int
	// In is the input source. Default: opens /dev/tty.
	In io.Reader
	// Out is the output destination. Default: opens /dev/tty.
	Out io.Writer
	// Size reports terminal dimensions. Default: real ioctl on /dev/tty
	// when In/Out are unset; 80x24 when In or Out is overridden.
	Size func() (w, h int)
}

Options configure construction of a Screen with custom IO and/or size reporting. Use with NewWithOptions when you need to redirect output (e.g. to a bytes.Buffer for tests, or a remote pty for embedding the picker in a larger UI). When In or Out is set, the Screen runs in "headless" mode: no raw mode is entered, no signal handlers are registered, and Size queries fall back to the user-supplied Size func (default 80x24). The caller is then responsible for whatever terminal management is needed.

type Screen

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

func New

func New(height int) (*Screen, error)

New constructs a Screen with the given height policy:

0   fullscreen (alt-screen, preserves nothing above)
N>0 exactly N rows at the bottom; prior output preserved above
N<0 terminal_rows + N (e.g. -2 leaves 2 rows visible above)

IO goes to /dev/tty. For custom IO, see NewWithOptions.

func NewWithOptions

func NewWithOptions(opts Options) (*Screen, error)

NewWithOptions constructs a Screen with custom IO and/or size reporting. If In and Out are both unset, behavior matches New — opens /dev/tty, real raw mode, real signal handlers. If either is set, the Screen runs headless (no raw mode, no signal handlers, no /dev/tty).

func (*Screen) ChannelEvents

func (s *Screen) ChannelEvents(out chan<- tcell.Event, quit <-chan struct{})

ChannelEvents reads from /dev/tty in raw mode, parses keystrokes and SIGWINCH, and emits tcell events on out. Stops when quit closes or input EOFs. The parser handles UTF-8 multibyte runes, control bytes, and the CSI/SS3 escape sequences the finder cares about.

func (*Screen) Clear

func (s *Screen) Clear()

func (*Screen) Fini

func (s *Screen) Fini()

func (*Screen) Init

func (s *Screen) Init() error

func (*Screen) SetContent

func (s *Screen) SetContent(x, y int, mainc rune, combc []rune, style tcell.Style)

func (*Screen) Show

func (s *Screen) Show()

func (*Screen) ShowCursor

func (s *Screen) ShowCursor(x, y int)

func (*Screen) Size

func (s *Screen) Size() (int, int)