vt

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

	// Put a single character at a specific position with the given attributes.
	// The cursor should be moved to this location.  It may advance.  If the value
	// of the rune is zero, then the cell is being erased, and no content should be
	// displayed.
	PutAbs(Coord, rune, Attr)

	// 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)
}

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 Col ¶

type Col int

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

type Colorer ¶ added in v3.0.6

type Colorer interface {
	// 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

	// SetFgColor sets the foreground color.
	SetFgColor(color.Color)

	// SetBgColor sets the background color.
	SetBgColor(color.Color)
}

Colorer can select the colors used. This interface is stateful, so that an implementation needs to remember the values and use them.

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

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

	// 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 GraphemePositioner ¶ added in v3.0.6

type GraphemePositioner interface {
	Positioner

	// Put the grapheme cluster at the cursor position. This will occupy a single
	// narrow or wide terminal cell.
	PutGrapheme([]rune)
}

GraphemePositioner adds the ability to write a grapheme cluster to Positioner. If a terminal does not implement this, then it will not support grapheme clusters.

type KbdEvent ¶ added in v3.0.6

type KbdEvent struct {
	Down   bool     // true if event is for key down event
	Repeat int      // if > 1, a repeat count
	Code   KeyCode  // logical key code (X11 keysm, 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
}

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 gamepads. Those should be treated as different events entirely.

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 Positioner ¶ added in v3.0.6

type Positioner interface {

	// Put the rune at the cursor position with the given attributes. The cursor is expected
	// to advance by the rune width.
	PutChar(rune, Attr)
}

Positioner tracks the cursor. Backends that implement this should automatically advance the position after writing content.

type PrivateMode ¶

type PrivateMode int

PrivateMode describes a DEC Private Mode.

const (
	PmAppCursor      PrivateMode = 1 // application cursor keys
	PmAutoMargin     PrivateMode = 7
	PmAltScreen      PrivateMode = 1049 // 47 and 1047 are alternates, but we use 1049
	PmBlinkCursor    PrivateMode = 12
	PmShowCursor     PrivateMode = 25
	PmMouseButton    PrivateMode = 1000
	PmMouseDrag      PrivateMode = 1002
	PmMouseMotion    PrivateMode = 1003
	PmFocusReports   PrivateMode = 1004
	PmMouseSgr       PrivateMode = 1006
	PmMouseSgrPixel  PrivateMode = 1016
	PmBracketedPaste PrivateMode = 2004
	PmSyncOutput     PrivateMode = 2026
	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 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.

type UnderlineColorer ¶ added in v3.0.6

type UnderlineColorer interface {
	Colorer

	// SetUlColor sets the underline color.
	// If color.None is chosen, then default foreground color is used.
	SetUlColor(color.Color)
}

UnderlineColorer adds underline color management to the Colorer.