vt

type AnsiMode ¶ added in v3.1.0

type AnsiMode int

AnsiMode are modes standardized in ECMA-48. They use CSI-h and CSI-l (no question mark).

const (
	AmKeyboardAction AnsiMode = 2  // Lock the keyboard.
	AmInsertReplace  AnsiMode = 4  // Insert or replace characters when a new character is added.
	AmSendReceive    AnsiMode = 12 // XON or XOFF.
	AmNewLineMode    AnsiMode = 20 // If true, LF emits CR as well, and Return sends both CR and LF.
)

func (pm AnsiMode) Disable() string

func (pm AnsiMode) Enable() string

func (pm AnsiMode) Query() string

func (pm AnsiMode) Reply(status ModeStatus) string

type Attr ¶ added in v3.0.6

type Attr uint16

Attr is a synthetic combination of display attributes for cells, apart from color which is handled separately.

type Backend ¶ added in v3.0.6

type Backend interface {

	// GetPrivateMode returns the status of a given private mode.
	GetPrivateMode(PrivateMode) ModeStatus

	// SetPrivateMode sets a private mode to the given status.
	// If either value is invalid, this should simply ignore the operation.
	SetPrivateMode(PrivateMode, ModeStatus) error

	// GetSize returns the size of the terminal in characters.
	// The X and Y are counts, so the bottom right cell should be at coordinate (X-1, Y-1).
	GetSize() Coord

	// Colors returns the number of colors this terminal can support.  For direct color,
	// return 1<<24. The XTerm palette is assumed. Monochrome terminals should return 0.
	Colors() int

	// Put content at the given location. The string in the cell might be a grapheme cluster, and the width can be
	// 0, 1, or 2.  The backend should try to optimize by keeping style and last coordinates if needed.
	// A graphical backend could use this and be completely stateless.
	Put(Coord, Cell)

	// GetPosition returns the cursor position.
	GetPosition() Coord

	// SetPosition sets the cursor position. If the position is out of bounds,
	// it should be clipped to the window size.
	SetPosition(Coord)

	// Reset resets the terminal to default state.
	Reset()

	// RaiseResize is called by the emulation layer when it has completed its own internal resizing.
	// The backend is responsible for sending a signal (if needed) to child processes as part of this
	// function.  (The emulation layer knows nothing of child processes.)
	RaiseResize()
}

Backend describes the backend of a terminal. This can be used to create a real emulator, while allowing the processor front end to handle the common details of parsing escape sequences, the state machine, and so forth. Backends support a limited set of common functionality, including a cursor. They only need to support writing at the cursor.

type Beeper ¶ added in v3.0.6

type Beeper interface {
	Beep()
}

Beeper can be implemented by a backend to indicate it can ring the bell or beep. This is typically done in response to a 0x07 bell.

type Blitter ¶ added in v3.1.0

type Blitter interface {
	Blit(src, dst, dim Coord)
}

Blitter implements a cell-level blit, where a rectangular range of cells is copied from one location to another. The source and destination may overlap. The old locations will remain unchanged except of course or cells overwritten by the blit. The content will also be clipped to the visible dimensions.

type Button ¶ added in v3.1.0

type Button int

Button is the mouse button pressed or released.

type Cell ¶ added in v3.1.0

type Cell struct {
	C string // Content, it will be a grapheme cluster
	S Style  // Style, a pointer is used efficiency
	W int    // Display width (0, 1, or 2)
}

Cell is a representation of a display cell. Most consumers will not need this. Note, this is not the simplest possible representation, and a 256x256 cell display is going to need about 3MB to store it all, but it's simple, and adequate to retain pretty much all of what we need for Unicode. We could save some memory by using explicit struct pointers and by eliminating grapheme cluster support, but modern users expect these features.

type Col ¶

type Col int

Col indicates a column number (x position). We use zero based indices.

type Coord ¶

type Coord struct {
	X Col // Column number, or X position.
	Y Row // Row number, or Y position.
}

Coord indicates a coordinate. This can also be used for window sizes.

type Emulator ¶ added in v3.0.6

type Emulator interface {
	// SetId sets our identity.
	SetId(name string, version string)

	// SendRaw sends raw data to the consumer.  This bypasses the normal encoding,
	// so it should be used with caution.
	SendRaw([]byte)

	// KeyEvent injects a keyboard event into the emulator, which will ultimately
	// result in data being sent via SendRaw.
	KeyEvent(ev KeyEvent)

	// ResizeEvent is called by a backend when the terminal has resized
	// This will send in-band resize notifications if the client has requested them.
	ResizeEvent(Coord)

	// MouseEvent is called by a backend to report mouse activity.
	MouseEvent(ev MouseEvent)

	// FocusEvent is called by a backend to report that focus is gained (true) or lost (false).
	FocusEvent(bool)

	// Drain waits until any queued but not processed input has finished processing.
	// It also wakes the reader.
	Drain() error

	// Start starts processing.
	Start() error

	// Stop stops processing.
	Stop() error

	// Reader reads data from the emulator.  These are bytes that would be transmitted
	// to a remote party.
	io.Reader

	// Writer writes data to the emulator.  These are commands that the emulator should process.
	io.Writer
}

Emulator is a terminal emulator API. It implements the state machinery (escape parsing and so forth) associated with being a terminal emulator. The backend handles rendering the content, and some low level details.

NOTE: This is not a committed interface yet, its entirely a work in progress.

func NewEmulator(be Backend) Emulator

type KeyCode ¶ added in v3.0.6

type KeyCode rune

KeyCode represents either a physical key, or logical key. When it is the "code", it will represent the logical key such as 'A'. But (on English keyboards), 'A' becomes 'a' (with the ModShift) modifier, as a base. (Sometimes we don't care about the logical keyboard, but only about a physical key, and using the base lets us deal with that.)

Normally KeyCodes are numerically the value of the key they represent. E.g 65 for 'A' or 97 for 'a'.

Following the Kitty protocol, we use the Private Use Area 57344 - 63743 for keys that do not correspond to a Unicode value (such as function keys). However, we do not use the same values as we need to represent more keys here than kitty does.

This should be sufficient to support all known keyboard protocols.

Note that Windows defines key codes for mice and game pads. Those should be treated as different events entirely.

type KeyEvent ¶ added in v3.1.0

type KeyEvent struct {
	Down   bool     // true if event is for key down event
	Repeat int      // if > 1, a repeat count
	Code   KeyCode  // logical key code (X11 key symbol, e.g. 'A')
	Base   KeyCode  // base key code (physical key, e.g 'a'), may be zero if same as code
	Mod    Modifier // modifiers
	Utf    string   // if non-empty, the unicode content for this
}

KeyEvent is a key event.

type MockBackend ¶ added in v3.1.0

type MockBackend interface {
	Backend

	// GetCell returns the cell at the given position, or an empty cell if the
	// position is out of the bounds of the window.
	GetCell(Coord) Cell

	// Bells counts the number of bells rung.
	Bells() int

	// GetTitle gets the current window title.
	GetTitle() string

	// SetSize is used to resize the window.
	// Newly added cells are empty, and content in old cells that out of range is lost.
	SetSize(Coord)
}

MockBackend provides additional mock-specific capabilities on top of Backend. This is meant to facilitate test cases

func NewMockBackend(options ...MockOpt) MockBackend

type MockOpt ¶ added in v3.1.0

type MockOpt interface{ SetMockOpt(mb *mockBackend) }

MockOpt is an interface by which options can change the behavior of the mocked terminal. This is intended to permit easier testing.

type MockOptColors ¶ added in v3.1.0

type MockOptColors int

MockOptColors changes the number of colors the terminal supports.

func (o MockOptColors) SetMockOpt(mb *mockBackend)

type MockOptNoBlit ¶ added in v3.1.0

type MockOptNoBlit struct{}

MockOptNoBlit suppresses the blitter interface.

func (MockOptNoBlit) SetMockOpt(mb *mockBackend)

type MockOptSize ¶ added in v3.1.0

type MockOptSize Coord

MockOptSize changes the default terminal size, which is normally 80x24.

func (o MockOptSize) SetMockOpt(mb *mockBackend)

type MockTerm ¶ added in v3.1.0

type MockTerm interface {
	tty.Tty

	// Pos reports the current cursor position.
	Pos() Coord

	// GetCell returns the cell at the given coordinates.
	// The coordinates must be valid.
	GetCell(Coord) Cell

	// Bells returns the number of times the bell has been rung.
	Bells() int

	// Inject a keyboard event.
	KeyEvent(KeyEvent)

	// Inject a mouse event.
	MouseEvent(MouseEvent)

	// Inject a focus event.
	FocusEvent(bool)

	// GetTitle obtains the current window title.
	GetTitle() string

	// SetSize is used to resize the terminal.
	SetSize(Coord)

	// SendRaw is used to send raw data to the application.
	// This is mostly intended to facilitate fuzz testing the application.
	SendRaw([]byte)

	// Backend returns the backend (used for testing).
	Backend() MockBackend
}

MockTerm is a mock terminal (emulator). It can be used to test the emulator itself, or to test applications (or tcell) that uses the terminal. It also implements the Tty interface used by tcell itself.

func NewMockTerm(opts ...MockOpt) MockTerm

type ModeStatus ¶

type ModeStatus int

ModeStatus represents the status of the mode.

const (
	ModeNA        ModeStatus = 0 // Mode is not supported (or unknown)
	ModeOn        ModeStatus = 1 // Mode is on (e.g. via CSI-h)
	ModeOff       ModeStatus = 2 // Mode is off (e.g. via CSI-l)
	ModeOnLocked  ModeStatus = 3 // Mode is hardwired on
	ModeOffLocked ModeStatus = 4 // Mode is hardwired off
)

func (ms ModeStatus) Changeable() bool

type Modifier ¶ added in v3.0.6

type Modifier int

type MouseEvent ¶ added in v3.1.0

type MouseEvent struct {
	Position Coord    // Location of pointer.
	Button   Button   // Buttons pressed.
	Down     bool     // True on press, false on release.
	Motion   bool     // True if mouse moved at least once cell.
	Mod      Modifier // Modifiers (for modified click).
}

MouseEvent reports a single mouse event. Only a single button may be reported for a given event. The application will have to keep state. As buttons are never pressed exactly simultaneously, the backend will send chords as a series of presses followed by a series of releases.

type MouseReporting ¶ added in v3.1.0

type MouseReporting int

MouseReporting determines what mouse events the backend reports.

type Mouser ¶ added in v3.1.0

type Mouser interface {
	SetMouse(MouseReporting)
}

Mouser adds support configuring mouse reporting. We also assume that a mouse reporter can report focus events.

type PrivateMode ¶

type PrivateMode int

PrivateMode describes a DEC Private Mode.

const (
	PmAppCursor        PrivateMode = 1    // Application cursor keys.
	PmVT52             PrivateMode = 2    // Clear to enable VT52 compatibility (not supported).
	PmColumns          PrivateMode = 3    // Set to enable 132 columns, reset for 80 columns.
	PmScrolling        PrivateMode = 4    // Smooth scrolling (jump by default).
	PmScreen           PrivateMode = 5    // Set to reverse dark and light on screen.
	PmOrigin           PrivateMode = 6    // Coordinates are relative to margins.
	PmAutoMargin       PrivateMode = 7    // Automatically wrap at margin.
	PmAutoRepeat       PrivateMode = 8    // Enable automatic key repeat.
	PmMouseX10         PrivateMode = 9    // Legacy (X10) mouse reporting.
	PmBlinkCursor      PrivateMode = 12   // Blinking (on) or steady (off) cursor.
	PmPrintFF          PrivateMode = 18   // Print form feed after printing screen.
	PmPrintExtent      PrivateMode = 19   // Print full screen (on) or scrolling region (off).
	PmShowCursor       PrivateMode = 25   // Show the cursor (default on).
	PmCharSet          PrivateMode = 42   // Enable national (on) or multinational (off) character sets.
	PmLeftRightMargin  PrivateMode = 69   // Enable left and right margins
	PmMouseButton      PrivateMode = 1000 // Report mouse button events.
	PmMouseDrag        PrivateMode = 1002 // Report mouse motion events when button depressed, requires PmMouseButton.
	PmMouseMotion      PrivateMode = 1003 // Report mouse motion events, requires PmMouseButton.
	PmFocusReports     PrivateMode = 1004 // Send focus gained or lost reports.
	PmMouseSgr         PrivateMode = 1006 // Use SGR sequences for mouse reports.
	PmMouseSgrPixel    PrivateMode = 1016 // Use SGR sequences for mouse reports, using pixel-level coordinates.
	PmAltScreen        PrivateMode = 1049 // 47 and 1047 are alternates, but we use 1049
	PmBracketedPaste   PrivateMode = 2004 // Bracket pasted text with bracketed paste escape sequences.
	PmSyncOutput       PrivateMode = 2026 // Buffer output when enabled, updating screen when reset.
	PmGraphemeClusters PrivateMode = 2027 // Support for grapheme cluster handling.
	PmResizeReports    PrivateMode = 2048 // Send in-band resize reports.
)

func (pm PrivateMode) Disable() string

func (pm PrivateMode) Enable() string

func (pm PrivateMode) Query() string

func (pm PrivateMode) Reply(status ModeStatus) string

type Resizer ¶ added in v3.0.6

type Resizer interface {
	// NotifyResize registers a channel to be posted to if the window size changes.
	NotifyResize(chan<- bool)
}

Resizer adds notifications when the window size changes.

type Row ¶

type Row int

Row indicates a row number (y position). We use zero based indices, although the VT standard mostly communicates using 1-based offsets.

type Style ¶ added in v3.1.0

type Style interface {
	Fg() color.Color              // Fg returns the foreground color.
	Bg() color.Color              // Bg returns the background color.
	Uc() color.Color              // Uc returns the underline color.k
	Attr() Attr                   // Attr returns the associated attributes.
	Url() (string, string)        // Url returns the URL and associated id if one was set.
	WithFg(color.Color) Style     // WithFg creates a new style with the foreground
	WithBg(color.Color) Style     // WithBg creates a new style with the background.
	WithUc(color.Color) Style     // WithUc creates a new style with the underline color
	WithAttr(Attr) Style          // WithAttr creates a new style with the attributes.
	WithUrl(string, string) Style // WithLink creates a new style with the URL and id.
	Equal(Style) bool             // Equal returns true if the styles are the same.
}

Style represents the styling of a cell. This is an interface to prevent direct modification.

type Titler ¶ added in v3.0.6

type Titler interface {
	// SetWindowTitle only changes the window title.
	SetWindowTitle(string)
}

Titler adds support for setting the window title. (Typically this is OSC2.) Note that for security reasons we only support setting this. We don't bother with icon titles, since few terminal emulators support it, and it would be hard for us to do this in any portable fashion.