vaxis

package module
v0.10.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2024 License: Apache-2.0 Imports: 28 Imported by: 19

README

Vaxis

It begins with them, but ends with me. Their son, Vaxis

Vaxis is a Terminal User Interface (TUI) library for go. Vaxis supports modern terminal features, such as styled underlines and graphics. A widgets package is provided with some useful widgets.

Vaxis is blazingly fast at rendering. It might not be as fast or efficient as notcurses, but significant profiling has been done to reduce all render bottlenecks while still maintaining the feature-set.

All input parsing is done using a real terminal parser, based on the excellent state machine by Paul Flo Williams. Some modifications have been made to allow for proper SGR parsing (':' separated sub-parameters)

Vaxis does not use terminfo. Support for features is detected through terminal queries. Vaxis assumes xterm-style escape codes everywhere else.

Contributions are welcome.

Usage

Minimal example
package main

import "git.sr.ht/~rockorager/vaxis"

func main() {
	vx, err := vaxis.New(vaxis.Options{})
	if err != nil {
		panic(err)
	}
	defer vx.Close()
	for ev := range vx.Events() {
		switch ev := ev.(type) {
		case vaxis.Key:
			switch ev.String() {
			case "Ctrl+c":
				return
			}
		}
		win := vx.Window()
		win.Clear()
		win.Print(vaxis.Segment{Text: "Hello, World!"})
		vx.Render()
	}
}

Support

Questions are welcome in #vaxis on libera.chat, or on the mailing list.

Issues can be reported on the tracker.

TUI Library Roundup

Notcurses is included because it's the most advanced, most efficient, most dank TUI library

Feature Vaxis tcell bubbletea notcurses
RGB ✅ ✅ ✅ ✅
Hyperlinks ✅ ✅ ❌ ❌
Bracketed Paste ✅ ✅ ❌ ❌
Kitty Keyboard ✅ ❌ ❌ ✅
Styled Underlines ✅ ❌ ❌ ✅
Application IDs (OSC 176) ✅ ❌ ❌ ❌
Background color query (OSC 11) ✅ ❌ ❌ ✅
Mouse Shapes (OSC 22) ✅ ❌ ❌ ❌
System Clipboard (OSC 52) ✅ ❌ ❌ ❌
System Notifications (OSC 9) ✅ ❌ ❌ ❌
System Notifications (OSC 777) ✅ ❌ ❌ ❌
Synchronized Output (DEC 2026) ✅ ❌ ❌ ✅
Unicode Core (DEC 2027) ✅ ❌ ❌ ❌
Color Mode Updates (DEC 2031) ✅ ❌ ❌ ❌
Images (full/space) ✅ ❌ ❌ ✅
Images (half block) ✅ ❌ ❌ ✅
Images (quadrant) ❌ ❌ ❌ ✅
Images (sextant) ❌ ❌ ❌ ✅
Images (sixel) ✅ ✅ ❌ ✅
Images (kitty) ✅ ❌ ❌ ✅
Images (iterm2) ❌ ❌ ❌ ✅
Video ❌ ❌ ❌ ✅
Dank 🆗 ❌ ❌ ✅

Documentation

Overview

Package vaxis is a terminal user interface for modern terminals

Index

Examples

Constants

View Source 
const (
	KeyUp rune = extended + 1 + iota
	KeyRight
	KeyDown
	KeyLeft
	KeyInsert
	KeyDelete
	KeyPgDown
	KeyPgUp
	KeyHome
	KeyEnd
	KeyF00
	KeyF01
	KeyF02
	KeyF03
	KeyF04
	KeyF05
	KeyF06
	KeyF07
	KeyF08
	KeyF09
	KeyF10
	KeyF11
	KeyF12
	KeyF13
	KeyF14
	KeyF15
	KeyF16
	KeyF17
	KeyF18
	KeyF19
	KeyF20
	KeyF21
	KeyF22
	KeyF23
	KeyF24
	KeyF25
	KeyF26
	KeyF27
	KeyF28
	KeyF29
	KeyF30
	KeyF31
	KeyF32
	KeyF33
	KeyF34
	KeyF35
	KeyF36
	KeyF37
	KeyF38
	KeyF39
	KeyF40
	KeyF41
	KeyF42
	KeyF43
	KeyF44
	KeyF45
	KeyF46
	KeyF47
	KeyF48
	KeyF49
	KeyF50
	KeyF51
	KeyF52
	KeyF53
	KeyF54
	KeyF55
	KeyF56
	KeyF57
	KeyF58
	KeyF59
	KeyF60
	KeyF61
	KeyF62
	KeyF63 // F63 is max defined in terminfo
	KeyClear
	KeyDownLeft
	KeyDownRight
	KeyUpLeft
	KeyUpRight
	KeyCenter
	KeyBegin
	KeyCancel
	KeyClose
	KeyCommand
	KeyCopy
	KeyExit
	KeyPrint
	KeyRefresh
	// notcurses says these are only avaialbe in kitty kbp
	KeyCapsLock
	KeyScrollLock
	KeyNumlock
	KeyPrintScreen
	KeyPause
	KeyMenu
	// Media keys, also generally only kitty kbp
	KeyMediaPlay
	KeyMediaPause
	KeyMediaPlayPause
	KeyMediaRev
	KeyMediaStop
	KeyMediaFF
	KeyMediaRewind
	KeyMediaNext
	KeyMediaPrev
	KeyMediaRecord
	KeyMediaVolDown
	KeyMediaVolUp
	KeyMediaMute
	// Modifiers, when pressed by themselves
	KeyLeftShift
	KeyLeftControl
	KeyLeftAlt
	KeyLeftSuper
	KeyLeftHyper
	KeyLeftMeta
	KeyRightShift
	KeyRightControl
	KeyRightAlt
	KeyRightSuper
	KeyRightHyper
	KeyRightMeta
	KeyL3Shift
	KeyL5Shift
	// Numerical pad keys, also generally only kitty kbp
	KeyKeyPad0
	KeyKeyPad1
	KeyKeyPad2
	KeyKeyPad3
	KeyKeyPad4
	KeyKeyPad5
	KeyKeyPad6
	KeyKeyPad7
	KeyKeyPad8
	KeyKeyPad9
	KeyKeyPadDecimal
	KeyKeyPadDivide
	KeyKeyPadMultiply
	KeyKeyPadSubtract
	KeyKeyPadAdd
	KeyKeyPadEnter
	KeyKeyPadEqual
	KeyKeyPadSeparator
	KeyKeyPadLeft
	KeyKeyPadRight
	KeyKeyPadUp
	KeyKeyPadDown
	KeyKeyPadPageUp
	KeyKeyPadPageDown
	KeyKeyPadHome
	KeyKeyPadEnd
	KeyKeyPadInsert
	KeyKeyPadDelete
	KeyKeyPadBegin

	// Aliases
	KeyEnter     = 0x0D
	KeyReturn    = KeyEnter
	KeyTab       = 0x09
	KeyEsc       = 0x1B
	KeySpace     = 0x20
	KeyBackspace = 0x7F
)
View Source 
const (
	CursorDefault = iota
	CursorBlockBlinking
	CursorBlock
	CursorUnderlineBlinking
	CursorUnderline
	CursorBeamBlinking
	CursorBeam
)

Variables

This section is empty.

Functions

func EncodeCells added in v0.6.2 

func EncodeCells(cells []Cell) string

Types

type AttributeMask 

type AttributeMask uint8

AttributeMask represents a bitmask of boolean attributes to style a cell 

const (
	AttrNone               = 0
	AttrBold AttributeMask = 1 << iota
	AttrDim
	AttrItalic
	AttrBlink
	AttrReverse
	AttrInvisible
	AttrStrikethrough
)

type CSIuBitMask added in v0.8.0 

type CSIuBitMask int
const (
	CSIuDisambiguate CSIuBitMask = 1 << iota
	CSIuReportEvents
	CSIuAlternateKeys
	CSIuAllKeys
	CSIuAssociatedText
)

type Cell 

type Cell struct {
	Character
	Style
	// contains filtered or unexported fields
}

Cell represents a single cell in a terminal window. It contains a Character and a Style, which fully defines the value. The zero value is rendered as an empty space

func ParseStyledString added in v0.6.2 

func ParseStyledString(s string) []Cell

Parses an SGR styled string into a slice of [Cell]s. This function does not depend on a Vaxis instance. The underlying cells will always be measured using correct unicode methods. If you are directly using these in a Vaxis window, you should either properly measure the graphemes based on your terminals capabilities or set the widths to 0 to enable vaxis to measure them

type Character 

type Character struct {
	Grapheme string
	Width    int
}

Character is a single extended-grapheme-cluster. It also contains the width of the EGC

func Characters 

func Characters(s string) []Character

Converts a string into a slice of Characters suitable to assign to terminal cells

type Color 

type Color uint32

Color is a terminal color. The zero value represents the default foreground or background color

func HexColor 

func HexColor(v uint32) Color

HexColor creates a new Color based on the supplied 24-bit hex value

Example 
package main

import (
	"git.sr.ht/~rockorager/vaxis"
)

func main() {
	vx, _ := vaxis.New(vaxis.Options{})
	// Creates an RGB color from a hex value
	color := vaxis.HexColor(0x00AABB)
	vx.Window().Fill(vaxis.Cell{
		Character: vaxis.Character{
			Grapheme: " ",
			Width:    1,
		},
		Style: vaxis.Style{
			Background: color,
		},
	})
}

Output:

func IndexColor 

func IndexColor(index uint8) Color

IndexColor creates a new Color from the supplied 8 bit value. Values 0-255 are valid

Example 
package main

import (
	"git.sr.ht/~rockorager/vaxis"
)

func main() {
	vx, _ := vaxis.New(vaxis.Options{})
	// Index 1 is usually a red
	color := vaxis.IndexColor(1)
	vx.Window().Fill(vaxis.Cell{
		Character: vaxis.Character{
			Grapheme: " ",
			Width:    1,
		},
		Style: vaxis.Style{
			Background: color,
		},
	})
}

Output:

func RGBColor 

func RGBColor(r uint8, g uint8, b uint8) Color

RGBColor creates a new Color based on the supplied RGB values

Example 
package main

import (
	"git.sr.ht/~rockorager/vaxis"
)

func main() {
	vx, _ := vaxis.New(vaxis.Options{})
	color := vaxis.RGBColor(1, 2, 3)
	vx.Window().Fill(vaxis.Cell{
		Character: vaxis.Character{
			Grapheme: "a",
		},
		Style: vaxis.Style{
			Background: color,
		},
	})
}

Output:

func (Color) Params added in v0.4.7 

func (c Color) Params() []uint8

Params returns the TParm parameters for the color, or an empty slice if the color is the default color

type ColorThemeMode added in v0.1.2 

type ColorThemeMode int

ColorThemeMode is the current color theme of the terminal. The raw value is equivalent to the DSR response value for each mode. 

const (
	// The terminal has a dark color theme
	DarkMode ColorThemeMode = 1
	// The terminal has a light color theme
	LightMode ColorThemeMode = 2
)

type ColorThemeUpdate added in v0.1.2 

type ColorThemeUpdate struct {
	Mode ColorThemeMode
}

ColorThemeUpdate is sent when the terminal color scheme has changed. This event is only delivered if supported by the terminal

type CursorStyle 

type CursorStyle int

CursorStyle is the style to display the hardware cursor

type Event 

type Event interface{}

Event is an empty interface used to pass data within a Vaxis application. Vaxis will emit user input events as well as other input-related events. Users can use PostEvent to post their own events into the loop

type EventType 

type EventType int

EventType is an input event type (press, repeat, release, etc) 

const (
	// The key / button was pressed
	EventPress EventType = iota
	// The key / button was repeated
	EventRepeat
	// The key / button was released
	EventRelease
	// A mouse motion event (with or without a button press)
	EventMotion
	// The key resulted from a paste
	EventPaste
)

type FocusIn 

type FocusIn struct{}

FocusIn is sent when the terminal has gained focus

type FocusOut 

type FocusOut struct{}

FocusOut is sent when the terminal has lost focus

type FullBlockImage added in v0.3.0 

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

FullBlockImage is an image composed of 0x20 characters. This is the most primitive graphics protocol

func (*FullBlockImage) CellSize added in v0.3.0 

func (fb *FullBlockImage) CellSize() (int, int)

func (*FullBlockImage) Destroy added in v0.3.0 

func (fb *FullBlockImage) Destroy()

func (*FullBlockImage) Draw added in v0.3.0 

func (fb *FullBlockImage) Draw(win Window)

func (*FullBlockImage) Resize added in v0.3.0 

func (fb *FullBlockImage) Resize(w int, h int)

Resize resizes and re-encodes an image

type HalfBlockImage added in v0.3.0 

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

HalfBlockImage is an image composed of half block characters.

func (*HalfBlockImage) CellSize added in v0.3.0 

func (hb *HalfBlockImage) CellSize() (int, int)

func (*HalfBlockImage) Destroy added in v0.3.0 

func (hb *HalfBlockImage) Destroy()

func (*HalfBlockImage) Draw added in v0.3.0 

func (hb *HalfBlockImage) Draw(win Window)

func (*HalfBlockImage) Resize added in v0.3.0 

func (hb *HalfBlockImage) Resize(w int, h int)

Resize resizes and re-encodes an image

type Image added in v0.3.0 

type Image interface {
	// Draw draws the [Image] to the [Window]. The image will not be drawn
	// if it is larger than the window
	Draw(Window)
	// Destroy removes an image from memory. Call when done with this image
	Destroy()
	// Resizes the image to fit within the provided area. The image will not
	// be upscaled, nor will it's aspect ratio be changed
	Resize(w int, h int)
	// CellSize is the current cell size of the encoded image
	CellSize() (w int, h int)
}

Image is a static image on the screen

Example 
package main

import (
	"image/png"
	"os"

	"git.sr.ht/~rockorager/vaxis"
)

func main() {
	// Open our image
	f, err := os.Open("/home/rockorager/pic.png")
	if err != nil {
		panic(err)
	}
	// Decode into an image.Image
	img, err := png.Decode(f)
	if err != nil {
		panic(err)
	}
	vx, err := vaxis.New(vaxis.Options{})
	if err != nil {
		panic(err)
	}
	// Create a graphic with Vaxis. Depending on the terminal, this will
	// either send the graphic to the terminal or create a sixel encoded
	// version of the image
	vimg, err := vx.NewImage(img)
	if err != nil {
		panic(err)
	}
	// Resize to whatever size we want, in cell values
	w := 20
	h := 10
	vimg.Resize(w, h)
	// Create a window. The window should fully contain the image
	win := vx.Window().New(0, 0, w, h)
	// Draw the graphic in the window
	vimg.Draw(win)
	vx.Render()
}

Output:

type Key 

type Key struct {
	// Text is text that the keypress generated
	Text string
	// Keycode is our primary key press. In alternate layouts, this will be
	// the lowercase value of the unicode point
	Keycode rune
	// The shifted keycode of this key event. This will only be non-zero if
	// the shift-modifier was used to generate the event
	ShiftedCode rune
	// BaseLayoutCode is the keycode that would have been generated on a
	// standard PC-101 layout
	BaseLayoutCode rune
	// Modifiers are any key modifier used to generate the event
	Modifiers ModifierMask
	// EventType is the type of key event this was (press, release, repeat,
	// or paste)
	EventType EventType
}

Key is a key event. Codepoint can be either the literal codepoint of the keypress, or a value set by Vaxis to indicate special keys. Special keys have their codepoints outside of the valid unicode range

Example 
package main

import (
	"git.sr.ht/~rockorager/vaxis"
)

func main() {
	vx, _ := vaxis.New(vaxis.Options{})
	msg := vx.PollEvent()
	switch msg := msg.(type) {
	case vaxis.Key:
		switch msg.String() {
		case "Ctrl+c":
			vx.Close()
		case "Ctrl+l":
			vx.Refresh()
		case "j":
			// Down?
		default:
			// handle the key
		}
	}
}

Output:

func (Key) MatchString added in v0.5.0 

func (k Key) MatchString(tgt string) bool

MatchString parses a string and matches to the Key event. The syntax for strings is: <modifier>[+<modifer>]+<key>. For example: 

Ctrl+p
Shift+Alt+Up

All modifiers will be matched lowercase

func (Key) Matches added in v0.4.7 

func (k Key) Matches(key rune, modifiers ...ModifierMask) bool

Matches returns true if there is any way for the passed key and mods to match the Key. Before matching, ModCapsLock and ModNumLock are removed from the modifier mask. Returns true if any of the following are true

1. Keycode and Modifiers are exact matches 2. Text and Modifiers are exact matches 3. ShiftedCode and Modifiers (with ModShift removed) are exact matches 4. BaseLayoutCode and Modifiers are exact matches

If key is not a letter, but still a graphic: (so we can match ':', which is shift+; but we don't want to match "shift+tab" as the same as "tab")

5. Keycode and Modifers (without ModShift) are exact matches 6. Shifted Keycode and Modifers (without ModShift) are exact matches

If key is lowercase or not a letter and mods includes ModShift, uppercase Key, remove ModShift and continue

6. Text and Modifiers are exact matches

func (Key) String 

func (k Key) String() string

String returns a human-readable description of the keypress, suitable for use in matching ("Ctrl+c")

type KittyImage added in v0.3.0 

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

func (*KittyImage) CellSize added in v0.3.0 

func (k *KittyImage) CellSize() (w int, h int)

func (*KittyImage) Destroy added in v0.3.0 

func (k *KittyImage) Destroy()

Destroy deletes this image from memory

func (*KittyImage) Draw added in v0.3.0 

func (k *KittyImage) Draw(win Window)

Draw draws the Image to the Window.

func (*KittyImage) Resize added in v0.3.0 

func (k *KittyImage) Resize(w int, h int)

Resizes the image to fit within the wxh area. The image will not be upscaled, nor will it's aspect ratio be changed. Resizing will be done in a separate goroutine. A Redraw event will be posted when complete

type ModifierMask 

type ModifierMask int

ModifierMask is a bitmask for which modifier keys were held when a key was pressed 

const (
	// Values equivalent to kitty keyboard protocol
	ModShift ModifierMask = 1 << iota
	ModAlt
	ModCtrl
	ModSuper
	ModHyper
	ModMeta
	ModCapsLock
	ModNumLock
)

type Mouse 

type Mouse struct {
	Button    MouseButton
	Row       int
	Col       int
	EventType EventType
	Modifiers ModifierMask
}

Mouse is a mouse event

type MouseButton 

type MouseButton int

MouseButton represents a mouse button 

const (
	MouseLeftButton MouseButton = iota
	MouseMiddleButton
	MouseRightButton
	MouseNoButton

	MouseWheelUp   MouseButton = 64
	MouseWheelDown MouseButton = 65

	MouseButton8  MouseButton = 128
	MouseButton9  MouseButton = 129
	MouseButton10 MouseButton = 130
	MouseButton11 MouseButton = 131
)

type MouseShape 

type MouseShape string

MouseShape is used with OSC 22 to change the shape of the mouse cursor 

const (
	MouseShapeDefault          MouseShape = "default"
	MouseShapeTextInput        MouseShape = "text"
	MouseShapeClickable        MouseShape = "pointer"
	MouseShapeHelp             MouseShape = "help"
	MouseShapeBusyBackground   MouseShape = "progress"
	MouseShapeBusy             MouseShape = "wait"
	MouseShapeResizeHorizontal MouseShape = "ew-resize"
	MouseShapeResizeVertical   MouseShape = "ns-resize"
	// The thick plus sign cursor that's typically used in spread-sheet applications to select cells.
	MouseShapeCell MouseShape = "cell"
)

type Options 

type Options struct {
	// DisableKittyKeyboard disables the use of the Kitty Keyboard protocol.
	// By default, if support is detected the protocol will be used.
	DisableKittyKeyboard bool
	// Deprecated Use CSIuBitMask instead
	//
	// ReportKeyboardEvents will report key release and key repeat events if
	// KittyKeyboardProtocol is enabled and supported by the terminal
	ReportKeyboardEvents bool
	// The size of the event queue channel. This will default to 1024 to
	// prevent any blocking on writes.
	EventQueueSize int
	// Disable mouse events
	DisableMouse bool
	// WithTTY passes an absolute path to use for the TTY Vaxis will draw
	// on. If the file is not a TTY, an error will be returned when calling
	// New
	WithTTY string
	// NoSignals causes Vaxis to not install any signal handlers
	NoSignals bool

	// CSIuBitMask is the bit mask to use for CSIu key encoding, when
	// available. This has no effect if DisableKittyKeyboard is true
	CSIuBitMask CSIuBitMask
}

Options are the runtime options which must be supplied to a new Vaxis object at instantiation

type PasteEndEvent 

type PasteEndEvent struct{}

PasteEndEvent is sent at the end of a bracketed paste. Each Key within the paste will also have the EventPaste set as the EventType

type PasteStartEvent 

type PasteStartEvent struct{}

PasteStartEvent is sent at the beginning of a bracketed paste. Each Key within the paste will also have the EventPaste set as the EventType

type QuitEvent 

type QuitEvent struct{}

QuitEvent is sent when the application is closing. It is emitted when the application calls vaxis.Close, and often times won't be seen by the application.

type Redraw 

type Redraw struct{}

Redraw is a generic event which can be sent to the host application to tell it some update has occurred it may not know about otherwise and it must redraw. These are always issued after a SyncFunc has been called

type Resize 

type Resize struct {
	Cols   int
	Rows   int
	XPixel int
	YPixel int
}

Resize is delivered whenever a window size change is detected (likely via SIGWINCH)

type Segment 

type Segment struct {
	// Text is the value of the text segment
	Text  string
	Style Style
}

Segment represents text segment

type Sixel added in v0.3.0 

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

func (*Sixel) CellSize added in v0.3.0 

func (s *Sixel) CellSize() (w int, h int)

CellSize is the current cell size of the encoded image

func (*Sixel) Destroy added in v0.3.0 

func (s *Sixel) Destroy()

Destroy removes an image from memory. Call when done with this image

func (*Sixel) Draw added in v0.3.0 

func (s *Sixel) Draw(win Window)

Draw draws the Image to the Window. The image will not be drawn if it is larger than the window

func (*Sixel) Resize added in v0.3.0 

func (s *Sixel) Resize(w int, h int)

Resizes the image to fit within the wxh area. The image will not be upscaled, nor will it's aspect ratio be changed. Resize will be done in a separate gorotuine. A Redraw event will be posted when complete

type Style 

type Style struct {
	// Hyperlink is used for adding OSC 8 information to the cell or
	// segment.
	Hyperlink string
	// HyperlinkParams is passed as the param string for OSC 8 sequences.
	// Typically this will be something like "id=<some-id>" to signal
	// non-contiguous links which are the same (IE when a link may be
	// wrapped on lines)
	HyperlinkParams string
	// Foreground is the color to apply to the foreground of this cell
	Foreground Color
	// Background is the color to apply to the background of this cell
	Background Color
	// UnderlineColor is the color to apply to the underline of this cell,
	// if supported
	UnderlineColor Color
	// UnderlineStyle is the type of underline to apply (single, double,
	// curly, etc). If a particular style is not supported, Vaxis will
	// fallback to single underlines
	UnderlineStyle UnderlineStyle
	// Attribute represents all other style information for this cell (bold,
	// dim, italic, etc)
	Attribute AttributeMask
}

Style contains all the data required to style a Cell or Segment

type StyledString added in v0.7.0 

type StyledString struct {
	Cells []Cell
}

func (*StyledString) Encode added in v0.7.0 

func (ss *StyledString) Encode() string

func (*StyledString) Len added in v0.7.0 

func (ss *StyledString) Len() int

Returns the rendered width of the styled string

type SyncFunc added in v0.2.0 

type SyncFunc func()

SyncFunc is a function which will be called in the main thread. vaxis will call the function and send an empty SyncFunc event to the application to signal that something has been updated (probably the application needs to redraw itself)

type UnderlineStyle 

type UnderlineStyle uint8

UnderlineStyle represents the style of underline to apply 

const (
	UnderlineOff UnderlineStyle = iota
	UnderlineSingle
	UnderlineDouble
	UnderlineCurly
	UnderlineDotted
	UnderlineDashed
)

type Vaxis 

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

func New 

func New(opts Options) (*Vaxis, error)

New creates a new Vaxis instance. Calling New will query the underlying terminal for supported features and enter the alternate screen

func (*Vaxis) Bell 

func (vx *Vaxis) Bell()

Bell sends a BEL control signal to the terminal

func (*Vaxis) CanDisplayGraphics added in v0.1.2 

func (vx *Vaxis) CanDisplayGraphics() bool

func (*Vaxis) CanKittyGraphics added in v0.1.2 

func (vx *Vaxis) CanKittyGraphics() bool

func (*Vaxis) CanReportBackgroundColor added in v0.9.0 

func (vx *Vaxis) CanReportBackgroundColor() bool

func (*Vaxis) CanSetAppID added in v0.9.0 

func (vx *Vaxis) CanSetAppID() bool

func (*Vaxis) CanSixel added in v0.1.2 

func (vx *Vaxis) CanSixel() bool

func (*Vaxis) ClipboardPop 

func (vx *Vaxis) ClipboardPop(ctx context.Context) (string, error)

ClipboardPop requests the content from the system clipboard. ClipboardPop works by requesting the data from the underlying terminal, which responds back with the data. Depending on usage, this could take some time. Callers can provide a context to set a deadline for this function to return. An error will be returned if the context is cancelled.

func (*Vaxis) ClipboardPush 

func (vx *Vaxis) ClipboardPush(s string)

ClipboardPush copies the provided string to the system clipboard

func (*Vaxis) Close 

func (vx *Vaxis) Close()

Close shuts down the event loops and returns the terminal to it's original state

func (*Vaxis) CursorPosition 

func (vx *Vaxis) CursorPosition() (row int, col int)

Reports the current cursor position. 0,0 is the upper left corner. Reports -1,-1 if the query times out or fails

func (*Vaxis) Events 

func (vx *Vaxis) Events() chan Event

Events returns the channel of events.

func (*Vaxis) HideCursor 

func (vx *Vaxis) HideCursor()

HideCursor hides the hardware cursor

func (*Vaxis) NewFullBlockImage added in v0.3.0 

func (vx *Vaxis) NewFullBlockImage(img image.Image) *FullBlockImage

func (*Vaxis) NewHalfBlockImage added in v0.3.0 

func (vx *Vaxis) NewHalfBlockImage(img image.Image) *HalfBlockImage

func (*Vaxis) NewImage added in v0.3.0 

func (vx *Vaxis) NewImage(img image.Image) (Image, error)

NewImage creates a new image using the highest quality renderer the terminal is capable of

func (*Vaxis) NewKittyGraphic added in v0.3.0 

func (vx *Vaxis) NewKittyGraphic(img image.Image) *KittyImage

func (*Vaxis) NewSixel added in v0.3.0 

func (vx *Vaxis) NewSixel(img image.Image) *Sixel

func (*Vaxis) NewStyledString added in v0.7.0 

func (vx *Vaxis) NewStyledString(s string, defaultStyle Style) *StyledString

func (*Vaxis) Notify 

func (vx *Vaxis) Notify(title string, body string)

Notify (attempts) to send a system notification. If title is the empty string, OSC9 will be used - otherwise osc777 is used

func (*Vaxis) PollEvent 

func (vx *Vaxis) PollEvent() Event

PollEvent blocks until there is an Event, and returns that Event

func (*Vaxis) PostEvent 

func (vx *Vaxis) PostEvent(ev Event)

PostEvent inserts an event into the Vaxis event loop

func (*Vaxis) PostEventBlocking added in v0.10.2 

func (vx *Vaxis) PostEventBlocking(ev Event)

PostEventBlocking inserts an event into the Vaxis event loop. The call will block if the queue is full. This method should only be used from a different goroutine than the main thread.

func (*Vaxis) QueryBackground added in v0.9.0 

func (vx *Vaxis) QueryBackground() Color

QueryBackground queries the host terminal for background color and returns it as an instance of vaxis.Color. If the host terminal doesn't support this, Color(0) is returned instead. Make sure not to run this in the same goroutine as Vaxis runs in or deadlock will occur.

func (*Vaxis) Refresh 

func (vx *Vaxis) Refresh()

Refresh forces a full render of the entire screen. Traditionally, this should be bound to Ctrl+l

func (*Vaxis) Render 

func (vx *Vaxis) Render()

Render renders the model's content to the terminal

func (*Vaxis) RenderedWidth 

func (vx *Vaxis) RenderedWidth(s string) int

RenderedWidth returns the rendered width of the provided string. The result is dependent on if your terminal can support unicode properly.

This is best effort. It will usually be correct, and in the few cases it's wrong will end up wrong in the nicer-rendering way (complex emojis will have extra space after them. This is preferable to messing up the internal model)

This call can be expensive, callers should consider caching the result for strings or characters which will need to be measured frequently

func (*Vaxis) Resize added in v0.2.0 

func (vx *Vaxis) Resize()

Resize manually triggers a resize event. Normally, vaxis listens to SIGWINCH for resize events, however in some use cases a manual resize trigger may be needed

func (*Vaxis) Resume added in v0.1.2 

func (vx *Vaxis) Resume() error

Resume returns the application to it's fullscreen state, re-enters raw mode, and reenables input parsing. Upon resuming, a Resize event will be delivered. It is entirely possible the terminal was resized while suspended.

func (*Vaxis) SetAppID added in v0.9.0 

func (vx *Vaxis) SetAppID(s string)

SetAppID sets the terminal's application ID via OSC 176

func (*Vaxis) SetMouseShape 

func (vx *Vaxis) SetMouseShape(shape MouseShape)

SetMouseShape sets the shape of the mouse

func (*Vaxis) SetTitle 

func (vx *Vaxis) SetTitle(s string)

SetTitle sets the terminal's title via OSC 2

func (*Vaxis) ShowCursor 

func (vx *Vaxis) ShowCursor(col int, row int, style CursorStyle)

ShowCursor shows the cursor at the given colxrow, with the given style. The passed column and row are 0-indexed and global. To show the cursor relative to a window, use Window.ShowCursor

func (*Vaxis) Suspend added in v0.1.2 

func (vx *Vaxis) Suspend() error

Suspend takes Vaxis out of fullscreen state, disables all terminal modes, stops listening for signals, and returns the terminal to it's original state. Suspend can be useful to, for example, drop out of the full screen TUI and run another TUI. The state of vaxis will be retained, so you can reenter the original state by calling Resume

func (*Vaxis) SyncFunc 

func (vx *Vaxis) SyncFunc(fn func())

SyncFunc queues a function to be called from the main thread. vaxis will call the function when the event is received in the main thread either through PollEvent or Events. A Redraw event will be sent to the host application after the function is completed

func (*Vaxis) TerminalID added in v0.9.0 

func (vx *Vaxis) TerminalID() string

TerminalID returns the terminal name and version advertised by the terminal, if supported. The actual format is implementation-defined, but it is safe to assume that the ID will start with the terminal name. Some examples: "foot(1.17.2)"; "WezTerm 20210502-154244-3f7122cb"

func (*Vaxis) Window 

func (vx *Vaxis) Window() Window

Window returns a window the full size of the screen. Child windows can be created from the returned Window

type Window 

type Window struct {
	// Vx is a reference to the [Vx] instance
	Vx *Vaxis
	// Parent is a reference to a parent [Window], if nil then the offsets
	// and size will be relative to the underlying terminal window
	Parent *Window
	Column int // col offset from parent
	Row    int // row offset from parent
	Width  int // width of the surface, in cols
	Height int // height of the surface, in rows
}

Window is a Window with an offset from an optional parent and a specified size. A Window can be instantiated directly, however the provided constructor methods are recommended as they will enforce size constraints

func (Window) Clear 

func (win Window) Clear()

Clear fills the Window with spaces with the default colors and removes all graphics placements

func (Window) Fill 

func (win Window) Fill(cell Cell)

Fill completely fills the Window with the provided cell

func (Window) New 

func (win Window) New(col, row, cols, rows int) Window

New creates a new child Window with an offset relative to the parent window

func (Window) Origin 

func (win Window) Origin() (int, int)

returns the Origin of the window, column x row, 0-indexed

func (Window) Print 

func (win Window) Print(segs ...Segment) (col int, row int)

Print prints [Segment]s, with each block having a given style. Text will be wrapped, line breaks will begin a new line at the first column of the surface. If the text overflows the height of the surface then only the top portion will be shown

func (Window) PrintTruncate 

func (win Window) PrintTruncate(row int, segs ...Segment)

PrintTruncate prints a single line of text to the specified row. If the text is wider than the width of the window, the line will be truncated with "…": 

"This line has mo…"

If the row is outside the bounds of the window, nothing will be printed

func (Window) Println 

func (win Window) Println(row int, segs ...Segment)

Println prints a single line of text to the specified row. If the text is wider than the width of the window, the line will be truncated with "…": 

"This line has mo…"

If the row is outside the bounds of the window, nothing will be printed

func (Window) SetCell 

func (win Window) SetCell(col int, row int, cell Cell)

SetCell is used to place data at the given cell location. Note that since the Window doesn't retain this data, if the location is outside of the visible area, it is simply discarded.

func (Window) SetStyle added in v0.4.6 

func (win Window) SetStyle(col int, row int, style Style)

SetStyle changes the style at a given location, leaving the text in place.

func (Window) ShowCursor 

func (win Window) ShowCursor(col int, row int, style CursorStyle)

ShowCursor shows the cursor at colxrow, relative to this Window's location

func (Window) Size 

func (win Window) Size() (width int, height int)

Size returns the visible size of the Window in character cells.

func (Window) Wrap added in v0.7.0 

func (win Window) Wrap(segs ...Segment) (col int, row int)

Wrap uses unicode line break logic to wrap text. this is expensive, but has good results

Source Files

View all Source files

Directories

Path Synopsis
_examples
color_theme_updates
graphics
hello_world
mouse_shapes
notification
readme
spinner
term
textinput
wrap
cmd
vtwidth
vtwidth is a utility to measure the width of a string as it will be rendered in the terminal
 vtwidth is a utility to measure the width of a string as it will be rendered in the terminal
Package octreequant implements an image quantizer, for transforming bitmap images to palette images, before encoding them to SIXEL.
 Package octreequant implements an image quantizer, for transforming bitmap images to palette images, before encoding them to SIXEL.
widgets
align
border
pager
progress
scrollbar
spinner
term
textinput

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.