Documentation ¶
Overview ¶
Package vterm wraps the libvterm C library to provide a virtual terminal implementation.
The Go API matches closely to the original C API and constants are interchangeable. However, Cell, Properties and Attributes are in native Go format and converted when calling libvterm, which increases readability and reduces the number of cgo calls (but might be slower).
The Go API supports hooking output callback and VTermScreen callbacks.
libvterm consists of several components: VTerm, VTermState, VTermScreen and a Parser. The VTerm has a State and a Screen object and the State has a built-in Parser. Most of the VTermState object and Parser callbacks tend to be internal and are not exposed by the Go API. (There are functions about palettes and colors however)
The VTermScreen and VTermState objects are not separated from the VTerm object; All related methods has *VTerm as the receiver.
The original libvterm included is modified; dynamic arrays are changed to alloca() and some NULL checks are added. Get the original here: http://www.leonerd.org.uk/code/libvterm/
Index ¶
- type Cell
- type CellAttrs
- type Color
- type CursorShape
- type Key
- type Modifier
- type Mouse
- type OutputCallback
- type Pos
- type Property
- type Rect
- type ScreenCallback
- type ScreenCallbackObj
- type Underline
- type VTerm
- func (vt *VTerm) CellAt(row, col int) Cell
- func (vt *VTerm) ConvertRGB(c *Color) (r, g, b uint8)
- func (vt *VTerm) DefaultColors() (fg, bg *Color)
- func (vt *VTerm) EnableAltscreen(enable bool)
- func (vt *VTerm) Free()
- func (vt *VTerm) GetBufferCurrent() int
- func (vt *VTerm) GetBufferRemaining() int
- func (vt *VTerm) GetBufferSize() int
- func (vt *VTerm) GetSize() (rols, cols int)
- func (vt *VTerm) IsEOL(row, col int) bool
- func (vt *VTerm) IsUTF8() bool
- func (vt *VTerm) KeyboardEndPaste()
- func (vt *VTerm) KeyboardKey(key Key, mod Modifier)
- func (vt *VTerm) KeyboardPasteString(str string, mod Modifier)
- func (vt *VTerm) KeyboardStartPaste()
- func (vt *VTerm) KeyboardUnichar(c rune, mod Modifier)
- func (vt *VTerm) MouseButton(button int, pressed bool, mod Modifier)
- func (vt *VTerm) MouseMove(row, col int, mod Modifier)
- func (vt *VTerm) OutputCallback(f OutputCallback, data interface{})
- func (vt *VTerm) OutputWriteTo(w io.Writer)
- func (vt *VTerm) PaletteColor(index int) (col *Color)
- func (vt *VTerm) Read(p []byte) (int, error)
- func (vt *VTerm) ScreenCallback(f ScreenCallback, data interface{})
- func (vt *VTerm) ScreenCallbackObj(i ScreenCallbackObj)
- func (vt *VTerm) SetBoldHighbright(enabled bool)
- func (vt *VTerm) SetDefaultColors(fg, bg *Color)
- func (vt *VTerm) SetPaletteColor(index int, col *Color)
- func (vt *VTerm) SetSize(rols, cols int)
- func (vt *VTerm) TextAt(rect Rect) string
- func (vt *VTerm) UseUTF8(use bool)
- func (vt *VTerm) Write(p []byte) (int, error)
- type Value
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cell ¶
type Cell struct { Chars []rune // Runes inside the cell (may be more than one) Width int // The width of the cell on the vterm (1=one cell, 2=spans across 2 cells, etc.) Attrs CellAttrs // Attribues of the cell Foreground, Background Color // Colors in the cell }
Cell describes a screen cell
type CellAttrs ¶
type CellAttrs struct { Underline Underline // int(Underline), Has underline?/Underline Type Bold bool // bool, Uses bold(and bright) text? Italic bool // bool, Is italic? Blink bool // bool, Is blinking? Reverse bool // bool, Has background/foreground colors reversed? Strike bool // bool, Has strikeline? Font int // int, Uses alternative font? / Font number 0 to 9 DoubleHeight int // DECDHL double-height line flag (0=none 1=top 2=bottom) DoubleWidth bool // Is the cell on a double-width line as in DECDWL or DECDHL }
CellAttrs describes the attributes of a screen cell
type Color ¶
type Color C.VTermColor
Color is a VTerm color instance; it can be a palette color or a RGB one
func NewColorIndexed ¶
NewColorIndexed constructs a new Color using the internal/standard palette.
func NewColorRGB ¶
NewColorRGB constructs a new Color representing the given RGB values.
func (*Color) ConvertRGB ¶
ConvertRGB calls vt.ConvertRGB(c).
func (*Color) Index ¶
Index returns the palette index (0~255) if the color is indexed, -1 otherwise.
type CursorShape ¶
type CursorShape int
CursorShape describes the shape of the cursor. It's a vterm Property.
const ( CursorShapeBlock CursorShape // A solid block CursorShapeUnderline // An underline CursorShapeBarLeft // A vertial bar on the left of the cell )
type Key ¶
type Key int
Key is a speical key not represented by visible text.
const ( KeyNone Key = iota KeyEnter KeyTab KeyBackspace KeyEscape KeyUp KeyDown KeyLeft KeyRight KeyInsert KeyDelete KeyHome KeyEnd KeyPageUp KeyPageDown KeyFunction0 Key = 256 KeyFunctionMax Key = KeyFunction0 + 255 )
All the keys
const ( KeyKeypad0 Key = 512 + iota KeyKeypad1 KeyKeypad2 KeyKeypad3 KeyKeypad4 KeyKeypad5 KeyKeypad6 KeyKeypad7 KeyKeypad8 KeyKeypad9 KeyKeypadMultiply KeyKeypadPlus KeyKeypadComma KeyKeypadMinus KeyKeypadPeriod KeyKeypadDivide KeyKeypadEnter KeyKeypadEqual KeyMax // Must be last KeyCount = KeyMax )
Seperated to reset iota
type Modifier ¶
type Modifier int
Modifier is a bitmask regarding the states of the modifier keys (Ctrl, Alt, Shift).
const ( ModifierNone Modifier = 1 << iota // No modifier ModifierShift // Shift key ModifierAlt // Alt key ModifierCtrl // Ctrl key ModifierAllModsMask = ModifierShift | ModifierAlt | ModifierCtrl // All the modifier keys )
type Mouse ¶
type Mouse int
Mouse describes the moving/button states of the mouse. A vterm Property.
type OutputCallback ¶
type OutputCallback func([]byte, interface{})
OutputCallback is called on new terminal output (into the input of the slave)
type Property ¶
type Property int
Property describes the global state of a virtual terminal.
const ( PropCursorVisible Property // bool, Is cursor visible? PropCursorBlink // bool, Is cursor blinking? PropAltscreen // bool, Is alt-screen active? PropTitle // string, Sets the vterm title PropIconName // string, Icon name PropReverse // bool, Is vterm in reverse-color? PropCursorShape // int(CursorShape), Shape of the cursor PropMouse // int(MouseProp), State of the mouse cursor/button )
type ScreenCallback ¶
type ScreenCallback struct { Damage func(r Rect, data interface{}) bool // A rectangle area on the screen has changed MoveRect func(dest, src Rect, data interface{}) bool // A rect on the screen is moved from src to dest MoveCursor func(pos, oldpos Pos, data interface{}) bool // Moves the cursor from oldpos to pos SetTermProp func(prop Property, value Value, data interface{}) bool // A Property is set Bell func(data interface{}) bool // Rings the bell Resize func(rows, cols int, data interface{}) bool // Terminal is resized ScrollbackPushLine func(cells []Cell, data interface{}) bool // A line in the slice is poped from the top of terminal and pushed the scrollback stack ScrollbackPopLine func(cells []Cell, data interface{}) bool // Terminal is resized and a line is to be poped from the top of the scrollback stack into the slice; returns false if the stack is empty }
ScreenCallback contains multiple callbacks called on screen changes. These functions return true if the action is successfully taken.
type ScreenCallbackObj ¶
type ScreenCallbackObj interface { ScreenCbDamage(r Rect) bool ScreenCbMoveRect(dest, src Rect) bool ScreenCbMoveCursor(pos, oldpos Pos) bool ScreenCbSetTermProp(prop Property, value Value) bool ScreenCbBell() bool ScreenCbResize(rows, cols int) bool ScreenCbScrollbackPushLine(cells []Cell) bool ScreenCbScrollbackPopLine(cells []Cell) bool }
ScreenCallbackObj is an interface object that wraps ScreenCallback in Go manner.
type VTerm ¶
type VTerm struct {
// contains filtered or unexported fields
}
VTerm holds the information for a Terminal. It must be explcitly freed by calling VTerm.Free().
func (*VTerm) ConvertRGB ¶
ConvertRGB converts the Color instance to RGB format (if it is not) using VTermState's internal palette, and then returns the RGB values.
func (*VTerm) DefaultColors ¶
DefaultColors returns the default foreground/background colors.
func (*VTerm) EnableAltscreen ¶
EnableAltscreen enables the screen alt-buffer
func (*VTerm) Free ¶
func (vt *VTerm) Free()
Free frees the VTerm instance. It must be called before disposing the object
func (*VTerm) GetBufferCurrent ¶
GetBufferCurrent returns the occupied space size of the internal buffer. Has no effect when OutputCallback is set.
func (*VTerm) GetBufferRemaining ¶
GetBufferRemaining returns the remaining space size the internal buffer. Has no effect when OutputCallback is set.
func (*VTerm) GetBufferSize ¶
GetBufferSize returns the current internal buffer size. Has no effect when OutputCallback is set.
func (*VTerm) KeyboardEndPaste ¶
func (vt *VTerm) KeyboardEndPaste()
KeyboardEndPaste disables pasting mode.
func (*VTerm) KeyboardKey ¶
KeyboardKey sends a speical key to the vterm.
func (*VTerm) KeyboardPasteString ¶
KeyboardPasteString is a shortcut for pasting a string.
func (*VTerm) KeyboardStartPaste ¶
func (vt *VTerm) KeyboardStartPaste()
KeyboardStartPaste enables pasting mode.
func (*VTerm) KeyboardUnichar ¶
KeyboardUnichar sends a single rune to the vterm.
func (*VTerm) MouseButton ¶
MouseButton is used to update mouse button state (pressed/released). Left mouse button=1, middle=2, right=3; wheel up=4, wheel down=5. For mouse wheel keys you only need to call pressed=true.
func (*VTerm) OutputCallback ¶
func (vt *VTerm) OutputCallback(f OutputCallback, data interface{})
OutputCallback sets the output callback of the vterm object. If set to non-nil, VTerm.Read will have no effect.
func (*VTerm) OutputWriteTo ¶
OutputWriteTo is a shortcut for setting a callback that writes to a io.Writer.
func (*VTerm) PaletteColor ¶
PaletteColor gets the palette color of the given index.
func (*VTerm) Read ¶
Read reads from the internal output buffer VTerm keeps (into the input of the slave). Has no effect when OutputCallback is set.
func (*VTerm) ScreenCallback ¶
func (vt *VTerm) ScreenCallback(f ScreenCallback, data interface{})
ScreenCallback sets the screen callback of the vterm object. TODO Some fields in the ScreenCallback object can be nil while others are not.
func (*VTerm) ScreenCallbackObj ¶
func (vt *VTerm) ScreenCallbackObj(i ScreenCallbackObj)
ScreenCallbackObj sets the screen callbacks with a interface object.
func (*VTerm) SetBoldHighbright ¶
SetBoldHighbright sets whether to use a brighter foreground on text set to bold.
func (*VTerm) SetDefaultColors ¶
SetDefaultColors sets the default foreground/background colors.
func (*VTerm) SetPaletteColor ¶
SetPaletteColor sets the palette color for the given index.