libghostty

package module
v0.0.0-...-b203652 Latest Latest
Warning

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

 Go to latest Published: May 5, 2026 License: MIT Imports: 8 Imported by: 0

README

Go Libghostty Bindings

Go bindings for libghostty-vt.

This project uses cgo but libghostty-vt only depends on libc, so it is very easy to static link and very easy to cross-compile. The bindings default to static linking for this reason.

[!WARNING]

I'm not promising any API stability yet. This is a new project and the API may change as necessary. The underlying functionality is very stable, but the Go API is still being designed.

Example

package main

import (
 "fmt"
 "log"

 "go.mitchellh.com/libghostty"
)

func main() {
 term, err := libghostty.NewTerminal(libghostty.WithSize(80, 24))
 if err != nil {
  log.Fatal(err)
 }
 defer term.Close()

 // Feed VT data — bold green "world", then plain text.
 fmt.Fprintf(term, "Hello, \033[1;32mworld\033[0m!\r\n")

 // Format the terminal contents as plain text.
 f, err := libghostty.NewFormatter(term,
  libghostty.WithFormatterFormat(libghostty.FormatterFormatPlain),
  libghostty.WithFormatterTrim(true),
 )
 if err != nil {
  log.Fatal(err)
 }
 defer f.Close()

 output, _ := f.FormatString()
 fmt.Println(output) // Hello, world!
}

More examples are in the examples/ directory.

Usage

Add the module to your Go project:

go get go.mitchellh.com/libghostty

This is a cgo package that links libghostty-vt via pkg-config. By default it links statically. Before building your project, you need the library installed. Either install it system-wide or set PKG_CONFIG_PATH to point to a local checkout:

export PKG_CONFIG_PATH=/path/to/libghostty-vt/share/pkgconfig

To link dynamically instead (requires the shared library at runtime, so you'll also need to set the library path):

go build -tags dynamic

See the Ghostty docs for building libghostty-vt from source.

Cross-Compilation

Because libghostty-vt only depends on libc, cross-compilation is straightforward using Zig as the C compiler. Zig is already required to build libghostty-vt, so no extra tooling is needed. You don't need to write any Zig code, we're just using Zig as a C/C++ compiler.

First, build libghostty-vt for your target (from the ghostty source tree):

zig build -Demit-lib-vt -Dtarget=x86_64-linux-gnu --prefix /tmp/ghostty-linux-amd64

Then cross-compile your Go project with zig cc:

CGO_ENABLED=1 \
GOOS=linux GOARCH=amd64 \
CC="zig cc -target x86_64-linux-gnu" \
CXX="zig c++ -target x86_64-linux-gnu" \
CGO_CFLAGS="-I/tmp/ghostty-linux-amd64/include -DGHOSTTY_STATIC" \
CGO_LDFLAGS="-L/tmp/ghostty-linux-amd64/lib -lghostty-vt" \
go build ./...

Supported targets include x86_64-linux-gnu, aarch64-linux-gnu, x86_64-macos, aarch64-macos, x86_64-windows-gnu, and aarch64-windows-gnu.

If you are using ghostty's CMake integration via FetchContent, the ghostty_vt_add_target() function handles the zig build for you:

FetchContent_MakeAvailable(ghostty)
ghostty_vt_add_target(NAME linux-amd64 ZIG_TARGET x86_64-linux-gnu)

See the ghostty CMakeLists.txt for full documentation of ghostty_vt_add_target().

Development

CMake fetches and builds libghostty-vt automatically. CMake is only required and used for development of this module. For actual downstream usage, you can get libghostty-vt available however you like (e.g. system package, local checkout, etc.).

You need Zig and CMake on your PATH.

make build
make test

# If in a Nix dev shell:
go build
go test

If you use the Nix dev shell (nix develop), go build and go test work directly — the shell configures all paths automatically.

Documentation

Overview

Package libghostty provides Go bindings for libghostty-vt, a virtual terminal emulator library from the Ghostty project.

Getting Started

Create a terminal with NewTerminal, feed it input with Terminal.VTWrite (or Terminal.Write for an io.Writer), and inspect state through data getters such as Terminal.CursorX, Terminal.Title, and Terminal.ActiveScreen. When finished, call Terminal.Close to release resources. 

term, err := libghostty.NewTerminal(
	libghostty.WithSize(80, 24),
	libghostty.WithMaxScrollback(1000),
)
if err != nil {
	log.Fatal(err)
}
defer term.Close()

term.VTWrite([]byte("Hello, world!\r\n"))

Concurrency

Unless documented otherwise, exported handle types in this package are not safe for concurrent use. Keep each Terminal, Formatter, KeyEncoder, MouseEncoder, KeyEvent, MouseEvent, and borrowed view confined to one goroutine at a time or protect it with your own synchronization.

RenderState is the main exception. Hold exclusive access to the terminal while calling RenderState.Update. After Update returns, the render state can be read without touching the terminal until the next Update. Do not call Update concurrently with reads from the same render state.

Borrowed views such as GridRef, KittyGraphics, KittyGraphicsImage, and Selection, plus raw pixel slices returned by Kitty graphics accessors, are only valid until the next mutating terminal call. Read and copy what you need before mutating the terminal again.

Plain copied values such as Cell, Row, Style, ColorRGB, and Palette are regular Go values and may be retained after the call that produced them.

Effects

The terminal communicates side-effects back to the host through effect callbacks. Register them at creation time with functional options like WithWritePty, WithBell, and WithEnquiry, or on a live terminal with Terminal.SetEffectWritePty and friends.

Effect callbacks run synchronously during Terminal.VTWrite. They must not call Terminal.VTWrite on the same terminal and should avoid blocking for long periods.

WithWritePty is the most common effect — it delivers data that the terminal wants to send back to the pty (e.g. query responses): 

term, _ := libghostty.NewTerminal(
	libghostty.WithSize(80, 24),
	libghostty.WithWritePty(func(_ *libghostty.Terminal, data []byte) {
		os.Stdout.Write(data)
	}),
)

Terminal Options

Terminal properties can be changed after creation with setter methods such as Terminal.SetColorForeground, Terminal.SetColorBackground, Terminal.SetColorPalette, Terminal.SetTitle, and Terminal.SetPwd.

Linking

This is a cgo package. By default it links the shared library via pkg-config. Build with "-tags static" to link statically instead.

Index

Constants

View Source 
const (
	ColorNamedBlack         = C.GHOSTTY_COLOR_NAMED_BLACK
	ColorNamedRed           = C.GHOSTTY_COLOR_NAMED_RED
	ColorNamedGreen         = C.GHOSTTY_COLOR_NAMED_GREEN
	ColorNamedYellow        = C.GHOSTTY_COLOR_NAMED_YELLOW
	ColorNamedBlue          = C.GHOSTTY_COLOR_NAMED_BLUE
	ColorNamedMagenta       = C.GHOSTTY_COLOR_NAMED_MAGENTA
	ColorNamedCyan          = C.GHOSTTY_COLOR_NAMED_CYAN
	ColorNamedWhite         = C.GHOSTTY_COLOR_NAMED_WHITE
	ColorNamedBrightBlack   = C.GHOSTTY_COLOR_NAMED_BRIGHT_BLACK
	ColorNamedBrightRed     = C.GHOSTTY_COLOR_NAMED_BRIGHT_RED
	ColorNamedBrightGreen   = C.GHOSTTY_COLOR_NAMED_BRIGHT_GREEN
	ColorNamedBrightYellow  = C.GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW
	ColorNamedBrightBlue    = C.GHOSTTY_COLOR_NAMED_BRIGHT_BLUE
	ColorNamedBrightMagenta = C.GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA
	ColorNamedBrightCyan    = C.GHOSTTY_COLOR_NAMED_BRIGHT_CYAN
	ColorNamedBrightWhite   = C.GHOSTTY_COLOR_NAMED_BRIGHT_WHITE
)

Named color palette indices. C: GHOSTTY_COLOR_NAMED_*

View Source 
const (
	DAConformanceVT100  = C.GHOSTTY_DA_CONFORMANCE_VT100
	DAConformanceVT101  = C.GHOSTTY_DA_CONFORMANCE_VT101
	DAConformanceVT102  = C.GHOSTTY_DA_CONFORMANCE_VT102
	DAConformanceVT125  = C.GHOSTTY_DA_CONFORMANCE_VT125
	DAConformanceVT131  = C.GHOSTTY_DA_CONFORMANCE_VT131
	DAConformanceVT132  = C.GHOSTTY_DA_CONFORMANCE_VT132
	DAConformanceVT220  = C.GHOSTTY_DA_CONFORMANCE_VT220
	DAConformanceVT240  = C.GHOSTTY_DA_CONFORMANCE_VT240
	DAConformanceVT320  = C.GHOSTTY_DA_CONFORMANCE_VT320
	DAConformanceVT340  = C.GHOSTTY_DA_CONFORMANCE_VT340
	DAConformanceVT420  = C.GHOSTTY_DA_CONFORMANCE_VT420
	DAConformanceVT510  = C.GHOSTTY_DA_CONFORMANCE_VT510
	DAConformanceVT520  = C.GHOSTTY_DA_CONFORMANCE_VT520
	DAConformanceVT525  = C.GHOSTTY_DA_CONFORMANCE_VT525
	DAConformanceLevel2 = C.GHOSTTY_DA_CONFORMANCE_LEVEL_2
	DAConformanceLevel3 = C.GHOSTTY_DA_CONFORMANCE_LEVEL_3
	DAConformanceLevel4 = C.GHOSTTY_DA_CONFORMANCE_LEVEL_4
	DAConformanceLevel5 = C.GHOSTTY_DA_CONFORMANCE_LEVEL_5
)

DA1 conformance levels (Pp parameter). C: GHOSTTY_DA_CONFORMANCE_*

View Source 
const (
	DAFeatureColumns132          = C.GHOSTTY_DA_FEATURE_COLUMNS_132
	DAFeaturePrinter             = C.GHOSTTY_DA_FEATURE_PRINTER
	DAFeatureReGIS               = C.GHOSTTY_DA_FEATURE_REGIS
	DAFeatureSixel               = C.GHOSTTY_DA_FEATURE_SIXEL
	DAFeatureSelectiveErase      = C.GHOSTTY_DA_FEATURE_SELECTIVE_ERASE
	DAFeatureUserDefinedKeys     = C.GHOSTTY_DA_FEATURE_USER_DEFINED_KEYS
	DAFeatureNationalReplacement = C.GHOSTTY_DA_FEATURE_NATIONAL_REPLACEMENT
	DAFeatureTechnicalCharacters = C.GHOSTTY_DA_FEATURE_TECHNICAL_CHARACTERS
	DAFeatureLocator             = C.GHOSTTY_DA_FEATURE_LOCATOR
	DAFeatureTerminalState       = C.GHOSTTY_DA_FEATURE_TERMINAL_STATE
	DAFeatureWindowing           = C.GHOSTTY_DA_FEATURE_WINDOWING
	DAFeatureHorizontalScrolling = C.GHOSTTY_DA_FEATURE_HORIZONTAL_SCROLLING
	DAFeatureANSIColor           = C.GHOSTTY_DA_FEATURE_ANSI_COLOR
	DAFeatureRectangularEditing  = C.GHOSTTY_DA_FEATURE_RECTANGULAR_EDITING
	DAFeatureANSITextLocator     = C.GHOSTTY_DA_FEATURE_ANSI_TEXT_LOCATOR
	DAFeatureClipboard           = C.GHOSTTY_DA_FEATURE_CLIPBOARD
)

DA1 feature codes (Ps parameters). C: GHOSTTY_DA_FEATURE_*

View Source 
const (
	DADeviceTypeVT100 = C.GHOSTTY_DA_DEVICE_TYPE_VT100
	DADeviceTypeVT220 = C.GHOSTTY_DA_DEVICE_TYPE_VT220
	DADeviceTypeVT240 = C.GHOSTTY_DA_DEVICE_TYPE_VT240
	DADeviceTypeVT330 = C.GHOSTTY_DA_DEVICE_TYPE_VT330
	DADeviceTypeVT340 = C.GHOSTTY_DA_DEVICE_TYPE_VT340
	DADeviceTypeVT320 = C.GHOSTTY_DA_DEVICE_TYPE_VT320
	DADeviceTypeVT382 = C.GHOSTTY_DA_DEVICE_TYPE_VT382
	DADeviceTypeVT420 = C.GHOSTTY_DA_DEVICE_TYPE_VT420
	DADeviceTypeVT510 = C.GHOSTTY_DA_DEVICE_TYPE_VT510
	DADeviceTypeVT520 = C.GHOSTTY_DA_DEVICE_TYPE_VT520
	DADeviceTypeVT525 = C.GHOSTTY_DA_DEVICE_TYPE_VT525
)

DA2 device type identifiers (Pp parameter). C: GHOSTTY_DA_DEVICE_TYPE_*

View Source 
const (
	UnderlineNone   = C.GHOSTTY_SGR_UNDERLINE_NONE
	UnderlineSingle = C.GHOSTTY_SGR_UNDERLINE_SINGLE
	UnderlineDouble = C.GHOSTTY_SGR_UNDERLINE_DOUBLE
	UnderlineCurly  = C.GHOSTTY_SGR_UNDERLINE_CURLY
	UnderlineDotted = C.GHOSTTY_SGR_UNDERLINE_DOTTED
	UnderlineDashed = C.GHOSTTY_SGR_UNDERLINE_DASHED
)

Underline style constants. C: GhosttySgrUnderline

View Source 
const PaletteSize = 256

PaletteSize is the number of entries in a terminal color palette.

Variables

View Source 
var (
	// ModeKAM is keyboard action mode (disable keyboard).
	ModeKAM = Mode(C.GHOSTTY_MODE_KAM)

	// ModeInsert is insert mode.
	ModeInsert = Mode(C.GHOSTTY_MODE_INSERT)

	// ModeSRM is send/receive mode.
	ModeSRM = Mode(C.GHOSTTY_MODE_SRM)

	// ModeLinefeed is linefeed/new line mode.
	ModeLinefeed = Mode(C.GHOSTTY_MODE_LINEFEED)
)

ANSI modes.

View Source 
var (
	// ModeDECCKM is cursor keys mode.
	ModeDECCKM = Mode(C.GHOSTTY_MODE_DECCKM)

	// Mode132Column is 132/80 column mode.
	Mode132Column = Mode(C.GHOSTTY_MODE_132_COLUMN)

	// ModeSlowScroll is slow scroll mode.
	ModeSlowScroll = Mode(C.GHOSTTY_MODE_SLOW_SCROLL)

	// ModeReverseColors is reverse video mode.
	ModeReverseColors = Mode(C.GHOSTTY_MODE_REVERSE_COLORS)

	// ModeOrigin is origin mode.
	ModeOrigin = Mode(C.GHOSTTY_MODE_ORIGIN)

	// ModeWraparound is auto-wrap mode.
	ModeWraparound = Mode(C.GHOSTTY_MODE_WRAPAROUND)

	// ModeAutorepeat is auto-repeat keys mode.
	ModeAutorepeat = Mode(C.GHOSTTY_MODE_AUTOREPEAT)

	// ModeX10Mouse is X10 mouse reporting mode.
	ModeX10Mouse = Mode(C.GHOSTTY_MODE_X10_MOUSE)

	// ModeCursorBlinking is cursor blink mode.
	ModeCursorBlinking = Mode(C.GHOSTTY_MODE_CURSOR_BLINKING)

	// ModeCursorVisible is cursor visible mode (DECTCEM).
	ModeCursorVisible = Mode(C.GHOSTTY_MODE_CURSOR_VISIBLE)

	// ModeEnableMode3 allows 132 column mode.
	ModeEnableMode3 = Mode(C.GHOSTTY_MODE_ENABLE_MODE_3)

	// ModeReverseWrap is reverse wrap mode.
	ModeReverseWrap = Mode(C.GHOSTTY_MODE_REVERSE_WRAP)

	// ModeAltScreenLegacy is alternate screen (legacy, mode 47).
	ModeAltScreenLegacy = Mode(C.GHOSTTY_MODE_ALT_SCREEN_LEGACY)

	// ModeKeypadKeys is application keypad mode.
	ModeKeypadKeys = Mode(C.GHOSTTY_MODE_KEYPAD_KEYS)

	// ModeLeftRightMargin is left/right margin mode.
	ModeLeftRightMargin = Mode(C.GHOSTTY_MODE_LEFT_RIGHT_MARGIN)

	// ModeNormalMouse is normal mouse tracking mode.
	ModeNormalMouse = Mode(C.GHOSTTY_MODE_NORMAL_MOUSE)

	// ModeButtonMouse is button-event mouse tracking mode.
	ModeButtonMouse = Mode(C.GHOSTTY_MODE_BUTTON_MOUSE)

	// ModeAnyMouse is any-event mouse tracking mode.
	ModeAnyMouse = Mode(C.GHOSTTY_MODE_ANY_MOUSE)

	// ModeFocusEvent enables focus in/out events.
	ModeFocusEvent = Mode(C.GHOSTTY_MODE_FOCUS_EVENT)

	// ModeUTF8Mouse is UTF-8 mouse format mode.
	ModeUTF8Mouse = Mode(C.GHOSTTY_MODE_UTF8_MOUSE)

	// ModeSGRMouse is SGR mouse format mode.
	ModeSGRMouse = Mode(C.GHOSTTY_MODE_SGR_MOUSE)

	// ModeAltScroll is alternate scroll mode.
	ModeAltScroll = Mode(C.GHOSTTY_MODE_ALT_SCROLL)

	// ModeURxvtMouse is URxvt mouse format mode.
	ModeURxvtMouse = Mode(C.GHOSTTY_MODE_URXVT_MOUSE)

	// ModeSGRPixelsMouse is SGR-Pixels mouse format mode.
	ModeSGRPixelsMouse = Mode(C.GHOSTTY_MODE_SGR_PIXELS_MOUSE)

	// ModeNumlockKeypad ignores keypad with NumLock.
	ModeNumlockKeypad = Mode(C.GHOSTTY_MODE_NUMLOCK_KEYPAD)

	// ModeAltEscPrefix makes Alt key send ESC prefix.
	ModeAltEscPrefix = Mode(C.GHOSTTY_MODE_ALT_ESC_PREFIX)

	// ModeAltSendsEsc makes Alt send escape.
	ModeAltSendsEsc = Mode(C.GHOSTTY_MODE_ALT_SENDS_ESC)

	// ModeReverseWrapExt is extended reverse wrap mode.
	ModeReverseWrapExt = Mode(C.GHOSTTY_MODE_REVERSE_WRAP_EXT)

	// ModeAltScreen is alternate screen mode (mode 1047).
	ModeAltScreen = Mode(C.GHOSTTY_MODE_ALT_SCREEN)

	// ModeSaveCursor saves cursor position (DECSC, mode 1048).
	ModeSaveCursor = Mode(C.GHOSTTY_MODE_SAVE_CURSOR)

	// ModeAltScreenSave is alt screen + save cursor + clear (mode 1049).
	ModeAltScreenSave = Mode(C.GHOSTTY_MODE_ALT_SCREEN_SAVE)

	// ModeBracketedPaste is bracketed paste mode.
	ModeBracketedPaste = Mode(C.GHOSTTY_MODE_BRACKETED_PASTE)

	// ModeSyncOutput is synchronized output mode.
	ModeSyncOutput = Mode(C.GHOSTTY_MODE_SYNC_OUTPUT)

	// ModeGraphemeCluster is grapheme cluster mode.
	ModeGraphemeCluster = Mode(C.GHOSTTY_MODE_GRAPHEME_CLUSTER)

	// ModeColorSchemeReport enables color scheme reporting.
	ModeColorSchemeReport = Mode(C.GHOSTTY_MODE_COLOR_SCHEME_REPORT)

	// ModeInBandResize enables in-band size reports.
	ModeInBandResize = Mode(C.GHOSTTY_MODE_IN_BAND_RESIZE)
)

DEC private modes.

Functions

func Alloc 

func Alloc(len uintptr) unsafe.Pointer

Alloc allocates len bytes through the default libghostty allocator (NULL allocator). Returns a pointer to the allocated memory or nil if the allocation failed.

The returned memory must be freed with Free using the same length. C: ghostty_alloc

func FocusEncode 

func FocusEncode(event FocusEvent) ([]byte, error)

FocusEncode encodes a focus event into a terminal escape sequence and returns the result as a byte slice.

func Free 

func Free(ptr unsafe.Pointer, len uintptr)

Free frees memory allocated by Alloc (or returned by a libghostty function) using the default libghostty allocator (NULL allocator). The len must match the original allocation size. It is safe to pass nil. C: ghostty_free

func PasteEncode 

func PasteEncode(data []byte, bracketed bool) ([]byte, error)

PasteEncode prepares data for writing to a terminal pty.

The encoder applies Ghostty's terminal-input paste rules: unsafe control bytes are replaced with spaces, bracketed paste markers are added when bracketed is true, and newlines become carriage returns when bracketed is false. The input slice is copied before calling into Ghostty because the C encoder mutates its data buffer in place.

func PasteIsSafe 

func PasteIsSafe(data []byte) bool

PasteIsSafe reports whether data is safe to paste into a terminal.

Ghostty's safety check is intentionally conservative: data containing newlines or bracketed-paste end markers is considered unsafe because it can inject commands into interactive programs. Empty data is safe.

func SysSetDecodePng 

func SysSetDecodePng(fn SysDecodePngFn) error

SysSetDecodePng installs a Go callback that decodes PNG image data into RGBA pixels. This enables PNG support in the Kitty Graphics Protocol. Pass nil to clear the callback and disable PNG decoding.

This function is not safe for concurrent use. Callers must ensure that decode configuration is not modified while terminals may process image data (e.g. configure at startup before creating terminals).

func SysSetLog 

func SysSetLog(fn SysLogFn) error

SysSetLog installs a Go callback that receives internal library log messages. Pass nil to clear the callback and discard log messages.

Which log levels are emitted depends on the build mode of the library. Debug builds emit all levels; release builds emit info and above.

This function is not safe for concurrent use. Callers must ensure that log configuration is not modified while log messages may be delivered (e.g. configure at startup before creating terminals).

func SysSetLogStderr 

func SysSetLogStderr() error

SysSetLogStderr installs the built-in stderr log callback provided by libghostty. Each message is formatted as "[level](scope): message\n" and written to stderr in a thread-safe manner.

This function is not safe for concurrent use. See SysSetLog.

Types

type BellFn 

type BellFn func(t *Terminal)

BellFn is called when the terminal receives a BEL character (0x07). The parameter is the terminal that triggered the effect. C: GhosttyTerminalBellFn

type BuildInfo 

type BuildInfo struct {
	// SIMD reports whether SIMD-accelerated code paths are enabled.
	SIMD bool

	// KittyGraphics reports whether Kitty graphics protocol support
	// is available.
	KittyGraphics bool

	// TmuxControlMode reports whether tmux control mode support
	// is available.
	TmuxControlMode bool

	// Optimize is the optimization mode the library was built with.
	Optimize OptimizeMode

	// VersionString is the full version string
	// (e.g. "1.2.3" or "1.2.3-dev+abcdef").
	VersionString string

	// VersionMajor is the major version number.
	VersionMajor uint

	// VersionMinor is the minor version number.
	VersionMinor uint

	// VersionPatch is the patch version number.
	VersionPatch uint

	// VersionBuild is the build metadata string (e.g. commit hash).
	// Empty if no build metadata is present.
	VersionBuild string
}

BuildInfo holds compile-time build configuration of libghostty-vt. All values are constant for the lifetime of the process. C: GhosttyBuildInfo (query enum)

func GetBuildInfo 

func GetBuildInfo() (BuildInfo, error)

GetBuildInfo queries all compile-time build configuration values and returns them in a single BuildInfo struct.

type Cell 

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

Cell is a wrapper around an opaque terminal grid cell value. Use getter methods to extract data from it. A Cell is a copied value snapshot, not a borrowed handle, so it may be retained after the GridRef or render-state iterator that produced it becomes invalid. C: GhosttyCell

func (*Cell) Codepoint 

func (c *Cell) Codepoint() (uint32, error)

Codepoint returns the codepoint of the cell (0 if empty).

func (*Cell) ColorPalette 

func (c *Cell) ColorPalette() (uint8, error)

ColorPalette returns the palette index for the cell's background color. Only valid when the cell's content tag is CellContentBgColorPalette.

func (*Cell) ColorRGB 

func (c *Cell) ColorRGB() (ColorRGB, error)

ColorRGB returns the RGB color for the cell's background color. Only valid when the cell's content tag is CellContentBgColorRGB.

func (*Cell) ContentTag 

func (c *Cell) ContentTag() (CellContentTag, error)

ContentTag returns the content tag describing what kind of content the cell holds.

func (*Cell) GetMulti 

func (c *Cell) GetMulti(keys []CellData, values []unsafe.Pointer) error

GetMulti queries multiple cell data fields in a single cgo call. This is a low-level function; prefer the typed getters (Codepoint, Wide, HasText, etc.) for normal use. GetMulti is useful when you need many fields at once and want to avoid per-field cgo overhead.

Each element in keys specifies a data kind, and the corresponding element in values must be an unsafe.Pointer to a variable whose type matches the "Output type" documented for that key in the upstream C header (ghostty/vt/screen.h, GhosttyCellData enum).

Example: 

var cp C.uint32_t
var wide C.GhosttyCellWide
err := cell.GetMulti(
	[]CellData{CellDataCodepoint, CellDataWide},
	[]unsafe.Pointer{unsafe.Pointer(&cp), unsafe.Pointer(&wide)},
)

C: ghostty_cell_get_multi 

func (c *Cell) HasHyperlink() (bool, error)

HasHyperlink reports whether the cell has a hyperlink.

func (*Cell) HasStyling 

func (c *Cell) HasStyling() (bool, error)

HasStyling reports whether the cell has non-default styling.

func (*Cell) HasText 

func (c *Cell) HasText() (bool, error)

HasText reports whether the cell has text to render.

func (*Cell) Protected 

func (c *Cell) Protected() (bool, error)

Protected reports whether the cell is protected.

func (*Cell) Semantic 

func (c *Cell) Semantic() (CellSemanticContent, error)

Semantic returns the semantic content type of the cell.

func (*Cell) StyleID 

func (c *Cell) StyleID() (uint16, error)

StyleID returns the style ID for the cell.

func (*Cell) Wide 

func (c *Cell) Wide() (CellWide, error)

Wide returns the wide property of the cell.

type CellContentTag 

type CellContentTag int

CellContentTag describes what kind of content a cell holds. C: GhosttyCellContentTag 

const (
	// CellContentCodepoint means a single codepoint (may be zero for empty).
	CellContentCodepoint CellContentTag = C.GHOSTTY_CELL_CONTENT_CODEPOINT

	// CellContentCodepointGrapheme means a codepoint that is part of a
	// multi-codepoint grapheme cluster.
	CellContentCodepointGrapheme CellContentTag = C.GHOSTTY_CELL_CONTENT_CODEPOINT_GRAPHEME

	// CellContentBgColorPalette means no text; background color from palette.
	CellContentBgColorPalette CellContentTag = C.GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE

	// CellContentBgColorRGB means no text; background color as RGB.
	CellContentBgColorRGB CellContentTag = C.GHOSTTY_CELL_CONTENT_BG_COLOR_RGB
)

type CellData 

type CellData int

CellData identifies a data field for cell queries. C: GhosttyCellData 

const (
	// CellDataInvalid is an invalid data type.
	CellDataInvalid CellData = C.GHOSTTY_CELL_DATA_INVALID

	// CellDataCodepoint is the codepoint of the cell (uint32_t).
	CellDataCodepoint CellData = C.GHOSTTY_CELL_DATA_CODEPOINT

	// CellDataContentTag is the content tag describing what kind of
	// content is in the cell (GhosttyCellContentTag).
	CellDataContentTag CellData = C.GHOSTTY_CELL_DATA_CONTENT_TAG

	// CellDataWide is the wide property of the cell (GhosttyCellWide).
	CellDataWide CellData = C.GHOSTTY_CELL_DATA_WIDE

	// CellDataHasText indicates whether the cell has text to render (bool).
	CellDataHasText CellData = C.GHOSTTY_CELL_DATA_HAS_TEXT

	// CellDataHasStyling indicates whether the cell has non-default
	// styling (bool).
	CellDataHasStyling CellData = C.GHOSTTY_CELL_DATA_HAS_STYLING

	// CellDataStyleID is the style ID for the cell (uint16_t).
	CellDataStyleID CellData = C.GHOSTTY_CELL_DATA_STYLE_ID

	// CellDataHasHyperlink indicates whether the cell has a hyperlink
	// (bool).
	CellDataHasHyperlink CellData = C.GHOSTTY_CELL_DATA_HAS_HYPERLINK

	// CellDataProtected indicates whether the cell is protected (bool).
	CellDataProtected CellData = C.GHOSTTY_CELL_DATA_PROTECTED

	// CellDataSemanticContent is the semantic content type of the cell
	// (GhosttyCellSemanticContent).
	CellDataSemanticContent CellData = C.GHOSTTY_CELL_DATA_SEMANTIC_CONTENT

	// CellDataColorPalette is the palette index for the cell's background
	// color (GhosttyColorPaletteIndex).
	CellDataColorPalette CellData = C.GHOSTTY_CELL_DATA_COLOR_PALETTE

	// CellDataColorRGBValue is the RGB value for the cell's background
	// color (GhosttyColorRgb).
	CellDataColorRGBValue CellData = C.GHOSTTY_CELL_DATA_COLOR_RGB
)

type CellSemanticContent 

type CellSemanticContent int

CellSemanticContent is the semantic content type of a cell, as set by OSC 133 sequences. C: GhosttyCellSemanticContent 

const (
	// CellSemanticOutput means regular output content (e.g. command output).
	CellSemanticOutput CellSemanticContent = C.GHOSTTY_CELL_SEMANTIC_OUTPUT

	// CellSemanticInput means content that is part of user input.
	CellSemanticInput CellSemanticContent = C.GHOSTTY_CELL_SEMANTIC_INPUT

	// CellSemanticPrompt means content that is part of a shell prompt.
	CellSemanticPrompt CellSemanticContent = C.GHOSTTY_CELL_SEMANTIC_PROMPT
)

type CellWide 

type CellWide int

CellWide describes the width behavior of a cell. C: GhosttyCellWide 

const (
	// CellWideNarrow means not a wide character, cell width 1.
	CellWideNarrow CellWide = C.GHOSTTY_CELL_WIDE_NARROW

	// CellWideWide means wide character, cell width 2.
	CellWideWide CellWide = C.GHOSTTY_CELL_WIDE_WIDE

	// CellWideSpacerTail means spacer after wide character (do not render).
	CellWideSpacerTail CellWide = C.GHOSTTY_CELL_WIDE_SPACER_TAIL

	// CellWideSpacerHead means spacer at end of soft-wrapped line for a
	// wide character.
	CellWideSpacerHead CellWide = C.GHOSTTY_CELL_WIDE_SPACER_HEAD
)

type ColorRGB 

type ColorRGB struct {
	R uint8
	G uint8
	B uint8
}

ColorRGB represents an RGB color value. C: GhosttyColorRgb

type ColorScheme 

type ColorScheme int

ColorScheme identifies the terminal color scheme (light or dark). C: GhosttyColorScheme 

const (
	// ColorSchemeLight indicates a light color scheme.
	ColorSchemeLight ColorScheme = C.GHOSTTY_COLOR_SCHEME_LIGHT

	// ColorSchemeDark indicates a dark color scheme.
	ColorSchemeDark ColorScheme = C.GHOSTTY_COLOR_SCHEME_DARK
)

type ColorSchemeFn 

type ColorSchemeFn func(t *Terminal) (ColorScheme, bool)

ColorSchemeFn is called for color scheme queries (CSI ? 996 n). The first parameter is the terminal that triggered the effect. Return the scheme and true, or zero value and false to ignore the query. C: GhosttyTerminalColorSchemeFn

type CursorVisualStyle 

type CursorVisualStyle int

CursorVisualStyle describes the visual style of the cursor. C: GhosttyRenderStateCursorVisualStyle 

const (
	// CursorVisualStyleBar is a bar cursor (DECSCUSR 5, 6).
	CursorVisualStyleBar CursorVisualStyle = C.GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR

	// CursorVisualStyleBlock is a block cursor (DECSCUSR 1, 2).
	CursorVisualStyleBlock CursorVisualStyle = C.GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK

	// CursorVisualStyleUnderline is an underline cursor (DECSCUSR 3, 4).
	CursorVisualStyleUnderline CursorVisualStyle = C.GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_UNDERLINE

	// CursorVisualStyleBlockHollow is a hollow block cursor.
	CursorVisualStyleBlockHollow CursorVisualStyle = C.GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW
)

type DeviceAttributes 

type DeviceAttributes struct {
	// Primary is the DA1 response data (CSI c).
	Primary DeviceAttributesPrimary

	// Secondary is the DA2 response data (CSI > c).
	Secondary DeviceAttributesSecondary

	// Tertiary is the DA3 response data (CSI = c).
	Tertiary DeviceAttributesTertiary
}

DeviceAttributes holds the response data for all three DA levels. The terminal fills whichever sub-struct matches the request type. C: GhosttyDeviceAttributes

type DeviceAttributesFn 

type DeviceAttributesFn func(t *Terminal) (DeviceAttributes, bool)

DeviceAttributesFn is called for device attributes queries (CSI c / CSI > c / CSI = c). The first parameter is the terminal that triggered the effect. Return the attributes and true, or zero value and false to ignore the query. C: GhosttyTerminalDeviceAttributesFn

type DeviceAttributesPrimary 

type DeviceAttributesPrimary struct {
	// ConformanceLevel is the Pp parameter. E.g. 62 for VT220.
	ConformanceLevel uint16

	// Features contains the DA1 feature codes (Ps parameters).
	// Only the first NumFeatures entries are valid.
	Features [64]uint16

	// NumFeatures is the number of valid entries in Features.
	NumFeatures int
}

DeviceAttributesPrimary holds primary device attributes (DA1). C: GhosttyDeviceAttributesPrimary

type DeviceAttributesSecondary 

type DeviceAttributesSecondary struct {
	// DeviceType is the terminal type identifier (Pp). E.g. 1 for VT220.
	DeviceType uint16

	// FirmwareVersion is the firmware/patch version number (Pv).
	FirmwareVersion uint16

	// ROMCartridge is the ROM cartridge registration number (Pc).
	// Always 0 for emulators.
	ROMCartridge uint16
}

DeviceAttributesSecondary holds secondary device attributes (DA2). C: GhosttyDeviceAttributesSecondary

type DeviceAttributesTertiary 

type DeviceAttributesTertiary struct {
	// UnitID is encoded as 8 uppercase hex digits in the response.
	UnitID uint32
}

DeviceAttributesTertiary holds tertiary device attributes (DA3). C: GhosttyDeviceAttributesTertiary

type EnquiryFn 

type EnquiryFn func(t *Terminal) []byte

EnquiryFn is called when the terminal receives ENQ (0x05). The first parameter is the terminal that triggered the effect. Return the response bytes; nil or empty means no response. C: GhosttyTerminalEnquiryFn

type Error 

type Error struct {
	Result Result
}

Error holds a non-success Ghostty result.

func (*Error) Error 

func (e *Error) Error() string

type FocusEvent 

type FocusEvent int

FocusEvent represents a focus gained or lost event for focus reporting mode (mode 1004).

C: GhosttyFocusEvent 

const (
	// FocusGained indicates the terminal window gained focus.
	FocusGained FocusEvent = C.GHOSTTY_FOCUS_GAINED

	// FocusLost indicates the terminal window lost focus.
	FocusLost FocusEvent = C.GHOSTTY_FOCUS_LOST
)

func ParseFocusEvent 

func ParseFocusEvent(s string) (FocusEvent, error)

ParseFocusEvent returns the FocusEvent value for the given name ("gained" or "lost"). Returns an error if the name is not recognized.

func (FocusEvent) MarshalText 

func (f FocusEvent) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. The output is the same as String() so the type integrates with encoding/json and other text-based encoders.

func (FocusEvent) String 

func (f FocusEvent) String() string

String returns a human-friendly name for the focus event: "gained" or "lost". Unknown values render as "unknown".

func (*FocusEvent) UnmarshalText 

func (f *FocusEvent) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It parses a focus event name ("gained" or "lost") and stores the corresponding FocusEvent value in the receiver. Returns an error if the name is not recognized.

type Formatter 

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

Formatter wraps a Ghostty formatter handle that can produce plain text, VT sequences, or HTML from a terminal's current state. The formatter stores a borrowed reference to a terminal, so the terminal must outlive the formatter and formatter calls must be serialized with all other access to that terminal.

Formatter implements io.WriterTo so formatted output can be written directly to any io.Writer. C: GhosttyFormatter

func NewFormatter 

func NewFormatter(t *Terminal, opts ...FormatterOption) (*Formatter, error)

NewFormatter creates a formatter for the given terminal's active screen. The terminal must outlive the formatter. The formatter captures a borrowed reference to the terminal and reads its current state on each Formatter.Format call, so formatter calls must be serialized with other access to the terminal.

func (*Formatter) Close 

func (f *Formatter) Close()

Close frees the formatter handle. After this call, the formatter must not be used.

func (*Formatter) Format 

func (f *Formatter) Format() ([]byte, error)

Format runs the formatter and returns the output as a byte slice. Each call reflects the terminal's current state at the time of the call. Serialize Format with all other access to the underlying terminal. The returned buffer is allocated by libghostty and copied into Go memory.

func (*Formatter) FormatString 

func (f *Formatter) FormatString() (string, error)

FormatString runs the formatter and returns the output as a string. This is a convenience wrapper around Format.

func (*Formatter) WriteTo 

func (f *Formatter) WriteTo(w io.Writer) (int64, error)

WriteTo implements io.WriterTo. It formats the current terminal state and writes the entire output to w.

type FormatterFormat 

type FormatterFormat int

FormatterFormat selects the output format for a Formatter. C: GhosttyFormatterFormat 

const (
	// FormatterFormatPlain emits plain text (no escape sequences).
	FormatterFormatPlain FormatterFormat = C.GHOSTTY_FORMATTER_FORMAT_PLAIN

	// FormatterFormatVT emits VT sequences preserving colors, styles, URLs, etc.
	FormatterFormatVT FormatterFormat = C.GHOSTTY_FORMATTER_FORMAT_VT

	// FormatterFormatHTML emits HTML with inline styles.
	FormatterFormatHTML FormatterFormat = C.GHOSTTY_FORMATTER_FORMAT_HTML
)

type FormatterOption 

type FormatterOption func(*formatterOpts)

FormatterOption is a functional option for configuring a Formatter.

func WithFormatterExtraCharsets 

func WithFormatterExtraCharsets(v bool) FormatterOption

WithFormatterExtraCharsets emits character set designations and invocations.

func WithFormatterExtraCursor 

func WithFormatterExtraCursor(v bool) FormatterOption

WithFormatterExtraCursor emits cursor position using CUP (CSI H). 

func WithFormatterExtraHyperlink(v bool) FormatterOption

WithFormatterExtraHyperlink emits current hyperlink state using OSC 8 sequences.

func WithFormatterExtraKeyboard 

func WithFormatterExtraKeyboard(v bool) FormatterOption

WithFormatterExtraKeyboard emits keyboard modes such as ModifyOtherKeys.

func WithFormatterExtraKittyKeyboard 

func WithFormatterExtraKittyKeyboard(v bool) FormatterOption

WithFormatterExtraKittyKeyboard emits Kitty keyboard protocol state using CSI > u and CSI = sequences.

func WithFormatterExtraModes 

func WithFormatterExtraModes(v bool) FormatterOption

WithFormatterExtraModes emits terminal modes that differ from their defaults using CSI h/l.

func WithFormatterExtraPalette 

func WithFormatterExtraPalette(v bool) FormatterOption

WithFormatterExtraPalette emits the palette using OSC 4 sequences.

func WithFormatterExtraProtection 

func WithFormatterExtraProtection(v bool) FormatterOption

WithFormatterExtraProtection emits character protection mode using DECSCA.

func WithFormatterExtraPwd 

func WithFormatterExtraPwd(v bool) FormatterOption

WithFormatterExtraPwd emits the present working directory using OSC 7.

func WithFormatterExtraScrollingRegion 

func WithFormatterExtraScrollingRegion(v bool) FormatterOption

WithFormatterExtraScrollingRegion emits scrolling region state using DECSTBM and DECSLRM sequences.

func WithFormatterExtraStyle 

func WithFormatterExtraStyle(v bool) FormatterOption

WithFormatterExtraStyle emits current SGR style state based on the cursor's active style_id.

func WithFormatterExtraTabstops 

func WithFormatterExtraTabstops(v bool) FormatterOption

WithFormatterExtraTabstops emits tabstop positions by clearing all tabs and setting each one.

func WithFormatterFormat 

func WithFormatterFormat(f FormatterFormat) FormatterOption

WithFormatterFormat sets the output format (plain, VT, or HTML). Defaults to FormatterFormatPlain if not specified.

func WithFormatterTrim 

func WithFormatterTrim(trim bool) FormatterOption

WithFormatterTrim enables trimming of trailing whitespace on non-blank lines.

func WithFormatterUnwrap 

func WithFormatterUnwrap(unwrap bool) FormatterOption

WithFormatterUnwrap enables unwrapping of soft-wrapped lines.

type GridRef 

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

GridRef is a resolved reference to a specific cell position in the terminal's internal page structure. Obtain a GridRef from Terminal.GridRef, then extract cell or row data from it.

A GridRef is a borrowed view into terminal internals, so callers must use it under the same serialized access that protects the owning terminal. Any later terminal operation may invalidate the GridRef, even if it looks unrelated, so read and cache what you need immediately. Values returned by its getter methods are copied snapshots and may be retained after the GridRef itself becomes invalid. C: GhosttyGridRef

func (*GridRef) Cell 

func (g *GridRef) Cell() (*Cell, error)

Cell returns the cell at the grid reference's position.

func (*GridRef) Graphemes 

func (g *GridRef) Graphemes() ([]uint32, error)

Graphemes returns the full grapheme cluster codepoints for the cell at the grid reference's position. Returns nil if the cell has no text.

func (*GridRef) Row 

func (g *GridRef) Row() (*Row, error)

Row returns the row at the grid reference's position.

func (*GridRef) Style 

func (g *GridRef) Style() (*Style, error)

Style returns the style of the cell at the grid reference's position.

type Key 

type Key int

Key represents a physical key code. These are layout-independent and based on the W3C UI Events KeyboardEvent code standard.

C: GhosttyKey 

const (
	KeyUnidentified  Key = C.GHOSTTY_KEY_UNIDENTIFIED
	KeyBackquote     Key = C.GHOSTTY_KEY_BACKQUOTE
	KeyBackslash     Key = C.GHOSTTY_KEY_BACKSLASH
	KeyBracketLeft   Key = C.GHOSTTY_KEY_BRACKET_LEFT
	KeyBracketRight  Key = C.GHOSTTY_KEY_BRACKET_RIGHT
	KeyComma         Key = C.GHOSTTY_KEY_COMMA
	KeyDigit0        Key = C.GHOSTTY_KEY_DIGIT_0
	KeyDigit1        Key = C.GHOSTTY_KEY_DIGIT_1
	KeyDigit2        Key = C.GHOSTTY_KEY_DIGIT_2
	KeyDigit3        Key = C.GHOSTTY_KEY_DIGIT_3
	KeyDigit4        Key = C.GHOSTTY_KEY_DIGIT_4
	KeyDigit5        Key = C.GHOSTTY_KEY_DIGIT_5
	KeyDigit6        Key = C.GHOSTTY_KEY_DIGIT_6
	KeyDigit7        Key = C.GHOSTTY_KEY_DIGIT_7
	KeyDigit8        Key = C.GHOSTTY_KEY_DIGIT_8
	KeyDigit9        Key = C.GHOSTTY_KEY_DIGIT_9
	KeyEqual         Key = C.GHOSTTY_KEY_EQUAL
	KeyIntlBackslash Key = C.GHOSTTY_KEY_INTL_BACKSLASH
	KeyIntlRo        Key = C.GHOSTTY_KEY_INTL_RO
	KeyIntlYen       Key = C.GHOSTTY_KEY_INTL_YEN
	KeyA             Key = C.GHOSTTY_KEY_A
	KeyB             Key = C.GHOSTTY_KEY_B
	KeyC             Key = C.GHOSTTY_KEY_C
	KeyD             Key = C.GHOSTTY_KEY_D
	KeyE             Key = C.GHOSTTY_KEY_E
	KeyF             Key = C.GHOSTTY_KEY_F
	KeyG             Key = C.GHOSTTY_KEY_G
	KeyH             Key = C.GHOSTTY_KEY_H
	KeyI             Key = C.GHOSTTY_KEY_I
	KeyJ             Key = C.GHOSTTY_KEY_J
	KeyK             Key = C.GHOSTTY_KEY_K
	KeyL             Key = C.GHOSTTY_KEY_L
	KeyM             Key = C.GHOSTTY_KEY_M
	KeyN             Key = C.GHOSTTY_KEY_N
	KeyO             Key = C.GHOSTTY_KEY_O
	KeyP             Key = C.GHOSTTY_KEY_P
	KeyQ             Key = C.GHOSTTY_KEY_Q
	KeyR             Key = C.GHOSTTY_KEY_R
	KeyS             Key = C.GHOSTTY_KEY_S
	KeyT             Key = C.GHOSTTY_KEY_T
	KeyU             Key = C.GHOSTTY_KEY_U
	KeyV             Key = C.GHOSTTY_KEY_V
	KeyW             Key = C.GHOSTTY_KEY_W
	KeyX             Key = C.GHOSTTY_KEY_X
	KeyY             Key = C.GHOSTTY_KEY_Y
	KeyZ             Key = C.GHOSTTY_KEY_Z
	KeyMinus         Key = C.GHOSTTY_KEY_MINUS
	KeyPeriod        Key = C.GHOSTTY_KEY_PERIOD
	KeyQuote         Key = C.GHOSTTY_KEY_QUOTE
	KeySemicolon     Key = C.GHOSTTY_KEY_SEMICOLON
	KeySlash         Key = C.GHOSTTY_KEY_SLASH
)

Writing System Keys (W3C § 3.1.1) 

const (
	KeyAltLeft      Key = C.GHOSTTY_KEY_ALT_LEFT
	KeyAltRight     Key = C.GHOSTTY_KEY_ALT_RIGHT
	KeyBackspace    Key = C.GHOSTTY_KEY_BACKSPACE
	KeyCapsLock     Key = C.GHOSTTY_KEY_CAPS_LOCK
	KeyContextMenu  Key = C.GHOSTTY_KEY_CONTEXT_MENU
	KeyControlLeft  Key = C.GHOSTTY_KEY_CONTROL_LEFT
	KeyControlRight Key = C.GHOSTTY_KEY_CONTROL_RIGHT
	KeyEnter        Key = C.GHOSTTY_KEY_ENTER
	KeyMetaLeft     Key = C.GHOSTTY_KEY_META_LEFT
	KeyMetaRight    Key = C.GHOSTTY_KEY_META_RIGHT
	KeyShiftLeft    Key = C.GHOSTTY_KEY_SHIFT_LEFT
	KeyShiftRight   Key = C.GHOSTTY_KEY_SHIFT_RIGHT
	KeySpace        Key = C.GHOSTTY_KEY_SPACE
	KeyTab          Key = C.GHOSTTY_KEY_TAB
	KeyConvert      Key = C.GHOSTTY_KEY_CONVERT
	KeyKanaMode     Key = C.GHOSTTY_KEY_KANA_MODE
	KeyNonConvert   Key = C.GHOSTTY_KEY_NON_CONVERT
)

Functional Keys (W3C § 3.1.2) 

const (
	KeyDelete   Key = C.GHOSTTY_KEY_DELETE
	KeyEnd      Key = C.GHOSTTY_KEY_END
	KeyHelp     Key = C.GHOSTTY_KEY_HELP
	KeyHome     Key = C.GHOSTTY_KEY_HOME
	KeyInsert   Key = C.GHOSTTY_KEY_INSERT
	KeyPageDown Key = C.GHOSTTY_KEY_PAGE_DOWN
	KeyPageUp   Key = C.GHOSTTY_KEY_PAGE_UP
)

Control Pad Section (W3C § 3.2) 

const (
	KeyArrowDown  Key = C.GHOSTTY_KEY_ARROW_DOWN
	KeyArrowLeft  Key = C.GHOSTTY_KEY_ARROW_LEFT
	KeyArrowRight Key = C.GHOSTTY_KEY_ARROW_RIGHT
	KeyArrowUp    Key = C.GHOSTTY_KEY_ARROW_UP
)

Arrow Pad Section (W3C § 3.3) 

const (
	KeyNumLock            Key = C.GHOSTTY_KEY_NUM_LOCK
	KeyNumpad0            Key = C.GHOSTTY_KEY_NUMPAD_0
	KeyNumpad1            Key = C.GHOSTTY_KEY_NUMPAD_1
	KeyNumpad2            Key = C.GHOSTTY_KEY_NUMPAD_2
	KeyNumpad3            Key = C.GHOSTTY_KEY_NUMPAD_3
	KeyNumpad4            Key = C.GHOSTTY_KEY_NUMPAD_4
	KeyNumpad5            Key = C.GHOSTTY_KEY_NUMPAD_5
	KeyNumpad6            Key = C.GHOSTTY_KEY_NUMPAD_6
	KeyNumpad7            Key = C.GHOSTTY_KEY_NUMPAD_7
	KeyNumpad8            Key = C.GHOSTTY_KEY_NUMPAD_8
	KeyNumpad9            Key = C.GHOSTTY_KEY_NUMPAD_9
	KeyNumpadAdd          Key = C.GHOSTTY_KEY_NUMPAD_ADD
	KeyNumpadBackspace    Key = C.GHOSTTY_KEY_NUMPAD_BACKSPACE
	KeyNumpadClear        Key = C.GHOSTTY_KEY_NUMPAD_CLEAR
	KeyNumpadClearEntry   Key = C.GHOSTTY_KEY_NUMPAD_CLEAR_ENTRY
	KeyNumpadComma        Key = C.GHOSTTY_KEY_NUMPAD_COMMA
	KeyNumpadDecimal      Key = C.GHOSTTY_KEY_NUMPAD_DECIMAL
	KeyNumpadDivide       Key = C.GHOSTTY_KEY_NUMPAD_DIVIDE
	KeyNumpadEnter        Key = C.GHOSTTY_KEY_NUMPAD_ENTER
	KeyNumpadEqual        Key = C.GHOSTTY_KEY_NUMPAD_EQUAL
	KeyNumpadMemoryAdd    Key = C.GHOSTTY_KEY_NUMPAD_MEMORY_ADD
	KeyNumpadMemoryClear  Key = C.GHOSTTY_KEY_NUMPAD_MEMORY_CLEAR
	KeyNumpadMemoryRecall Key = C.GHOSTTY_KEY_NUMPAD_MEMORY_RECALL
	KeyNumpadMemoryStore  Key = C.GHOSTTY_KEY_NUMPAD_MEMORY_STORE
	KeyNumpadMemorySub    Key = C.GHOSTTY_KEY_NUMPAD_MEMORY_SUBTRACT
	KeyNumpadMultiply     Key = C.GHOSTTY_KEY_NUMPAD_MULTIPLY
	KeyNumpadParenLeft    Key = C.GHOSTTY_KEY_NUMPAD_PAREN_LEFT
	KeyNumpadParenRight   Key = C.GHOSTTY_KEY_NUMPAD_PAREN_RIGHT
	KeyNumpadSubtract     Key = C.GHOSTTY_KEY_NUMPAD_SUBTRACT
	KeyNumpadSeparator    Key = C.GHOSTTY_KEY_NUMPAD_SEPARATOR
	KeyNumpadUp           Key = C.GHOSTTY_KEY_NUMPAD_UP
	KeyNumpadDown         Key = C.GHOSTTY_KEY_NUMPAD_DOWN
	KeyNumpadRight        Key = C.GHOSTTY_KEY_NUMPAD_RIGHT
	KeyNumpadLeft         Key = C.GHOSTTY_KEY_NUMPAD_LEFT
	KeyNumpadBegin        Key = C.GHOSTTY_KEY_NUMPAD_BEGIN
	KeyNumpadHome         Key = C.GHOSTTY_KEY_NUMPAD_HOME
	KeyNumpadEnd          Key = C.GHOSTTY_KEY_NUMPAD_END
	KeyNumpadInsert       Key = C.GHOSTTY_KEY_NUMPAD_INSERT
	KeyNumpadDelete       Key = C.GHOSTTY_KEY_NUMPAD_DELETE
	KeyNumpadPageUp       Key = C.GHOSTTY_KEY_NUMPAD_PAGE_UP
	KeyNumpadPageDown     Key = C.GHOSTTY_KEY_NUMPAD_PAGE_DOWN
)

Numpad Section (W3C § 3.4) 

const (
	KeyEscape      Key = C.GHOSTTY_KEY_ESCAPE
	KeyF1          Key = C.GHOSTTY_KEY_F1
	KeyF2          Key = C.GHOSTTY_KEY_F2
	KeyF3          Key = C.GHOSTTY_KEY_F3
	KeyF4          Key = C.GHOSTTY_KEY_F4
	KeyF5          Key = C.GHOSTTY_KEY_F5
	KeyF6          Key = C.GHOSTTY_KEY_F6
	KeyF7          Key = C.GHOSTTY_KEY_F7
	KeyF8          Key = C.GHOSTTY_KEY_F8
	KeyF9          Key = C.GHOSTTY_KEY_F9
	KeyF10         Key = C.GHOSTTY_KEY_F10
	KeyF11         Key = C.GHOSTTY_KEY_F11
	KeyF12         Key = C.GHOSTTY_KEY_F12
	KeyF13         Key = C.GHOSTTY_KEY_F13
	KeyF14         Key = C.GHOSTTY_KEY_F14
	KeyF15         Key = C.GHOSTTY_KEY_F15
	KeyF16         Key = C.GHOSTTY_KEY_F16
	KeyF17         Key = C.GHOSTTY_KEY_F17
	KeyF18         Key = C.GHOSTTY_KEY_F18
	KeyF19         Key = C.GHOSTTY_KEY_F19
	KeyF20         Key = C.GHOSTTY_KEY_F20
	KeyF21         Key = C.GHOSTTY_KEY_F21
	KeyF22         Key = C.GHOSTTY_KEY_F22
	KeyF23         Key = C.GHOSTTY_KEY_F23
	KeyF24         Key = C.GHOSTTY_KEY_F24
	KeyF25         Key = C.GHOSTTY_KEY_F25
	KeyFn          Key = C.GHOSTTY_KEY_FN
	KeyFnLock      Key = C.GHOSTTY_KEY_FN_LOCK
	KeyPrintScreen Key = C.GHOSTTY_KEY_PRINT_SCREEN
	KeyScrollLock  Key = C.GHOSTTY_KEY_SCROLL_LOCK
	KeyPause       Key = C.GHOSTTY_KEY_PAUSE
)

Function Section (W3C § 3.5) 

const (
	KeyBrowserBack        Key = C.GHOSTTY_KEY_BROWSER_BACK
	KeyBrowserFavorites   Key = C.GHOSTTY_KEY_BROWSER_FAVORITES
	KeyBrowserForward     Key = C.GHOSTTY_KEY_BROWSER_FORWARD
	KeyBrowserHome        Key = C.GHOSTTY_KEY_BROWSER_HOME
	KeyBrowserRefresh     Key = C.GHOSTTY_KEY_BROWSER_REFRESH
	KeyBrowserSearch      Key = C.GHOSTTY_KEY_BROWSER_SEARCH
	KeyBrowserStop        Key = C.GHOSTTY_KEY_BROWSER_STOP
	KeyEject              Key = C.GHOSTTY_KEY_EJECT
	KeyLaunchApp1         Key = C.GHOSTTY_KEY_LAUNCH_APP_1
	KeyLaunchApp2         Key = C.GHOSTTY_KEY_LAUNCH_APP_2
	KeyLaunchMail         Key = C.GHOSTTY_KEY_LAUNCH_MAIL
	KeyMediaPlayPause     Key = C.GHOSTTY_KEY_MEDIA_PLAY_PAUSE
	KeyMediaSelect        Key = C.GHOSTTY_KEY_MEDIA_SELECT
	KeyMediaStop          Key = C.GHOSTTY_KEY_MEDIA_STOP
	KeyMediaTrackNext     Key = C.GHOSTTY_KEY_MEDIA_TRACK_NEXT
	KeyMediaTrackPrevious Key = C.GHOSTTY_KEY_MEDIA_TRACK_PREVIOUS
	KeyPower              Key = C.GHOSTTY_KEY_POWER
	KeySleep              Key = C.GHOSTTY_KEY_SLEEP
	KeyAudioVolumeDown    Key = C.GHOSTTY_KEY_AUDIO_VOLUME_DOWN
	KeyAudioVolumeMute    Key = C.GHOSTTY_KEY_AUDIO_VOLUME_MUTE
	KeyAudioVolumeUp      Key = C.GHOSTTY_KEY_AUDIO_VOLUME_UP
	KeyWakeUp             Key = C.GHOSTTY_KEY_WAKE_UP
)

Media Keys (W3C § 3.6) 

const (
	KeyCopy  Key = C.GHOSTTY_KEY_COPY
	KeyCut   Key = C.GHOSTTY_KEY_CUT
	KeyPaste Key = C.GHOSTTY_KEY_PASTE
)

Legacy, Non-standard, and Special Keys (W3C § 3.7)

func ParseKey 

func ParseKey(s string) (Key, error)

ParseKey returns the Key value for the given canonical snake_case key name (e.g. "key_a", "arrow_down"). Returns an error if the name is not recognized.

func (Key) MarshalText 

func (k Key) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. The output is the same as String() so the type integrates with encoding/json and other text-based encoders.

func (Key) String 

func (k Key) String() string

String returns the canonical snake_case name of the Key (e.g. "key_a", "arrow_down", "fn"). Returns "unidentified" for unknown values, mirroring the behavior of KeyUnidentified.

func (*Key) UnmarshalText 

func (k *Key) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It parses a canonical snake_case key name (e.g. "key_a", "arrow_down") and stores the corresponding Key value in the receiver. Returns an error if the name is not recognized.

type KeyAction 

type KeyAction int

KeyAction represents the type of keyboard input event (press, release, or repeat).

C: GhosttyKeyAction 

const (
	// KeyActionRelease indicates a key was released.
	KeyActionRelease KeyAction = C.GHOSTTY_KEY_ACTION_RELEASE

	// KeyActionPress indicates a key was pressed.
	KeyActionPress KeyAction = C.GHOSTTY_KEY_ACTION_PRESS

	// KeyActionRepeat indicates a key is being held down (repeat).
	KeyActionRepeat KeyAction = C.GHOSTTY_KEY_ACTION_REPEAT
)

type KeyEncoder 

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

KeyEncoder encodes key events into terminal escape sequences, supporting both legacy encoding and the Kitty Keyboard Protocol. It maintains mutable encoding options and is not safe for concurrent use.

Basic usage:

  1. Create an encoder with NewKeyEncoder.
  2. Configure options with SetOpt* methods or SetOptFromTerminal.
  3. Create key events, encode them with Encode, and free them.
  4. Free the encoder with Close when done.

C: GhosttyKeyEncoder

func NewKeyEncoder 

func NewKeyEncoder() (*KeyEncoder, error)

NewKeyEncoder creates a new key encoder with default options. The encoder must be freed with Close when no longer needed.

func (*KeyEncoder) Close 

func (enc *KeyEncoder) Close()

Close frees the underlying key encoder handle. After this call, the encoder must not be used.

func (*KeyEncoder) Encode 

func (enc *KeyEncoder) Encode(event *KeyEvent) ([]byte, error)

Encode encodes a key event into a terminal escape sequence and returns the result as a byte slice. Not all key events produce output (e.g. unmodified modifier keys); in that case, a nil slice and nil error are returned.

func (*KeyEncoder) SetOptBool 

func (enc *KeyEncoder) SetOptBool(opt KeyEncoderOption, val bool)

SetOptBool sets a boolean encoder option. Use this for options that accept a bool value (most encoder options).

func (*KeyEncoder) SetOptFromTerminal 

func (enc *KeyEncoder) SetOptFromTerminal(t *Terminal)

SetOptFromTerminal reads the terminal's current modes and flags and applies them to the encoder's options. This sets cursor key application mode, keypad mode, alt escape prefix, modifyOtherKeys state, and Kitty keyboard protocol flags from the terminal state.

Note that the macOS option-as-alt option cannot be determined from terminal state and is reset to OptionAsAltFalse by this call. Use SetOptOptionAsAlt afterward if needed. The caller must serialize access to both the encoder and the terminal during this call.

func (*KeyEncoder) SetOptKittyFlags 

func (enc *KeyEncoder) SetOptKittyFlags(flags KittyKeyFlags)

SetOptKittyFlags sets the Kitty keyboard protocol flags on the encoder.

func (*KeyEncoder) SetOptOptionAsAlt 

func (enc *KeyEncoder) SetOptOptionAsAlt(val OptionAsAlt)

SetOptOptionAsAlt sets the macOS option-as-alt behavior on the encoder.

type KeyEncoderOption 

type KeyEncoderOption int

KeyEncoderOption identifies an encoder configuration option for use with SetOpt.

C: GhosttyKeyEncoderOption 

const (
	// KeyEncoderOptCursorKeyApplication sets DEC mode 1: cursor key
	// application mode (value: bool).
	KeyEncoderOptCursorKeyApplication KeyEncoderOption = C.GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION

	// KeyEncoderOptKeypadKeyApplication sets DEC mode 66: keypad key
	// application mode (value: bool).
	KeyEncoderOptKeypadKeyApplication KeyEncoderOption = C.GHOSTTY_KEY_ENCODER_OPT_KEYPAD_KEY_APPLICATION

	// KeyEncoderOptIgnoreKeypadWithNumlock sets DEC mode 1035: ignore
	// keypad with numlock (value: bool).
	KeyEncoderOptIgnoreKeypadWithNumlock KeyEncoderOption = C.GHOSTTY_KEY_ENCODER_OPT_IGNORE_KEYPAD_WITH_NUMLOCK

	// KeyEncoderOptAltEscPrefix sets DEC mode 1036: alt sends escape
	// prefix (value: bool).
	KeyEncoderOptAltEscPrefix KeyEncoderOption = C.GHOSTTY_KEY_ENCODER_OPT_ALT_ESC_PREFIX

	// KeyEncoderOptModifyOtherKeysState2 sets xterm modifyOtherKeys
	// mode 2 (value: bool).
	KeyEncoderOptModifyOtherKeysState2 KeyEncoderOption = C.GHOSTTY_KEY_ENCODER_OPT_MODIFY_OTHER_KEYS_STATE_2

	// KeyEncoderOptKittyFlags sets Kitty keyboard protocol flags
	// (value: KittyKeyFlags bitmask).
	KeyEncoderOptKittyFlags KeyEncoderOption = C.GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS

	// KeyEncoderOptMacOSOptionAsAlt sets the macOS option-as-alt
	// setting (value: OptionAsAlt).
	KeyEncoderOptMacOSOptionAsAlt KeyEncoderOption = C.GHOSTTY_KEY_ENCODER_OPT_MACOS_OPTION_AS_ALT

	// KeyEncoderOptBackarrowKeyMode sets backarrow key mode (value: bool).
	// When false (default), backspace emits 0x7f; when true, 0x08.
	KeyEncoderOptBackarrowKeyMode KeyEncoderOption = C.GHOSTTY_KEY_ENCODER_OPT_BACKARROW_KEY_MODE
)

type KeyEvent 

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

KeyEvent is an opaque handle representing a keyboard input event containing information about the physical key pressed, modifiers, and generated text. It is mutable and reusable, but not safe for concurrent use.

C: GhosttyKeyEvent

func NewKeyEvent 

func NewKeyEvent() (*KeyEvent, error)

NewKeyEvent creates a new key event with default values. The event must be freed with Close when no longer needed.

func (*KeyEvent) Action 

func (e *KeyEvent) Action() KeyAction

Action returns the key action (press, release, repeat).

func (*KeyEvent) Close 

func (e *KeyEvent) Close()

Close frees the underlying key event handle. After this call, the key event must not be used.

func (*KeyEvent) Composing 

func (e *KeyEvent) Composing() bool

Composing reports whether the key event is part of a composition sequence.

func (*KeyEvent) ConsumedMods 

func (e *KeyEvent) ConsumedMods() Mods

ConsumedMods returns the consumed modifiers bitmask.

func (*KeyEvent) Key 

func (e *KeyEvent) Key() Key

Key returns the physical key code.

func (*KeyEvent) Mods 

func (e *KeyEvent) Mods() Mods

Mods returns the modifier keys bitmask.

func (*KeyEvent) SetAction 

func (e *KeyEvent) SetAction(action KeyAction)

SetAction sets the key action (press, release, repeat).

func (*KeyEvent) SetComposing 

func (e *KeyEvent) SetComposing(composing bool)

SetComposing sets whether the key event is part of a composition sequence.

func (*KeyEvent) SetConsumedMods 

func (e *KeyEvent) SetConsumedMods(mods Mods)

SetConsumedMods sets the consumed modifiers bitmask.

func (*KeyEvent) SetKey 

func (e *KeyEvent) SetKey(key Key)

SetKey sets the physical key code.

func (*KeyEvent) SetMods 

func (e *KeyEvent) SetMods(mods Mods)

SetMods sets the modifier keys bitmask.

func (*KeyEvent) SetUTF8 

func (e *KeyEvent) SetUTF8(s string)

SetUTF8 sets the UTF-8 text generated by the key for the current keyboard layout. Must contain the unmodified character before any Ctrl/Meta transformations. Do not pass C0 control characters or platform function key codes; pass an empty string instead and let the encoder use the logical key.

The string is not copied by the key event. The caller must ensure the string remains valid for the lifetime needed by the event.

func (*KeyEvent) SetUnshiftedCodepoint 

func (e *KeyEvent) SetUnshiftedCodepoint(cp rune)

SetUnshiftedCodepoint sets the unshifted Unicode codepoint.

func (*KeyEvent) UTF8 

func (e *KeyEvent) UTF8() string

UTF8 returns the UTF-8 text generated by the key event.

func (*KeyEvent) UnshiftedCodepoint 

func (e *KeyEvent) UnshiftedCodepoint() rune

UnshiftedCodepoint returns the unshifted Unicode codepoint.

type KittyGraphics 

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

KittyGraphics is a handle to the Kitty graphics image storage associated with a terminal's active screen. It is borrowed from the terminal and remains valid until the next mutating terminal call (for example Terminal.VTWrite or Terminal.Reset). Access to this handle must be serialized with mutations of the owning terminal.

C: GhosttyKittyGraphics

func (*KittyGraphics) Image 

func (kg *KittyGraphics) Image(imageID uint32) *KittyGraphicsImage

Image looks up a Kitty graphics image by its image ID. Returns nil if no image with the given ID exists.

func (*KittyGraphics) PlacementIterator 

func (kg *KittyGraphics) PlacementIterator(iter *KittyGraphicsPlacementIterator) error

PlacementIterator populates the given iterator with placement data from this storage. The iterator must have been created with NewKittyGraphicsPlacementIterator.

type KittyGraphicsImage 

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

KittyGraphicsImage is a handle to a single Kitty graphics image. It is borrowed from the storage and remains valid until the next mutating terminal call. Access to this handle and any borrowed pixel data derived from it must be serialized with mutations of the owning terminal.

C: GhosttyKittyGraphicsImage

func (*KittyGraphicsImage) Compression 

func (img *KittyGraphicsImage) Compression() (KittyImageCompression, error)

Compression returns the compression of the image.

func (*KittyGraphicsImage) Data 

func (img *KittyGraphicsImage) Data() ([]byte, error)

Data returns a borrowed slice of the raw pixel data. The slice is only valid until the next mutating terminal call.

func (*KittyGraphicsImage) Format 

func (img *KittyGraphicsImage) Format() (KittyImageFormat, error)

Format returns the pixel format of the image.

func (*KittyGraphicsImage) GetMulti 

func (img *KittyGraphicsImage) GetMulti(keys []KittyGraphicsImageData, values []unsafe.Pointer) error

GetMulti queries multiple image data fields in a single cgo call. This is a low-level function; prefer the typed getters (ID, Width, Height, Format, etc.) or Info() for normal use. GetMulti is useful when you need a custom subset of fields and want to avoid per-field cgo overhead.

Each element in keys specifies a data kind, and the corresponding element in values must be an unsafe.Pointer to a variable whose type matches the "Output type" documented for that key in the upstream C header (ghostty/vt/kitty_graphics.h, GhosttyKittyGraphicsImageData enum).

Example: 

var w, h C.uint32_t
err := img.GetMulti(
	[]KittyGraphicsImageData{KittyGraphicsImageDataWidth, KittyGraphicsImageDataHeight},
	[]unsafe.Pointer{unsafe.Pointer(&w), unsafe.Pointer(&h)},
)

C: ghostty_kitty_graphics_image_get_multi

func (*KittyGraphicsImage) Height 

func (img *KittyGraphicsImage) Height() (uint32, error)

Height returns the image height in pixels.

func (*KittyGraphicsImage) ID 

func (img *KittyGraphicsImage) ID() (uint32, error)

ID returns the image ID.

func (*KittyGraphicsImage) Info 

func (img *KittyGraphicsImage) Info() (*KittyGraphicsImageInfo, error)

Info returns all image metadata in a single call. This is more efficient than calling ID, Number, Width, Height, Format, Compression, and Data individually. Uses the get_multi C API to fetch all fields in one cgo round-trip.

func (*KittyGraphicsImage) Number 

func (img *KittyGraphicsImage) Number() (uint32, error)

Number returns the image number.

func (*KittyGraphicsImage) Width 

func (img *KittyGraphicsImage) Width() (uint32, error)

Width returns the image width in pixels.

type KittyGraphicsImageData 

type KittyGraphicsImageData int

KittyGraphicsImageData identifies a data field for Kitty graphics image queries. C: GhosttyKittyGraphicsImageData 

const (
	// KittyGraphicsImageDataInvalid is an invalid / sentinel value.
	KittyGraphicsImageDataInvalid KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_INVALID

	// KittyGraphicsImageDataID is the image ID (uint32_t).
	KittyGraphicsImageDataID KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_ID

	// KittyGraphicsImageDataNumber is the image number (uint32_t).
	KittyGraphicsImageDataNumber KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_NUMBER

	// KittyGraphicsImageDataWidth is the image width in pixels (uint32_t).
	KittyGraphicsImageDataWidth KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_WIDTH

	// KittyGraphicsImageDataHeight is the image height in pixels (uint32_t).
	KittyGraphicsImageDataHeight KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_HEIGHT

	// KittyGraphicsImageDataFormat is the pixel format of the image
	// (GhosttyKittyImageFormat).
	KittyGraphicsImageDataFormat KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_FORMAT

	// KittyGraphicsImageDataCompression is the compression of the image
	// (GhosttyKittyImageCompression).
	KittyGraphicsImageDataCompression KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_COMPRESSION

	// KittyGraphicsImageDataDataPtr is a borrowed pointer to the raw pixel
	// data (const uint8_t **).
	KittyGraphicsImageDataDataPtr KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR

	// KittyGraphicsImageDataDataLen is the length of the raw pixel data
	// in bytes (size_t).
	KittyGraphicsImageDataDataLen KittyGraphicsImageData = C.GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN
)

type KittyGraphicsImageInfo 

type KittyGraphicsImageInfo struct {
	// ID is the image ID.
	ID uint32

	// Number is the image number.
	Number uint32

	// Width is the image width in pixels.
	Width uint32

	// Height is the image height in pixels.
	Height uint32

	// Format is the pixel format of the image.
	Format KittyImageFormat

	// Compression is the compression of the image.
	Compression KittyImageCompression

	// Data is a borrowed slice of the raw pixel data. Only valid
	// until the next mutating terminal call.
	Data []byte
}

KittyGraphicsImageInfo contains all image metadata in a single struct. This is a Go-only convenience type; it has no corresponding C struct. Populated via get_multi in a single cgo call.

type KittyGraphicsPlacementData 

type KittyGraphicsPlacementData int

KittyGraphicsPlacementData identifies a data field for Kitty graphics placement queries. C: GhosttyKittyGraphicsPlacementData 

const (
	// KittyGraphicsPlacementDataInvalid is an invalid / sentinel value.
	KittyGraphicsPlacementDataInvalid KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_INVALID

	// KittyGraphicsPlacementDataImageID is the image ID this placement
	// belongs to (uint32_t).
	KittyGraphicsPlacementDataImageID KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID

	// KittyGraphicsPlacementDataPlacementID is the placement ID (uint32_t).
	KittyGraphicsPlacementDataPlacementID KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID

	// KittyGraphicsPlacementDataIsVirtual indicates whether this is a
	// virtual placement (bool).
	KittyGraphicsPlacementDataIsVirtual KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL

	// KittyGraphicsPlacementDataXOffset is the pixel offset from the left
	// edge of the cell (uint32_t).
	KittyGraphicsPlacementDataXOffset KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_X_OFFSET

	// KittyGraphicsPlacementDataYOffset is the pixel offset from the top
	// edge of the cell (uint32_t).
	KittyGraphicsPlacementDataYOffset KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Y_OFFSET

	// KittyGraphicsPlacementDataSourceX is the source rectangle x origin
	// in pixels (uint32_t).
	KittyGraphicsPlacementDataSourceX KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_X

	// KittyGraphicsPlacementDataSourceY is the source rectangle y origin
	// in pixels (uint32_t).
	KittyGraphicsPlacementDataSourceY KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_Y

	// KittyGraphicsPlacementDataSourceWidth is the source rectangle width
	// in pixels (uint32_t).
	KittyGraphicsPlacementDataSourceWidth KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_WIDTH

	// KittyGraphicsPlacementDataSourceHeight is the source rectangle height
	// in pixels (uint32_t).
	KittyGraphicsPlacementDataSourceHeight KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_HEIGHT

	// KittyGraphicsPlacementDataColumns is the number of columns this
	// placement occupies (uint32_t).
	KittyGraphicsPlacementDataColumns KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_COLUMNS

	// KittyGraphicsPlacementDataRows is the number of rows this placement
	// occupies (uint32_t).
	KittyGraphicsPlacementDataRows KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_ROWS

	// KittyGraphicsPlacementDataZ is the z-index for this placement
	// (int32_t).
	KittyGraphicsPlacementDataZ KittyGraphicsPlacementData = C.GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z
)

type KittyGraphicsPlacementInfo 

type KittyGraphicsPlacementInfo struct {
	// ImageID is the image ID this placement belongs to.
	ImageID uint32

	// PlacementID is the placement ID.
	PlacementID uint32

	// IsVirtual indicates whether this is a virtual placement (unicode placeholder).
	IsVirtual bool

	// XOffset is the pixel offset from the left edge of the cell.
	XOffset uint32

	// YOffset is the pixel offset from the top edge of the cell.
	YOffset uint32

	// SourceX is the source rectangle x origin in pixels.
	SourceX uint32

	// SourceY is the source rectangle y origin in pixels.
	SourceY uint32

	// SourceWidth is the source rectangle width in pixels (0 = full image width).
	SourceWidth uint32

	// SourceHeight is the source rectangle height in pixels (0 = full image height).
	SourceHeight uint32

	// Columns is the number of columns this placement occupies.
	Columns uint32

	// Rows is the number of rows this placement occupies.
	Rows uint32

	// Z is the z-index for this placement.
	Z int32
}

KittyGraphicsPlacementInfo contains all placement metadata in a single struct. This is a Go-only convenience type; it has no corresponding C struct. Populated via get_multi in a single cgo call.

type KittyGraphicsPlacementIterator 

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

KittyGraphicsPlacementIterator iterates over placements in the Kitty graphics storage. It is independently owned and must be freed by calling Close, but the data it yields is only valid while the underlying terminal is not mutated. Access to the iterator must therefore be serialized with mutations of the terminal that produced it.

C: GhosttyKittyGraphicsPlacementIterator

func NewKittyGraphicsPlacementIterator 

func NewKittyGraphicsPlacementIterator() (*KittyGraphicsPlacementIterator, error)

NewKittyGraphicsPlacementIterator creates a new placement iterator. Call KittyGraphics.PlacementIterator to populate it with data, then iterate with Next and read fields with the getter methods. The iterator must be freed by calling Close.

func (*KittyGraphicsPlacementIterator) Close 

func (it *KittyGraphicsPlacementIterator) Close()

Close frees the placement iterator. After this call, the iterator must not be used.

func (*KittyGraphicsPlacementIterator) Columns 

func (it *KittyGraphicsPlacementIterator) Columns() (uint32, error)

Columns returns the number of columns this placement occupies.

func (*KittyGraphicsPlacementIterator) GetMulti 

func (it *KittyGraphicsPlacementIterator) GetMulti(keys []KittyGraphicsPlacementData, values []unsafe.Pointer) error

GetMulti queries multiple placement data fields in a single cgo call. This is a low-level function; prefer the typed getters (ImageID, PlacementID, Z, etc.) or Info() for normal use. GetMulti is useful when you need a custom subset of fields and want to avoid per-field cgo overhead.

Each element in keys specifies a data kind, and the corresponding element in values must be an unsafe.Pointer to a variable whose type matches the "Output type" documented for that key in the upstream C header (ghostty/vt/kitty_graphics.h, GhosttyKittyGraphicsPlacementData enum).

Example: 

var imageID C.uint32_t
var z C.int32_t
err := it.GetMulti(
	[]KittyGraphicsPlacementData{KittyGraphicsPlacementDataImageID, KittyGraphicsPlacementDataZ},
	[]unsafe.Pointer{unsafe.Pointer(&imageID), unsafe.Pointer(&z)},
)

C: ghostty_kitty_graphics_placement_get_multi

func (*KittyGraphicsPlacementIterator) GridSize 

func (it *KittyGraphicsPlacementIterator) GridSize(img *KittyGraphicsImage, t *Terminal) (cols, rows uint32, err error)

GridSize computes the number of grid columns and rows the current placement occupies.

func (*KittyGraphicsPlacementIterator) ImageID 

func (it *KittyGraphicsPlacementIterator) ImageID() (uint32, error)

ImageID returns the image ID of the current placement.

func (*KittyGraphicsPlacementIterator) Info 

func (it *KittyGraphicsPlacementIterator) Info() (*KittyGraphicsPlacementInfo, error)

Info returns all placement metadata in a single call. This is more efficient than calling ImageID, PlacementID, IsVirtual, XOffset, YOffset, SourceX, SourceY, SourceWidth, SourceHeight, Columns, Rows, and Z individually. Uses the get_multi C API to fetch all fields in one cgo round-trip.

func (*KittyGraphicsPlacementIterator) IsVirtual 

func (it *KittyGraphicsPlacementIterator) IsVirtual() (bool, error)

IsVirtual reports whether the current placement is a virtual (unicode placeholder) placement.

func (*KittyGraphicsPlacementIterator) Next 

func (it *KittyGraphicsPlacementIterator) Next() bool

Next advances the iterator to the next placement. Returns true if a placement is available, false when iteration is complete.

func (*KittyGraphicsPlacementIterator) PixelSize 

func (it *KittyGraphicsPlacementIterator) PixelSize(img *KittyGraphicsImage, t *Terminal) (width, height uint32, err error)

PixelSize computes the rendered pixel dimensions of the current placement, accounting for the source rectangle, specified columns/rows, and aspect ratio.

func (*KittyGraphicsPlacementIterator) PlacementID 

func (it *KittyGraphicsPlacementIterator) PlacementID() (uint32, error)

PlacementID returns the placement ID of the current placement.

func (*KittyGraphicsPlacementIterator) Rect 

func (it *KittyGraphicsPlacementIterator) Rect(img *KittyGraphicsImage, t *Terminal) (*Selection, error)

Rect computes the grid rectangle occupied by the current placement. Virtual placements (unicode placeholders) return an error with ResultNoValue.

func (*KittyGraphicsPlacementIterator) RenderInfo 

func (it *KittyGraphicsPlacementIterator) RenderInfo(img *KittyGraphicsImage, t *Terminal) (*KittyGraphicsPlacementRenderInfo, error)

RenderInfo returns all rendering geometry for the current placement in a single call. This combines the results of PixelSize, GridSize, ViewportPos, and SourceRect into one cgo call.

When ViewportVisible is false, the placement is fully off-screen or is a virtual placement; ViewportCol and ViewportRow may contain meaningless values in that case.

func (*KittyGraphicsPlacementIterator) Rows 

func (it *KittyGraphicsPlacementIterator) Rows() (uint32, error)

Rows returns the number of rows this placement occupies.

func (*KittyGraphicsPlacementIterator) SetLayer 

func (it *KittyGraphicsPlacementIterator) SetLayer(layer KittyPlacementLayer) error

SetLayer sets the z-layer filter for the iterator. Only placements matching the given layer will be returned by Next. The default is KittyPlacementLayerAll (no filtering).

func (*KittyGraphicsPlacementIterator) SourceHeight 

func (it *KittyGraphicsPlacementIterator) SourceHeight() (uint32, error)

SourceHeight returns the source rectangle height in pixels (0 = full image height).

func (*KittyGraphicsPlacementIterator) SourceRect 

func (it *KittyGraphicsPlacementIterator) SourceRect(img *KittyGraphicsImage) (x, y, width, height uint32, err error)

SourceRect returns the resolved source rectangle for the current placement in pixels, clamped to the actual image bounds. A width or height of 0 in the placement means "use the full image dimension".

func (*KittyGraphicsPlacementIterator) SourceWidth 

func (it *KittyGraphicsPlacementIterator) SourceWidth() (uint32, error)

SourceWidth returns the source rectangle width in pixels (0 = full image width).

func (*KittyGraphicsPlacementIterator) SourceX 

func (it *KittyGraphicsPlacementIterator) SourceX() (uint32, error)

SourceX returns the source rectangle x origin in pixels.

func (*KittyGraphicsPlacementIterator) SourceY 

func (it *KittyGraphicsPlacementIterator) SourceY() (uint32, error)

SourceY returns the source rectangle y origin in pixels.

func (*KittyGraphicsPlacementIterator) ViewportPos 

func (it *KittyGraphicsPlacementIterator) ViewportPos(img *KittyGraphicsImage, t *Terminal) (col, row int32, err error)

ViewportPos returns the viewport-relative grid position of the current placement. The row can be negative for partially visible placements. Returns an error with ResultNoValue when fully off-screen or for virtual placements.

func (*KittyGraphicsPlacementIterator) XOffset 

func (it *KittyGraphicsPlacementIterator) XOffset() (uint32, error)

XOffset returns the pixel offset from the left edge of the cell.

func (*KittyGraphicsPlacementIterator) YOffset 

func (it *KittyGraphicsPlacementIterator) YOffset() (uint32, error)

YOffset returns the pixel offset from the top edge of the cell.

func (*KittyGraphicsPlacementIterator) Z 

func (it *KittyGraphicsPlacementIterator) Z() (int32, error)

Z returns the z-index of the current placement.

type KittyGraphicsPlacementRenderInfo 

type KittyGraphicsPlacementRenderInfo struct {
	// PixelWidth is the rendered width in pixels.
	PixelWidth uint32

	// PixelHeight is the rendered height in pixels.
	PixelHeight uint32

	// GridCols is the number of grid columns the placement occupies.
	GridCols uint32

	// GridRows is the number of grid rows the placement occupies.
	GridRows uint32

	// ViewportCol is the viewport-relative column (may be negative
	// for partially visible placements).
	ViewportCol int32

	// ViewportRow is the viewport-relative row (may be negative
	// for partially visible placements).
	ViewportRow int32

	// ViewportVisible is false when the placement is fully off-screen
	// or is a virtual placement. When false, ViewportCol and ViewportRow
	// may contain meaningless values.
	ViewportVisible bool

	// SourceX is the resolved source rectangle x origin in pixels.
	SourceX uint32

	// SourceY is the resolved source rectangle y origin in pixels.
	SourceY uint32

	// SourceWidth is the resolved source rectangle width in pixels.
	SourceWidth uint32

	// SourceHeight is the resolved source rectangle height in pixels.
	SourceHeight uint32
}

KittyGraphicsPlacementRenderInfo contains all rendering geometry for a placement in a single struct. Combines pixel size, grid size, viewport position, and source rectangle into one cgo call.

C: GhosttyKittyGraphicsPlacementRenderInfo

type KittyImageCompression 

type KittyImageCompression int

KittyImageCompression describes the compression of a Kitty graphics image.

C: GhosttyKittyImageCompression 

const (
	// KittyImageCompressionNone means no compression.
	KittyImageCompressionNone KittyImageCompression = C.GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE

	// KittyImageCompressionZlibDeflate means zlib/deflate compression.
	KittyImageCompressionZlibDeflate KittyImageCompression = C.GHOSTTY_KITTY_IMAGE_COMPRESSION_ZLIB_DEFLATE
)

type KittyImageFormat 

type KittyImageFormat int

KittyImageFormat describes the pixel format of a Kitty graphics image.

C: GhosttyKittyImageFormat 

const (
	// KittyImageFormatRGB is 24-bit RGB (3 bytes per pixel).
	KittyImageFormatRGB KittyImageFormat = C.GHOSTTY_KITTY_IMAGE_FORMAT_RGB

	// KittyImageFormatRGBA is 32-bit RGBA (4 bytes per pixel).
	KittyImageFormatRGBA KittyImageFormat = C.GHOSTTY_KITTY_IMAGE_FORMAT_RGBA

	// KittyImageFormatPNG is compressed PNG data.
	KittyImageFormatPNG KittyImageFormat = C.GHOSTTY_KITTY_IMAGE_FORMAT_PNG

	// KittyImageFormatGrayAlpha is 16-bit gray+alpha (2 bytes per pixel).
	KittyImageFormatGrayAlpha KittyImageFormat = C.GHOSTTY_KITTY_IMAGE_FORMAT_GRAY_ALPHA

	// KittyImageFormatGray is 8-bit grayscale (1 byte per pixel).
	KittyImageFormatGray KittyImageFormat = C.GHOSTTY_KITTY_IMAGE_FORMAT_GRAY
)

type KittyKeyFlags 

type KittyKeyFlags uint8

KittyKeyFlags is a bitmask of Kitty keyboard protocol flags. C: GhosttyKittyKeyFlags 

const (
	// KittyKeyDisabled disables the Kitty keyboard protocol (all flags off).
	KittyKeyDisabled KittyKeyFlags = C.GHOSTTY_KITTY_KEY_DISABLED

	// KittyKeyDisambiguate enables disambiguating escape codes.
	KittyKeyDisambiguate KittyKeyFlags = C.GHOSTTY_KITTY_KEY_DISAMBIGUATE

	// KittyKeyReportEvents enables reporting key press and release events.
	KittyKeyReportEvents KittyKeyFlags = C.GHOSTTY_KITTY_KEY_REPORT_EVENTS

	// KittyKeyReportAlternates enables reporting alternate key codes.
	KittyKeyReportAlternates KittyKeyFlags = C.GHOSTTY_KITTY_KEY_REPORT_ALTERNATES

	// KittyKeyReportAll reports all key events including those normally
	// handled by the terminal.
	KittyKeyReportAll KittyKeyFlags = C.GHOSTTY_KITTY_KEY_REPORT_ALL

	// KittyKeyReportAssociated reports associated text with key events.
	KittyKeyReportAssociated KittyKeyFlags = C.GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED

	// KittyKeyAll enables all Kitty keyboard protocol flags.
	KittyKeyAll KittyKeyFlags = C.GHOSTTY_KITTY_KEY_ALL
)

type KittyPlacementLayer 

type KittyPlacementLayer int

KittyPlacementLayer classifies z-layer for kitty graphics placements. Based on the kitty protocol z-index conventions.

C: GhosttyKittyPlacementLayer 

const (
	// KittyPlacementLayerAll disables layer filtering (all placements).
	KittyPlacementLayerAll KittyPlacementLayer = C.GHOSTTY_KITTY_PLACEMENT_LAYER_ALL

	// KittyPlacementLayerBelowBG matches placements below cell background
	// (z < INT32_MIN/2).
	KittyPlacementLayerBelowBG KittyPlacementLayer = C.GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_BG

	// KittyPlacementLayerBelowText matches placements above background but
	// below text (INT32_MIN/2 <= z < 0).
	KittyPlacementLayerBelowText KittyPlacementLayer = C.GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_TEXT

	// KittyPlacementLayerAboveText matches placements above text (z >= 0).
	KittyPlacementLayerAboveText KittyPlacementLayer = C.GHOSTTY_KITTY_PLACEMENT_LAYER_ABOVE_TEXT
)

type Mode 

type Mode uint16

Mode is a packed 16-bit terminal mode identifier. It encodes a mode value (bits 0–14) and an ANSI flag (bit 15). DEC private modes have the ANSI bit clear; standard ANSI modes have it set. C: GhosttyMode

func (Mode) ANSI 

func (m Mode) ANSI() bool

ANSI reports whether this is a standard ANSI mode. If false, it is a DEC private mode (?-prefixed).

func (Mode) Value 

func (m Mode) Value() uint16

Value returns the numeric mode value (0–32767).

type ModeReportState 

type ModeReportState int

ModeReportState represents DECRPM report state values (Ps2 parameter). C: GhosttyModeReportState 

const (
	// ModeReportNotRecognized means the mode is not recognized.
	ModeReportNotRecognized ModeReportState = C.GHOSTTY_MODE_REPORT_NOT_RECOGNIZED

	// ModeReportSet means the mode is set (enabled).
	ModeReportSet ModeReportState = C.GHOSTTY_MODE_REPORT_SET

	// ModeReportReset means the mode is reset (disabled).
	ModeReportReset ModeReportState = C.GHOSTTY_MODE_REPORT_RESET

	// ModeReportPermanentlySet means the mode is permanently set.
	ModeReportPermanentlySet ModeReportState = C.GHOSTTY_MODE_REPORT_PERMANENTLY_SET

	// ModeReportPermanentlyReset means the mode is permanently reset.
	ModeReportPermanentlyReset ModeReportState = C.GHOSTTY_MODE_REPORT_PERMANENTLY_RESET
)

type Mods 

type Mods uint16

Mods is a bitmask representing keyboard modifier keys. Use the Mods* constants to test and set individual modifiers.

C: GhosttyMods 

const (
	// ModShift indicates the Shift key is pressed.
	ModShift Mods = C.GHOSTTY_MODS_SHIFT

	// ModCtrl indicates the Control key is pressed.
	ModCtrl Mods = C.GHOSTTY_MODS_CTRL

	// ModAlt indicates the Alt/Option key is pressed.
	ModAlt Mods = C.GHOSTTY_MODS_ALT

	// ModSuper indicates the Super/Command/Windows key is pressed.
	ModSuper Mods = C.GHOSTTY_MODS_SUPER

	// ModCapsLock indicates Caps Lock is active.
	ModCapsLock Mods = C.GHOSTTY_MODS_CAPS_LOCK

	// ModNumLock indicates Num Lock is active.
	ModNumLock Mods = C.GHOSTTY_MODS_NUM_LOCK

	// ModShiftSide indicates right Shift is pressed (0 = left, 1 = right).
	// Only meaningful when ModShift is set.
	ModShiftSide Mods = C.GHOSTTY_MODS_SHIFT_SIDE

	// ModCtrlSide indicates right Ctrl is pressed (0 = left, 1 = right).
	// Only meaningful when ModCtrl is set.
	ModCtrlSide Mods = C.GHOSTTY_MODS_CTRL_SIDE

	// ModAltSide indicates right Alt is pressed (0 = left, 1 = right).
	// Only meaningful when ModAlt is set.
	ModAltSide Mods = C.GHOSTTY_MODS_ALT_SIDE

	// ModSuperSide indicates right Super is pressed (0 = left, 1 = right).
	// Only meaningful when ModSuper is set.
	ModSuperSide Mods = C.GHOSTTY_MODS_SUPER_SIDE
)

func ParseMods 

func ParseMods(s string) (Mods, error)

ParseMods returns the Mods value parsed from the given "+" or "," separated list of modifier names. See Mods.UnmarshalText for the accepted syntax and aliases.

func (Mods) MarshalText 

func (m Mods) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. The output is the same as String() so the type integrates with encoding/json and other text-based encoders. An empty bitmask marshals to an empty byte slice (i.e. JSON `""`).

func (Mods) String 

func (m Mods) String() string

String returns a human-friendly representation of the modifier bitmask: each set bit is rendered as its snake_case name and bits are joined with "+" in a stable canonical order. Returns "" if no bits are set.

Examples: 

Mods(0).String()                   == ""
(ModShift | ModCtrl).String()      == "shift+ctrl"
(ModShift | ModShiftSide).String() == "shift+shift_side"

func (*Mods) UnmarshalText 

func (m *Mods) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It parses a "+" or "," separated list of modifier names and stores the resulting bitmask in the receiver. Whitespace around tokens and empty tokens are ignored. Recognized names are the canonical snake_case names returned by String plus the upstream aliases (cmd/command, opt/option, control). An empty input is valid and produces a zero bitmask. Returns an error if any token is not recognized.

The receiver is overwritten, not OR'd into.

type MouseAction 

type MouseAction int

MouseAction represents the type of mouse event (press, release, or motion).

C: GhosttyMouseAction 

const (
	// MouseActionPress indicates a mouse button was pressed.
	MouseActionPress MouseAction = C.GHOSTTY_MOUSE_ACTION_PRESS

	// MouseActionRelease indicates a mouse button was released.
	MouseActionRelease MouseAction = C.GHOSTTY_MOUSE_ACTION_RELEASE

	// MouseActionMotion indicates the mouse moved.
	MouseActionMotion MouseAction = C.GHOSTTY_MOUSE_ACTION_MOTION
)

type MouseButton 

type MouseButton int

MouseButton identifies which mouse button was involved in an event.

C: GhosttyMouseButton 

const (
	MouseButtonUnknown MouseButton = C.GHOSTTY_MOUSE_BUTTON_UNKNOWN
	MouseButtonLeft    MouseButton = C.GHOSTTY_MOUSE_BUTTON_LEFT
	MouseButtonRight   MouseButton = C.GHOSTTY_MOUSE_BUTTON_RIGHT
	MouseButtonMiddle  MouseButton = C.GHOSTTY_MOUSE_BUTTON_MIDDLE
	MouseButtonFour    MouseButton = C.GHOSTTY_MOUSE_BUTTON_FOUR
	MouseButtonFive    MouseButton = C.GHOSTTY_MOUSE_BUTTON_FIVE
	MouseButtonSix     MouseButton = C.GHOSTTY_MOUSE_BUTTON_SIX
	MouseButtonSeven   MouseButton = C.GHOSTTY_MOUSE_BUTTON_SEVEN
	MouseButtonEight   MouseButton = C.GHOSTTY_MOUSE_BUTTON_EIGHT
	MouseButtonNine    MouseButton = C.GHOSTTY_MOUSE_BUTTON_NINE
	MouseButtonTen     MouseButton = C.GHOSTTY_MOUSE_BUTTON_TEN
	MouseButtonEleven  MouseButton = C.GHOSTTY_MOUSE_BUTTON_ELEVEN
)

func ParseMouseButton 

func ParseMouseButton(s string) (MouseButton, error)

ParseMouseButton returns the MouseButton value for the given canonical name (e.g. "left", "right", "four"). Returns an error if the name is not recognized.

func (MouseButton) MarshalText 

func (b MouseButton) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. The output is the same as String() so the type integrates with encoding/json and other text-based encoders.

func (MouseButton) String 

func (b MouseButton) String() string

String returns the canonical lowercase name of the mouse button (e.g. "left", "right", "four"). Unknown values render as "unknown".

func (*MouseButton) UnmarshalText 

func (b *MouseButton) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It parses a canonical mouse button name (e.g. "left", "right", "four") and stores the corresponding MouseButton value in the receiver. Returns an error if the name is not recognized.

type MouseEncoder 

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

MouseEncoder encodes mouse events into terminal escape sequences, supporting X10, UTF-8, SGR, URxvt, and SGR-Pixels mouse protocols. It maintains mutable encoder state and is not safe for concurrent use.

Basic usage:

  1. Create an encoder with NewMouseEncoder.
  2. Configure options with SetOpt* methods or SetOptFromTerminal.
  3. Create mouse events, encode them with Encode, and free them.
  4. Free the encoder with Close when done.

C: GhosttyMouseEncoder

func NewMouseEncoder 

func NewMouseEncoder() (*MouseEncoder, error)

NewMouseEncoder creates a new mouse encoder with default options. The encoder must be freed with Close when no longer needed.

func (*MouseEncoder) Close 

func (enc *MouseEncoder) Close()

Close frees the underlying mouse encoder handle. After this call, the encoder must not be used.

func (*MouseEncoder) Encode 

func (enc *MouseEncoder) Encode(event *MouseEvent) ([]byte, error)

Encode encodes a mouse event into a terminal escape sequence and returns the result as a byte slice. Not all mouse events produce output; in that case, a nil slice and nil error are returned.

func (*MouseEncoder) Reset 

func (enc *MouseEncoder) Reset()

Reset clears internal encoder state such as motion deduplication (last tracked cell).

func (*MouseEncoder) SetOptAnyButtonPressed 

func (enc *MouseEncoder) SetOptAnyButtonPressed(pressed bool)

SetOptAnyButtonPressed sets whether any mouse button is currently pressed.

func (*MouseEncoder) SetOptFormat 

func (enc *MouseEncoder) SetOptFormat(format MouseFormat)

SetOptFormat sets the mouse output format on the encoder.

func (*MouseEncoder) SetOptFromTerminal 

func (enc *MouseEncoder) SetOptFromTerminal(t *Terminal)

SetOptFromTerminal reads the terminal's current mouse tracking mode and output format and applies them to the encoder. It does not modify size or any-button state. The caller must serialize access to both the encoder and the terminal during this call.

func (*MouseEncoder) SetOptSize 

func (enc *MouseEncoder) SetOptSize(s MouseEncoderSize)

SetOptSize sets the renderer size context on the encoder.

func (*MouseEncoder) SetOptTrackLastCell 

func (enc *MouseEncoder) SetOptTrackLastCell(track bool)

SetOptTrackLastCell enables or disables motion deduplication by last cell.

func (*MouseEncoder) SetOptTrackingMode 

func (enc *MouseEncoder) SetOptTrackingMode(mode MouseTrackingMode)

SetOptTrackingMode sets the mouse tracking mode on the encoder.

type MouseEncoderOption 

type MouseEncoderOption int

MouseEncoderOption identifies a mouse encoder configuration option for use with SetOpt.

C: GhosttyMouseEncoderOption 

const (
	// MouseEncoderOptEvent sets the mouse tracking mode
	// (value: MouseTrackingMode).
	MouseEncoderOptEvent MouseEncoderOption = C.GHOSTTY_MOUSE_ENCODER_OPT_EVENT

	// MouseEncoderOptFormat sets the mouse output format
	// (value: MouseFormat).
	MouseEncoderOptFormat MouseEncoderOption = C.GHOSTTY_MOUSE_ENCODER_OPT_FORMAT

	// MouseEncoderOptSize sets the renderer size context
	// (value: MouseEncoderSize).
	MouseEncoderOptSize MouseEncoderOption = C.GHOSTTY_MOUSE_ENCODER_OPT_SIZE

	// MouseEncoderOptAnyButtonPressed sets whether any mouse button
	// is currently pressed (value: bool).
	MouseEncoderOptAnyButtonPressed MouseEncoderOption = C.GHOSTTY_MOUSE_ENCODER_OPT_ANY_BUTTON_PRESSED

	// MouseEncoderOptTrackLastCell enables motion deduplication by
	// last cell (value: bool).
	MouseEncoderOptTrackLastCell MouseEncoderOption = C.GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL
)

type MouseEncoderSize 

type MouseEncoderSize struct {
	// ScreenWidth is the full screen width in pixels.
	ScreenWidth uint32

	// ScreenHeight is the full screen height in pixels.
	ScreenHeight uint32

	// CellWidth is the cell width in pixels. Must be non-zero.
	CellWidth uint32

	// CellHeight is the cell height in pixels. Must be non-zero.
	CellHeight uint32

	// PaddingTop is the top padding in pixels.
	PaddingTop uint32

	// PaddingBottom is the bottom padding in pixels.
	PaddingBottom uint32

	// PaddingRight is the right padding in pixels.
	PaddingRight uint32

	// PaddingLeft is the left padding in pixels.
	PaddingLeft uint32
}

MouseEncoderSize describes the rendered terminal geometry used to convert surface-space positions into encoded coordinates.

C: GhosttyMouseEncoderSize

type MouseEvent 

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

MouseEvent is an opaque handle representing a normalized mouse input event containing action, button, modifiers, and surface-space position. It is mutable and reusable, but not safe for concurrent use.

C: GhosttyMouseEvent

func NewMouseEvent 

func NewMouseEvent() (*MouseEvent, error)

NewMouseEvent creates a new mouse event with default values. The event must be freed with Close when no longer needed.

func (*MouseEvent) Action 

func (e *MouseEvent) Action() MouseAction

Action returns the mouse action (press, release, motion).

func (*MouseEvent) Button 

func (e *MouseEvent) Button() (button MouseButton, ok bool)

Button returns the mouse button and whether one is set. If no button is set (e.g. a motion-only event), ok is false.

func (*MouseEvent) ClearButton 

func (e *MouseEvent) ClearButton()

ClearButton clears the event button, setting it to "none". Use this for motion events with no button pressed.

func (*MouseEvent) Close 

func (e *MouseEvent) Close()

Close frees the underlying mouse event handle. After this call, the mouse event must not be used.

func (*MouseEvent) Mods 

func (e *MouseEvent) Mods() Mods

Mods returns the keyboard modifiers held during the mouse event.

func (*MouseEvent) Position 

func (e *MouseEvent) Position() MousePosition

Position returns the event position in surface-space pixels.

func (*MouseEvent) SetAction 

func (e *MouseEvent) SetAction(action MouseAction)

SetAction sets the mouse action (press, release, motion).

func (*MouseEvent) SetButton 

func (e *MouseEvent) SetButton(button MouseButton)

SetButton sets the mouse button for the event.

func (*MouseEvent) SetMods 

func (e *MouseEvent) SetMods(mods Mods)

SetMods sets the keyboard modifiers held during the mouse event.

func (*MouseEvent) SetPosition 

func (e *MouseEvent) SetPosition(pos MousePosition)

SetPosition sets the event position in surface-space pixels.

type MouseFormat 

type MouseFormat int

MouseFormat selects the wire format for mouse escape sequences.

C: GhosttyMouseFormat 

const (
	MouseFormatX10       MouseFormat = C.GHOSTTY_MOUSE_FORMAT_X10
	MouseFormatUTF8      MouseFormat = C.GHOSTTY_MOUSE_FORMAT_UTF8
	MouseFormatSGR       MouseFormat = C.GHOSTTY_MOUSE_FORMAT_SGR
	MouseFormatURxvt     MouseFormat = C.GHOSTTY_MOUSE_FORMAT_URXVT
	MouseFormatSGRPixels MouseFormat = C.GHOSTTY_MOUSE_FORMAT_SGR_PIXELS
)

type MousePosition 

type MousePosition struct {
	X float32
	Y float32
}

MousePosition represents a mouse position in surface-space pixels.

C: GhosttyMousePosition

type MouseTrackingMode 

type MouseTrackingMode int

MouseTrackingMode selects which mouse events the terminal tracks.

C: GhosttyMouseTrackingMode 

const (
	// MouseTrackingNone disables mouse reporting.
	MouseTrackingNone MouseTrackingMode = C.GHOSTTY_MOUSE_TRACKING_NONE

	// MouseTrackingX10 enables X10 mouse mode.
	MouseTrackingX10 MouseTrackingMode = C.GHOSTTY_MOUSE_TRACKING_X10

	// MouseTrackingNormal enables normal mouse mode (button press/release only).
	MouseTrackingNormal MouseTrackingMode = C.GHOSTTY_MOUSE_TRACKING_NORMAL

	// MouseTrackingButton enables button-event tracking mode.
	MouseTrackingButton MouseTrackingMode = C.GHOSTTY_MOUSE_TRACKING_BUTTON

	// MouseTrackingAny enables any-event tracking mode.
	MouseTrackingAny MouseTrackingMode = C.GHOSTTY_MOUSE_TRACKING_ANY
)

type OptimizeMode 

type OptimizeMode int

OptimizeMode identifies the optimization mode the library was built with. C: GhosttyOptimizeMode 

const (
	// OptimizeDebug is the debug optimization mode.
	OptimizeDebug OptimizeMode = C.GHOSTTY_OPTIMIZE_DEBUG

	// OptimizeReleaseSafe is the release-safe optimization mode.
	OptimizeReleaseSafe OptimizeMode = C.GHOSTTY_OPTIMIZE_RELEASE_SAFE

	// OptimizeReleaseSmall is the release-small optimization mode.
	OptimizeReleaseSmall OptimizeMode = C.GHOSTTY_OPTIMIZE_RELEASE_SMALL

	// OptimizeReleaseFast is the release-fast optimization mode.
	OptimizeReleaseFast OptimizeMode = C.GHOSTTY_OPTIMIZE_RELEASE_FAST
)

type OptionAsAlt 

type OptionAsAlt int

OptionAsAlt determines whether the macOS "option" key is treated as "alt".

C: GhosttyOptionAsAlt 

const (
	// OptionAsAltFalse means the option key is not treated as alt.
	OptionAsAltFalse OptionAsAlt = C.GHOSTTY_OPTION_AS_ALT_FALSE

	// OptionAsAltTrue means the option key is treated as alt.
	OptionAsAltTrue OptionAsAlt = C.GHOSTTY_OPTION_AS_ALT_TRUE

	// OptionAsAltLeft means only the left option key is treated as alt.
	OptionAsAltLeft OptionAsAlt = C.GHOSTTY_OPTION_AS_ALT_LEFT

	// OptionAsAltRight means only the right option key is treated as alt.
	OptionAsAltRight OptionAsAlt = C.GHOSTTY_OPTION_AS_ALT_RIGHT
)

type Palette 

type Palette [PaletteSize]ColorRGB

Palette is a 256-color palette.

type Point 

type Point struct {
	// Tag determines the coordinate system.
	Tag PointTag

	// X is the column (0-indexed).
	X uint16

	// Y is the row (0-indexed). May exceed page size for screen/history tags.
	Y uint32
}

Point is a tagged position in the terminal grid. The Tag determines which coordinate system X and Y refer to. C: GhosttyPoint

type PointTag 

type PointTag int

PointTag determines which coordinate system a point uses. C: GhosttyPointTag 

const (
	// PointTagActive references the active area where the cursor can move.
	PointTagActive PointTag = C.GHOSTTY_POINT_TAG_ACTIVE

	// PointTagViewport references the visible viewport (changes when scrolled).
	PointTagViewport PointTag = C.GHOSTTY_POINT_TAG_VIEWPORT

	// PointTagScreen references the full screen including scrollback.
	PointTagScreen PointTag = C.GHOSTTY_POINT_TAG_SCREEN

	// PointTagHistory references scrollback history only (before active area).
	PointTagHistory PointTag = C.GHOSTTY_POINT_TAG_HISTORY
)

type RenderState 

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

RenderState holds the state required to render a visible screen (viewport) of a terminal instance. It is stateful and optimized for repeated updates from a single terminal, only updating dirty regions of the screen.

A render state owns its own snapshot storage. Hold exclusive access to the terminal while calling RenderState.Update. After Update returns, the render state can be read without touching the terminal until the next Update. Do not call Update concurrently with reads from the same render state.

Iterators populated from the render state are only valid until the next Update, but copied values returned from their getter methods can be retained.

Basic usage:

  1. Create an empty render state with NewRenderState.
  2. Update it from a terminal via Update whenever needed.
  3. Read from the render state to get data for drawing.

C: GhosttyRenderState

func NewRenderState 

func NewRenderState() (*RenderState, error)

NewRenderState creates a new empty render state.

func (*RenderState) Close 

func (rs *RenderState) Close()

Close frees the underlying render state handle. After this call, the render state must not be used.

func (*RenderState) ColorBackground 

func (rs *RenderState) ColorBackground() (ColorRGB, error)

ColorBackground returns the default/current background color.

func (*RenderState) ColorCursor 

func (rs *RenderState) ColorCursor() (*ColorRGB, error)

ColorCursor returns the cursor color when explicitly set by terminal state. Returns nil (without error) when no explicit cursor color is set.

func (*RenderState) ColorForeground 

func (rs *RenderState) ColorForeground() (ColorRGB, error)

ColorForeground returns the default/current foreground color.

func (*RenderState) ColorPalette 

func (rs *RenderState) ColorPalette() (*Palette, error)

ColorPalette returns the active 256-color palette.

func (*RenderState) Colors 

func (rs *RenderState) Colors() (*RenderStateColors, error)

Colors returns all color information from the render state in a single call using the sized-struct API.

func (*RenderState) Cols 

func (rs *RenderState) Cols() (uint16, error)

Cols returns the viewport width in cells.

func (*RenderState) CursorBlinking 

func (rs *RenderState) CursorBlinking() (bool, error)

CursorBlinking reports whether the cursor should blink based on terminal modes.

func (*RenderState) CursorPasswordInput 

func (rs *RenderState) CursorPasswordInput() (bool, error)

CursorPasswordInput reports whether the cursor is at a password input field.

func (*RenderState) CursorViewportHasValue 

func (rs *RenderState) CursorViewportHasValue() (bool, error)

CursorViewportHasValue reports whether the cursor is visible within the viewport. If false, the cursor viewport position values are undefined.

func (*RenderState) CursorViewportWideTail 

func (rs *RenderState) CursorViewportWideTail() (bool, error)

CursorViewportWideTail reports whether the cursor is on the tail of a wide character. Only valid when CursorViewportHasValue returns true.

func (*RenderState) CursorViewportX 

func (rs *RenderState) CursorViewportX() (uint16, error)

CursorViewportX returns the cursor viewport x position in cells. Only valid when CursorViewportHasValue returns true.

func (*RenderState) CursorViewportY 

func (rs *RenderState) CursorViewportY() (uint16, error)

CursorViewportY returns the cursor viewport y position in cells. Only valid when CursorViewportHasValue returns true.

func (*RenderState) CursorVisible 

func (rs *RenderState) CursorVisible() (bool, error)

CursorVisible reports whether the cursor is visible based on terminal modes.

func (*RenderState) CursorVisualStyle 

func (rs *RenderState) CursorVisualStyle() (CursorVisualStyle, error)

CursorVisualStyle returns the visual style of the cursor.

func (*RenderState) Dirty 

func (rs *RenderState) Dirty() (RenderStateDirty, error)

Dirty returns the current dirty state.

func (*RenderState) GetMulti 

func (rs *RenderState) GetMulti(keys []RenderStateData, values []unsafe.Pointer) error

GetMulti queries multiple render state data fields in a single cgo call. This is a low-level function; prefer the typed getters (Cols, Rows, CursorVisible, etc.) for normal use. GetMulti is useful when you need many fields at once and want to avoid per-field cgo overhead.

Each element in keys specifies a data kind, and the corresponding element in values must be an unsafe.Pointer to a variable whose type matches the "Output type" documented for that key in the upstream C header (ghostty/vt/render.h, GhosttyRenderStateData enum).

Example: 

var cols, rows C.uint16_t
err := rs.GetMulti(
	[]RenderStateData{RenderStateDataCols, RenderStateDataRows},
	[]unsafe.Pointer{unsafe.Pointer(&cols), unsafe.Pointer(&rows)},
)

C: ghostty_render_state_get_multi

func (*RenderState) RowIterator 

func (rs *RenderState) RowIterator(ri *RenderStateRowIterator) error

RowIterator populates a pre-allocated row iterator with row data from the render state. The iterator can then be advanced with Next and queried with getter methods.

The iterator can be reused across multiple calls. The iterator view is only valid until the next call to RenderState.Update.

func (*RenderState) Rows 

func (rs *RenderState) Rows() (uint16, error)

Rows returns the viewport height in cells.

func (*RenderState) SetDirty 

func (rs *RenderState) SetDirty(dirty RenderStateDirty) error

SetDirty sets the dirty state.

func (*RenderState) Update 

func (rs *RenderState) Update(t *Terminal) error

Update updates the render state from a terminal instance. This consumes terminal/screen dirty state and is the only render-state operation that touches the terminal. Hold exclusive access to the terminal while this call is running, and do not read from the same render state concurrently with Update.

type RenderStateColors 

type RenderStateColors struct {
	// Background is the default/current background color.
	Background ColorRGB

	// Foreground is the default/current foreground color.
	Foreground ColorRGB

	// Cursor is the cursor color when explicitly set by terminal state.
	// Only valid when CursorHasValue is true.
	Cursor ColorRGB

	// CursorHasValue is true when Cursor contains a valid explicit
	// cursor color value.
	CursorHasValue bool

	// Palette is the active 256-color palette.
	Palette Palette
}

RenderStateColors holds all color information from a render state, retrieved in a single call via the sized-struct API. C: GhosttyRenderStateColors

type RenderStateData 

type RenderStateData int

RenderStateData identifies a data field for render state queries. C: GhosttyRenderStateData 

const (
	// RenderStateDataInvalid is an invalid / sentinel value.
	RenderStateDataInvalid RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_INVALID

	// RenderStateDataCols is the viewport width in cells (uint16_t).
	RenderStateDataCols RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_COLS

	// RenderStateDataRows is the viewport height in cells (uint16_t).
	RenderStateDataRows RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_ROWS

	// RenderStateDataDirty is the current dirty state
	// (GhosttyRenderStateDirty).
	RenderStateDataDirty RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_DIRTY

	// RenderStateDataRowIterator populates a pre-allocated row iterator
	// (GhosttyRenderStateRowIterator).
	RenderStateDataRowIterator RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR

	// RenderStateDataColorBackground is the default/current background
	// color (GhosttyColorRgb).
	RenderStateDataColorBackground RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_COLOR_BACKGROUND

	// RenderStateDataColorForeground is the default/current foreground
	// color (GhosttyColorRgb).
	RenderStateDataColorForeground RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_COLOR_FOREGROUND

	// RenderStateDataColorCursor is the cursor color when explicitly set
	// (GhosttyColorRgb).
	RenderStateDataColorCursor RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR

	// RenderStateDataColorCursorHasValue indicates whether an explicit
	// cursor color is set (bool).
	RenderStateDataColorCursorHasValue RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR_HAS_VALUE

	// RenderStateDataColorPalette is the active 256-color palette
	// (GhosttyColorRgb[256]).
	RenderStateDataColorPalette RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_COLOR_PALETTE

	// RenderStateDataCursorVisualStyle is the visual style of the cursor
	// (GhosttyRenderStateCursorVisualStyle).
	RenderStateDataCursorVisualStyle RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE

	// RenderStateDataCursorVisible indicates whether the cursor is visible
	// based on terminal modes (bool).
	RenderStateDataCursorVisible RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_CURSOR_VISIBLE

	// RenderStateDataCursorBlinking indicates whether the cursor should
	// blink based on terminal modes (bool).
	RenderStateDataCursorBlinking RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_CURSOR_BLINKING

	// RenderStateDataCursorPasswordInput indicates whether the cursor is
	// at a password input field (bool).
	RenderStateDataCursorPasswordInput RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_CURSOR_PASSWORD_INPUT

	// RenderStateDataCursorViewportHasValue indicates whether the cursor
	// is visible within the viewport (bool).
	RenderStateDataCursorViewportHasValue RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_HAS_VALUE

	// RenderStateDataCursorViewportX is the cursor viewport x position
	// in cells (uint16_t).
	RenderStateDataCursorViewportX RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_X

	// RenderStateDataCursorViewportY is the cursor viewport y position
	// in cells (uint16_t).
	RenderStateDataCursorViewportY RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_Y

	// RenderStateDataCursorViewportWideTail indicates whether the cursor
	// is on the tail of a wide character (bool).
	RenderStateDataCursorViewportWideTail RenderStateData = C.GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_WIDE_TAIL
)

type RenderStateDirty 

type RenderStateDirty int

RenderStateDirty describes the dirty state after an update. C: GhosttyRenderStateDirty 

const (
	// RenderStateDirtyFalse means not dirty; rendering can be skipped.
	RenderStateDirtyFalse RenderStateDirty = C.GHOSTTY_RENDER_STATE_DIRTY_FALSE

	// RenderStateDirtyPartial means some rows changed; renderer can
	// redraw incrementally.
	RenderStateDirtyPartial RenderStateDirty = C.GHOSTTY_RENDER_STATE_DIRTY_PARTIAL

	// RenderStateDirtyFull means global state changed; renderer should
	// redraw everything.
	RenderStateDirtyFull RenderStateDirty = C.GHOSTTY_RENDER_STATE_DIRTY_FULL
)

type RenderStateRowCells 

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

RenderStateRowCells iterates over cells in a render-state row. Create one with NewRenderStateRowCells, populate it via RenderStateRowIterator.Cells, then advance with RenderStateRowCells.Next (or jump with RenderStateRowCells.Select) and read data with getter methods.

A single instance can be reused across rows to avoid repeated allocation. The cells view is only valid until the next call to RenderState.Update. Do not use it while RenderState.Update may run on the same render state. Extracted Cell, Style, color values, and grapheme slices are copied values and may be retained.

C: GhosttyRenderStateRowCells

func NewRenderStateRowCells 

func NewRenderStateRowCells() (*RenderStateRowCells, error)

NewRenderStateRowCells creates a new row cells instance. The instance is empty until populated via RenderStateRowIterator.Cells.

func (*RenderStateRowCells) BgColor 

func (rc *RenderStateRowCells) BgColor() (*ColorRGB, error)

BgColor returns the resolved background color for the current cell. Returns nil (without error) when the cell has no background color, in which case the caller should use the terminal default background.

func (*RenderStateRowCells) Close 

func (rc *RenderStateRowCells) Close()

Close frees the underlying row cells handle. After this call, the instance must not be used.

func (*RenderStateRowCells) FgColor 

func (rc *RenderStateRowCells) FgColor() (*ColorRGB, error)

FgColor returns the resolved foreground color for the current cell. Returns nil (without error) when the cell has no explicit foreground color, in which case the caller should use the terminal default foreground. Bold color handling is not applied.

func (*RenderStateRowCells) GetMulti 

func (rc *RenderStateRowCells) GetMulti(keys []RenderStateRowCellsData, values []unsafe.Pointer) error

GetMulti queries multiple render-state cell data fields in a single cgo call. This is a low-level function; prefer the typed getters (Raw, Style, Graphemes, BgColor, FgColor) for normal use. GetMulti is useful when you need many fields at once and want to avoid per-field cgo overhead.

Each element in keys specifies a data kind, and the corresponding element in values must be an unsafe.Pointer to a variable whose type matches the "Output type" documented for that key in the upstream C header (ghostty/vt/render.h, GhosttyRenderStateRowCellsData enum).

Example: 

var raw C.GhosttyCell
var graphemesLen C.uint32_t
err := rc.GetMulti(
	[]RenderStateRowCellsData{RenderStateRowCellsDataRaw, RenderStateRowCellsDataGraphemesLen},
	[]unsafe.Pointer{unsafe.Pointer(&raw), unsafe.Pointer(&graphemesLen)},
)

C: ghostty_render_state_row_cells_get_multi

func (*RenderStateRowCells) Graphemes 

func (rc *RenderStateRowCells) Graphemes() ([]uint32, error)

Graphemes returns the full grapheme cluster codepoints for the current cell. The base codepoint is first, followed by any extra codepoints. Returns nil if the cell has no text.

func (*RenderStateRowCells) Next 

func (rc *RenderStateRowCells) Next() bool

Next advances the iterator to the next cell. Returns true if the iterator moved successfully and cell data is available. Returns false when there are no more cells.

func (*RenderStateRowCells) Raw 

func (rc *RenderStateRowCells) Raw() (*Cell, error)

Raw returns the raw Cell value for the current iterator position. The returned Cell can be used with the same getter methods as cells obtained from GridRef.

func (*RenderStateRowCells) Select 

func (rc *RenderStateRowCells) Select(x uint16) error

Select positions the iterator at the given column index (0-based) so that subsequent reads return data for that cell.

func (*RenderStateRowCells) Style 

func (rc *RenderStateRowCells) Style() (*Style, error)

Style returns the style for the current cell.

type RenderStateRowCellsData 

type RenderStateRowCellsData int

RenderStateRowCellsData identifies a data field for render state cell queries. C: GhosttyRenderStateRowCellsData 

const (
	// RenderStateRowCellsDataInvalid is an invalid / sentinel value.
	RenderStateRowCellsDataInvalid RenderStateRowCellsData = C.GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_INVALID

	// RenderStateRowCellsDataRaw is the raw cell value (GhosttyCell).
	RenderStateRowCellsDataRaw RenderStateRowCellsData = C.GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_RAW

	// RenderStateRowCellsDataStyle is the style for the current cell
	// (GhosttyStyle).
	RenderStateRowCellsDataStyle RenderStateRowCellsData = C.GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_STYLE

	// RenderStateRowCellsDataGraphemesLen is the total number of grapheme
	// codepoints including the base codepoint (uint32_t).
	RenderStateRowCellsDataGraphemesLen RenderStateRowCellsData = C.GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_LEN

	// RenderStateRowCellsDataGraphemesBuf writes grapheme codepoints into
	// a caller-provided buffer (uint32_t*).
	RenderStateRowCellsDataGraphemesBuf RenderStateRowCellsData = C.GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF

	// RenderStateRowCellsDataBgColor is the resolved background color of
	// the cell (GhosttyColorRgb).
	RenderStateRowCellsDataBgColor RenderStateRowCellsData = C.GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_BG_COLOR

	// RenderStateRowCellsDataFgColor is the resolved foreground color of
	// the cell (GhosttyColorRgb).
	RenderStateRowCellsDataFgColor RenderStateRowCellsData = C.GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_FG_COLOR
)

type RenderStateRowData 

type RenderStateRowData int

RenderStateRowData identifies a data field for render state row queries. C: GhosttyRenderStateRowData 

const (
	// RenderStateRowDataInvalid is an invalid / sentinel value.
	RenderStateRowDataInvalid RenderStateRowData = C.GHOSTTY_RENDER_STATE_ROW_DATA_INVALID

	// RenderStateRowDataDirty indicates whether the current row is dirty
	// (bool).
	RenderStateRowDataDirty RenderStateRowData = C.GHOSTTY_RENDER_STATE_ROW_DATA_DIRTY

	// RenderStateRowDataRaw is the raw row value (GhosttyRow).
	RenderStateRowDataRaw RenderStateRowData = C.GHOSTTY_RENDER_STATE_ROW_DATA_RAW

	// RenderStateRowDataCells populates a pre-allocated row cells instance
	// (GhosttyRenderStateRowCells).
	RenderStateRowDataCells RenderStateRowData = C.GHOSTTY_RENDER_STATE_ROW_DATA_CELLS
)

type RenderStateRowIterator 

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

RenderStateRowIterator iterates over rows in a render state. Create one with NewRenderStateRowIterator, populate it via RenderState.RowIterator, then advance with RenderStateRowIterator.Next and read data with getter methods.

The iterator's current position is only valid as long as the underlying render state is not updated. Do not use the iterator while RenderState.Update may run on the same render state. Extracted Row values are copied snapshots and may be retained after the iterator itself becomes invalid.

C: GhosttyRenderStateRowIterator

func NewRenderStateRowIterator 

func NewRenderStateRowIterator() (*RenderStateRowIterator, error)

NewRenderStateRowIterator creates a new row iterator instance. The iterator is empty until populated via RenderState.RowIterator.

func (*RenderStateRowIterator) Cells 

func (ri *RenderStateRowIterator) Cells(rc *RenderStateRowCells) error

Cells populates a pre-allocated row cells instance with cell data for the current row. The cells instance can then be advanced with Next or positioned with Select.

The cells instance can be reused across rows. Cell data is only valid until the next call to RenderState.Update.

func (*RenderStateRowIterator) Close 

func (ri *RenderStateRowIterator) Close()

Close frees the underlying row iterator handle. After this call, the iterator must not be used.

func (*RenderStateRowIterator) Dirty 

func (ri *RenderStateRowIterator) Dirty() (bool, error)

Dirty reports whether the current row is dirty and requires a redraw.

func (*RenderStateRowIterator) GetMulti 

func (ri *RenderStateRowIterator) GetMulti(keys []RenderStateRowData, values []unsafe.Pointer) error

GetMulti queries multiple render-state row data fields in a single cgo call. This is a low-level function; prefer the typed getters (Dirty, Raw, Cells) for normal use. GetMulti is useful when you need many fields at once and want to avoid per-field cgo overhead.

Each element in keys specifies a data kind, and the corresponding element in values must be an unsafe.Pointer to a variable whose type matches the "Output type" documented for that key in the upstream C header (ghostty/vt/render.h, GhosttyRenderStateRowData enum).

Example: 

var dirty C.bool
var raw C.GhosttyRow
err := ri.GetMulti(
	[]RenderStateRowData{RenderStateRowDataDirty, RenderStateRowDataRaw},
	[]unsafe.Pointer{unsafe.Pointer(&dirty), unsafe.Pointer(&raw)},
)

C: ghostty_render_state_row_get_multi

func (*RenderStateRowIterator) Next 

func (ri *RenderStateRowIterator) Next() bool

Next advances the iterator to the next row. Returns true if the iterator moved successfully and row data is available. Returns false when there are no more rows.

func (*RenderStateRowIterator) Raw 

func (ri *RenderStateRowIterator) Raw() (*Row, error)

Raw returns the raw Row value for the current iterator position. The returned Row can be used with the same getter methods as rows obtained from GridRef.

func (*RenderStateRowIterator) SetDirty 

func (ri *RenderStateRowIterator) SetDirty(dirty bool) error

SetDirty sets the dirty state for the current row.

type Result 

type Result int

Result represents a Ghostty result code.

C: GhosttyResult 

const (
	ResultSuccess      Result = C.GHOSTTY_SUCCESS
	ResultOutOfMemory  Result = C.GHOSTTY_OUT_OF_MEMORY
	ResultInvalidValue Result = C.GHOSTTY_INVALID_VALUE
	ResultOutOfSpace   Result = C.GHOSTTY_OUT_OF_SPACE
	ResultNoValue      Result = C.GHOSTTY_NO_VALUE
)

type Row 

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

Row is a wrapper around an opaque terminal grid row value. Use getter methods to extract data from it. A Row is a copied value snapshot, not a borrowed handle, so it may be retained after the GridRef or render-state iterator that produced it becomes invalid. C: GhosttyRow

func (*Row) Dirty 

func (r *Row) Dirty() (bool, error)

Dirty reports whether the row is dirty and requires a redraw.

func (*Row) GetMulti 

func (r *Row) GetMulti(keys []RowData, values []unsafe.Pointer) error

GetMulti queries multiple row data fields in a single cgo call. This is a low-level function; prefer the typed getters (Wrap, Grapheme, Styled, Semantic, etc.) for normal use. GetMulti is useful when you need many fields at once and want to avoid per-field cgo overhead.

Each element in keys specifies a data kind, and the corresponding element in values must be an unsafe.Pointer to a variable whose type matches the "Output type" documented for that key in the upstream C header (ghostty/vt/screen.h, GhosttyRowData enum).

Example: 

var wrap, styled C.bool
err := row.GetMulti(
	[]RowData{RowDataWrap, RowDataStyled},
	[]unsafe.Pointer{unsafe.Pointer(&wrap), unsafe.Pointer(&styled)},
)

C: ghostty_row_get_multi

func (*Row) Grapheme 

func (r *Row) Grapheme() (bool, error)

Grapheme reports whether any cells in the row have grapheme clusters. 

func (r *Row) Hyperlink() (bool, error)

Hyperlink reports whether any cells in the row have hyperlinks (may have false positives).

func (*Row) KittyVirtualPlaceholder 

func (r *Row) KittyVirtualPlaceholder() (bool, error)

KittyVirtualPlaceholder reports whether the row contains a Kitty virtual placeholder.

func (*Row) Semantic 

func (r *Row) Semantic() (RowSemanticPrompt, error)

Semantic returns the semantic prompt state of the row.

func (*Row) Styled 

func (r *Row) Styled() (bool, error)

Styled reports whether any cells in the row have styling (may have false positives).

func (*Row) Wrap 

func (r *Row) Wrap() (bool, error)

Wrap reports whether the row is soft-wrapped.

func (*Row) WrapContinuation 

func (r *Row) WrapContinuation() (bool, error)

WrapContinuation reports whether the row is a continuation of a soft-wrapped row.

type RowData 

type RowData int

RowData identifies a data field for row queries. C: GhosttyRowData 

const (
	// RowDataInvalid is an invalid data type.
	RowDataInvalid RowData = C.GHOSTTY_ROW_DATA_INVALID

	// RowDataWrap indicates whether the row is soft-wrapped (bool).
	RowDataWrap RowData = C.GHOSTTY_ROW_DATA_WRAP

	// RowDataWrapContinuation indicates whether the row is a continuation
	// of a soft-wrapped row (bool).
	RowDataWrapContinuation RowData = C.GHOSTTY_ROW_DATA_WRAP_CONTINUATION

	// RowDataGrapheme indicates whether any cells in the row have grapheme
	// clusters (bool).
	RowDataGrapheme RowData = C.GHOSTTY_ROW_DATA_GRAPHEME

	// RowDataStyled indicates whether any cells in the row have styling
	// (bool).
	RowDataStyled RowData = C.GHOSTTY_ROW_DATA_STYLED

	// RowDataHyperlink indicates whether any cells in the row have
	// hyperlinks (bool).
	RowDataHyperlink RowData = C.GHOSTTY_ROW_DATA_HYPERLINK

	// RowDataSemanticPrompt is the semantic prompt state of the row
	// (GhosttyRowSemanticPrompt).
	RowDataSemanticPrompt RowData = C.GHOSTTY_ROW_DATA_SEMANTIC_PROMPT

	// RowDataKittyVirtualPlaceholder indicates whether the row contains
	// a Kitty virtual placeholder (bool).
	RowDataKittyVirtualPlaceholder RowData = C.GHOSTTY_ROW_DATA_KITTY_VIRTUAL_PLACEHOLDER

	// RowDataDirty indicates whether the row is dirty and requires a
	// redraw (bool).
	RowDataDirty RowData = C.GHOSTTY_ROW_DATA_DIRTY
)

type RowSemanticPrompt 

type RowSemanticPrompt int

RowSemanticPrompt indicates whether any cells in a row are part of a shell prompt, as reported by OSC 133 sequences. C: GhosttyRowSemanticPrompt 

const (
	// RowSemanticNone means no prompt cells in this row.
	RowSemanticNone RowSemanticPrompt = C.GHOSTTY_ROW_SEMANTIC_NONE

	// RowSemanticPromptPrimary means prompt cells exist and this is a
	// primary prompt line.
	RowSemanticPromptPrimary RowSemanticPrompt = C.GHOSTTY_ROW_SEMANTIC_PROMPT

	// RowSemanticPromptContinuation means prompt cells exist and this is
	// a continuation line.
	RowSemanticPromptContinuation RowSemanticPrompt = C.GHOSTTY_ROW_SEMANTIC_PROMPT_CONTINUATION
)

type ScrollViewportTag 

type ScrollViewportTag int

ScrollViewportTag describes the scroll behavior. C: GhosttyTerminalScrollViewportTag 

const (
	// ScrollViewportTop scrolls to the top of scrollback.
	ScrollViewportTop ScrollViewportTag = C.GHOSTTY_SCROLL_VIEWPORT_TOP

	// ScrollViewportBottom scrolls to the bottom (active area).
	ScrollViewportBottom ScrollViewportTag = C.GHOSTTY_SCROLL_VIEWPORT_BOTTOM

	// ScrollViewportDelta scrolls by a delta amount (up is negative).
	ScrollViewportDelta ScrollViewportTag = C.GHOSTTY_SCROLL_VIEWPORT_DELTA
)

type Scrollbar 

type Scrollbar struct {
	// Total is the total size of the scrollable area in rows.
	Total uint64

	// Offset is the offset into the total area that the viewport is at.
	Offset uint64

	// Len is the length of the visible area in rows.
	Len uint64
}

Scrollbar holds the scrollbar state for the terminal viewport. C: GhosttyTerminalScrollbar

type Selection 

type Selection struct {
	// Start is the start of the selection range (inclusive).
	Start GridRef

	// End is the end of the selection range (inclusive).
	End GridRef

	// Rectangle indicates whether the selection is rectangular (block)
	// rather than linear.
	Rectangle bool
}

Selection represents a grid selection range defined by two grid references. Because Start and End are GridRef values, a Selection returned by Kitty graphics helpers is also a borrowed view and is invalidated by the next mutation of the owning terminal.

C: GhosttySelection

type SizeFn 

type SizeFn func(t *Terminal) (SizeReportSize, bool)

SizeFn is called for XTWINOPS size queries (CSI 14/16/18 t). The first parameter is the terminal that triggered the effect. Return the size and true, or zero value and false to ignore the query. C: GhosttyTerminalSizeFn

type SizeReportSize 

type SizeReportSize struct {
	// Rows is the terminal row count in cells.
	Rows uint16

	// Columns is the terminal column count in cells.
	Columns uint16

	// CellWidth is the width of a single terminal cell in pixels.
	CellWidth uint32

	// CellHeight is the height of a single terminal cell in pixels.
	CellHeight uint32
}

SizeReportSize holds terminal geometry for XTWINOPS size queries. C: GhosttySizeReportSize

type SizeReportStyle 

type SizeReportStyle int

SizeReportStyle determines the output format for a terminal size report. C: GhosttySizeReportStyle 

const (
	// SizeReportMode2048 is the in-band size report (mode 2048).
	SizeReportMode2048 SizeReportStyle = C.GHOSTTY_SIZE_REPORT_MODE_2048

	// SizeReportCSI14T is the XTWINOPS text area size in pixels.
	SizeReportCSI14T SizeReportStyle = C.GHOSTTY_SIZE_REPORT_CSI_14_T

	// SizeReportCSI16T is the XTWINOPS cell size in pixels.
	SizeReportCSI16T SizeReportStyle = C.GHOSTTY_SIZE_REPORT_CSI_16_T

	// SizeReportCSI18T is the XTWINOPS text area size in characters.
	SizeReportCSI18T SizeReportStyle = C.GHOSTTY_SIZE_REPORT_CSI_18_T
)

type Style 

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

Style is a thin wrapper around the copied C GhosttyStyle value. It provides getter methods to access individual style attributes without copying the entire struct upfront. A Style is a value snapshot and may be retained after the terminal, GridRef, or render-state iterator that produced it becomes invalid. C: GhosttyStyle

func (*Style) BgColor 

func (s *Style) BgColor() StyleColor

BgColor returns the background color. 

func (s *Style) Blink() bool

Blink reports whether blink is set.

func (*Style) Bold 

func (s *Style) Bold() bool

Bold reports whether bold is set.

func (*Style) Faint 

func (s *Style) Faint() bool

Faint reports whether faint (dim) is set.

func (*Style) FgColor 

func (s *Style) FgColor() StyleColor

FgColor returns the foreground color.

func (*Style) Inverse 

func (s *Style) Inverse() bool

Inverse reports whether inverse video is set.

func (*Style) Invisible 

func (s *Style) Invisible() bool

Invisible reports whether invisible is set.

func (*Style) IsDefault 

func (s *Style) IsDefault() bool

IsDefault reports whether the style is the default style (no colors, no flags).

func (*Style) Italic 

func (s *Style) Italic() bool

Italic reports whether italic is set.

func (*Style) Overline 

func (s *Style) Overline() bool

Overline reports whether overline is set.

func (*Style) Strikethrough 

func (s *Style) Strikethrough() bool

Strikethrough reports whether strikethrough is set.

func (*Style) Underline 

func (s *Style) Underline() int

Underline returns the underline style (one of the Underline* constants).

func (*Style) UnderlineColor 

func (s *Style) UnderlineColor() StyleColor

UnderlineColor returns the underline color.

type StyleColor 

type StyleColor struct {
	// Tag identifies the type of color.
	Tag StyleColorTag

	// Palette is the palette index (valid when Tag is StyleColorPalette).
	Palette uint8

	// RGB is the direct RGB color (valid when Tag is StyleColorRGB).
	RGB ColorRGB
}

StyleColor is a tagged union representing a color in a style attribute. Check Tag to determine which field is valid. C: GhosttyStyleColor

type StyleColorTag 

type StyleColorTag int

StyleColorTag identifies the type of color in a style color. C: GhosttyStyleColorTag 

const (
	// StyleColorNone means no color is set.
	StyleColorNone StyleColorTag = C.GHOSTTY_STYLE_COLOR_NONE

	// StyleColorPalette means the color is a palette index.
	StyleColorPalette StyleColorTag = C.GHOSTTY_STYLE_COLOR_PALETTE

	// StyleColorRGB means the color is a direct RGB value.
	StyleColorRGB StyleColorTag = C.GHOSTTY_STYLE_COLOR_RGB
)

type SysDecodePngFn 

type SysDecodePngFn func(data []byte) (*SysImage, error)

SysDecodePngFn is the Go callback type for PNG decoding. It receives raw PNG data and must return a decoded SysImage. The returned pixel data will be copied into library-managed memory; the caller does not need to keep the slice alive after returning.

Return a non-nil error to indicate decode failure. C: GhosttySysDecodePngFn

type SysImage 

type SysImage struct {
	// Width of the decoded image in pixels.
	Width uint32

	// Height of the decoded image in pixels.
	Height uint32

	// Data is the decoded RGBA pixel data (4 bytes per pixel).
	Data []byte
}

SysImage holds the result of decoding an image (e.g. PNG) into raw RGBA pixel data. Returned by the user-supplied decode callback. C: GhosttySysImage

type SysLogFn 

type SysLogFn func(level SysLogLevel, scope string, message string)

SysLogFn is the Go callback type for log messages from the library. The scope identifies the subsystem (e.g. "osc", "kitty"); it is empty for unscoped (default) log messages. The message and scope are only valid for the duration of the call. C: GhosttySysLogFn

type SysLogLevel 

type SysLogLevel int

SysLogLevel represents the severity level of a log message from the library. Maps directly to the C enum values. C: GhosttySysLogLevel 

const (
	// SysLogLevelError is the error log level.
	SysLogLevelError SysLogLevel = C.GHOSTTY_SYS_LOG_LEVEL_ERROR

	// SysLogLevelWarning is the warning log level.
	SysLogLevelWarning SysLogLevel = C.GHOSTTY_SYS_LOG_LEVEL_WARNING

	// SysLogLevelInfo is the info log level.
	SysLogLevelInfo SysLogLevel = C.GHOSTTY_SYS_LOG_LEVEL_INFO

	// SysLogLevelDebug is the debug log level.
	SysLogLevelDebug SysLogLevel = C.GHOSTTY_SYS_LOG_LEVEL_DEBUG
)

func (SysLogLevel) String 

func (l SysLogLevel) String() string

String returns a human-readable name for the log level.

type Terminal 

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

Terminal wraps a Ghostty VT terminal handle. It is stateful, not safe for concurrent use, and not reentrant. Serialize all calls that touch a terminal, including getters, setters, Terminal.VTWrite, Terminal.Resize, Terminal.Close, and any borrowed handles derived from it. Effect callbacks run synchronously during Terminal.VTWrite; they must not call Terminal.VTWrite on the same terminal and should avoid blocking for long periods. C: GhosttyTerminal

func NewTerminal 

func NewTerminal(opts ...TerminalOption) (*Terminal, error)

NewTerminal creates a new terminal with the given options. WithSize is required; cols and rows must both be greater than zero.

func (*Terminal) ActiveScreen 

func (t *Terminal) ActiveScreen() (TerminalScreen, error)

ActiveScreen returns which screen buffer is currently active.

func (*Terminal) Close 

func (t *Terminal) Close()

Close frees the underlying terminal handle and releases the cgo.Handle. After this call, the terminal must not be used.

func (*Terminal) ColorBackground 

func (t *Terminal) ColorBackground() (*ColorRGB, error)

ColorBackground returns the effective background color (OSC override or default). Returns nil if no background color is set.

func (*Terminal) ColorBackgroundDefault 

func (t *Terminal) ColorBackgroundDefault() (*ColorRGB, error)

ColorBackgroundDefault returns the default background color, ignoring any OSC override. Returns nil if no default is set.

func (*Terminal) ColorCursor 

func (t *Terminal) ColorCursor() (*ColorRGB, error)

ColorCursor returns the effective cursor color (OSC override or default). Returns nil if no cursor color is set.

func (*Terminal) ColorCursorDefault 

func (t *Terminal) ColorCursorDefault() (*ColorRGB, error)

ColorCursorDefault returns the default cursor color, ignoring any OSC override. Returns nil if no default is set.

func (*Terminal) ColorForeground 

func (t *Terminal) ColorForeground() (*ColorRGB, error)

ColorForeground returns the effective foreground color (OSC override or default). Returns nil if no foreground color is set.

func (*Terminal) ColorForegroundDefault 

func (t *Terminal) ColorForegroundDefault() (*ColorRGB, error)

ColorForegroundDefault returns the default foreground color, ignoring any OSC override. Returns nil if no default is set.

func (*Terminal) ColorPalette 

func (t *Terminal) ColorPalette() (*Palette, error)

ColorPalette returns the current 256-color palette (with any OSC overrides applied).

func (*Terminal) ColorPaletteDefault 

func (t *Terminal) ColorPaletteDefault() (*Palette, error)

ColorPaletteDefault returns the default 256-color palette, ignoring any OSC overrides.

func (*Terminal) Cols 

func (t *Terminal) Cols() (uint16, error)

Cols returns the terminal width in cells.

func (*Terminal) CursorPendingWrap 

func (t *Terminal) CursorPendingWrap() (bool, error)

CursorPendingWrap reports whether the cursor has a pending wrap (the next printed character will soft-wrap to the next line).

func (*Terminal) CursorStyle 

func (t *Terminal) CursorStyle() (*Style, error)

CursorStyle returns the current SGR style of the cursor. This is the style that will be applied to newly printed characters.

func (*Terminal) CursorVisible 

func (t *Terminal) CursorVisible() (bool, error)

CursorVisible reports whether the cursor is visible (DEC mode 25).

func (*Terminal) CursorX 

func (t *Terminal) CursorX() (uint16, error)

CursorX returns the cursor column position (0-indexed).

func (*Terminal) CursorY 

func (t *Terminal) CursorY() (uint16, error)

CursorY returns the cursor row position within the active area (0-indexed).

func (*Terminal) GetMulti 

func (t *Terminal) GetMulti(keys []TerminalData, values []unsafe.Pointer) error

GetMulti queries multiple terminal data fields in a single cgo call. This is a low-level function; prefer the typed getters (Cols, Rows, CursorX, etc.) for normal use. GetMulti is useful when you need many fields at once and want to avoid per-field cgo overhead.

Each element in keys specifies a data kind, and the corresponding element in values must be an unsafe.Pointer to a variable whose type matches the "Output type" documented for that key in the upstream C header (ghostty/vt/terminal.h, GhosttyTerminalData enum).

Example: 

var cols, rows C.uint16_t
err := t.GetMulti(
	[]TerminalData{TerminalDataCols, TerminalDataRows},
	[]unsafe.Pointer{unsafe.Pointer(&cols), unsafe.Pointer(&rows)},
)

C: ghostty_terminal_get_multi

func (*Terminal) GridRef 

func (t *Terminal) GridRef(point Point) (*GridRef, error)

GridRef resolves a point in the terminal grid to a grid reference. The returned GridRef is borrowed from terminal internals and should be used immediately; any later terminal operation may invalidate it.

Lookups using PointTagActive and PointTagViewport are fast. PointTagScreen and PointTagHistory may be expensive for large scrollback buffers.

func (*Terminal) HeightPx 

func (t *Terminal) HeightPx() (uint32, error)

HeightPx returns the total terminal height in pixels (rows * cell_height_px as set by Resize).

func (*Terminal) KittyGraphics 

func (t *Terminal) KittyGraphics() (*KittyGraphics, error)

KittyGraphics returns the Kitty graphics image storage for the terminal's active screen. The returned handle is borrowed from the terminal and remains valid until the next mutating call (for example Terminal.VTWrite or Terminal.Reset). Serialize use of the returned handle with mutations of the terminal.

func (*Terminal) KittyKeyboardFlags 

func (t *Terminal) KittyKeyboardFlags() (KittyKeyFlags, error)

KittyKeyboardFlags returns the current Kitty keyboard protocol flags.

func (*Terminal) ModeGet 

func (t *Terminal) ModeGet(mode Mode) (bool, error)

ModeGet returns the current value of a terminal mode.

func (*Terminal) ModeSet 

func (t *Terminal) ModeSet(mode Mode, value bool) error

ModeSet sets a terminal mode to the given value.

func (*Terminal) MouseTracking 

func (t *Terminal) MouseTracking() (bool, error)

MouseTracking reports whether any mouse tracking mode is active.

func (*Terminal) Pwd 

func (t *Terminal) Pwd() (string, error)

Pwd returns the terminal's current working directory as set by escape sequences (e.g. OSC 7). Returns an empty string if unset. The returned string is copied; it remains valid after subsequent calls to VTWrite or Reset.

func (*Terminal) Reset 

func (t *Terminal) Reset()

Reset performs a full terminal reset (RIS). All state is reset to initial configuration (modes, scrollback, scrolling region, screen contents). Dimensions are preserved.

func (*Terminal) Resize 

func (t *Terminal) Resize(cols, rows uint16, cellWidthPx, cellHeightPx uint32) error

Resize changes the terminal dimensions. Both cols and rows must be greater than zero. cellWidthPx and cellHeightPx specify the pixel dimensions of a single cell, used for image protocols and size reports.

func (*Terminal) Rows 

func (t *Terminal) Rows() (uint16, error)

Rows returns the terminal height in cells.

func (*Terminal) ScrollViewportBottom 

func (t *Terminal) ScrollViewportBottom()

ScrollViewportBottom scrolls the terminal viewport to the bottom (active area).

func (*Terminal) ScrollViewportDelta 

func (t *Terminal) ScrollViewportDelta(delta int)

ScrollViewportDelta scrolls the terminal viewport by the given delta (negative for up, positive for down).

func (*Terminal) ScrollViewportTop 

func (t *Terminal) ScrollViewportTop()

ScrollViewport scrolls the terminal viewport to the top of scrollback.

func (*Terminal) ScrollbackRows 

func (t *Terminal) ScrollbackRows() (uint, error)

ScrollbackRows returns the number of scrollback rows (total rows minus viewport rows).

func (*Terminal) Scrollbar 

func (t *Terminal) Scrollbar() (Scrollbar, error)

Scrollbar returns the scrollbar state for the terminal viewport. This may be expensive to calculate depending on the viewport position; call only as needed.

func (*Terminal) SetColorBackground 

func (t *Terminal) SetColorBackground(c *ColorRGB) error

SetColorBackground sets the default background color. Pass nil to clear (unset).

func (*Terminal) SetColorCursor 

func (t *Terminal) SetColorCursor(c *ColorRGB) error

SetColorCursor sets the default cursor color. Pass nil to clear (unset).

func (*Terminal) SetColorForeground 

func (t *Terminal) SetColorForeground(c *ColorRGB) error

SetColorForeground sets the default foreground color. Pass nil to clear (unset).

func (*Terminal) SetColorPalette 

func (t *Terminal) SetColorPalette(palette *Palette) error

SetColorPalette sets the default 256-color palette. Pass nil to reset to the built-in default palette.

func (*Terminal) SetEffectBell 

func (t *Terminal) SetEffectBell(fn BellFn)

SetEffectBell registers (or clears) the bell effect on a live terminal. Pass nil to clear.

func (*Terminal) SetEffectColorScheme 

func (t *Terminal) SetEffectColorScheme(fn ColorSchemeFn)

SetEffectColorScheme registers (or clears) the color-scheme effect on a live terminal. Pass nil to clear.

func (*Terminal) SetEffectDeviceAttributes 

func (t *Terminal) SetEffectDeviceAttributes(fn DeviceAttributesFn)

SetEffectDeviceAttributes registers (or clears) the device-attributes effect on a live terminal. Pass nil to clear.

func (*Terminal) SetEffectEnquiry 

func (t *Terminal) SetEffectEnquiry(fn EnquiryFn)

SetEffectEnquiry registers (or clears) the enquiry effect on a live terminal. Pass nil to clear.

func (*Terminal) SetEffectSize 

func (t *Terminal) SetEffectSize(fn SizeFn)

SetEffectSize registers (or clears) the size-report effect on a live terminal. Pass nil to clear.

func (*Terminal) SetEffectTitleChanged 

func (t *Terminal) SetEffectTitleChanged(fn TitleChangedFn)

SetEffectTitleChanged registers (or clears) the title-changed effect on a live terminal. Pass nil to clear.

func (*Terminal) SetEffectWritePty 

func (t *Terminal) SetEffectWritePty(fn WritePtyFn)

SetEffectWritePty registers (or clears) the write-pty effect on a live terminal. Pass nil to clear.

func (*Terminal) SetEffectXtversion 

func (t *Terminal) SetEffectXtversion(fn XtversionFn)

SetEffectXtversion registers (or clears) the xtversion effect on a live terminal. Pass nil to clear.

func (*Terminal) SetKittyImageMediumFile 

func (t *Terminal) SetKittyImageMediumFile(enabled bool) error

SetKittyImageMediumFile enables or disables Kitty image loading via the file medium.

func (*Terminal) SetKittyImageMediumSharedMem 

func (t *Terminal) SetKittyImageMediumSharedMem(enabled bool) error

SetKittyImageMediumSharedMem enables or disables Kitty image loading via the shared memory medium.

func (*Terminal) SetKittyImageMediumTempFile 

func (t *Terminal) SetKittyImageMediumTempFile(enabled bool) error

SetKittyImageMediumTempFile enables or disables Kitty image loading via the temporary file medium.

func (*Terminal) SetKittyImageStorageLimit 

func (t *Terminal) SetKittyImageStorageLimit(limit *uint64) error

SetKittyImageStorageLimit sets the Kitty image storage limit in bytes. Applied to all initialized screens (primary and alternate). A value of zero disables the Kitty graphics protocol entirely, deleting all stored images and placements. Pass nil to disable (equivalent to zero).

func (*Terminal) SetPwd 

func (t *Terminal) SetPwd(pwd string) error

SetPwd sets the terminal working directory manually. An empty string clears it.

func (*Terminal) SetTitle 

func (t *Terminal) SetTitle(title string) error

SetTitle sets the terminal title manually. An empty string clears it.

func (*Terminal) Title 

func (t *Terminal) Title() (string, error)

Title returns the terminal title as set by escape sequences (e.g. OSC 0/2). Returns an empty string if unset. The returned string is copied; it remains valid after subsequent calls to VTWrite or Reset.

func (*Terminal) TotalRows 

func (t *Terminal) TotalRows() (uint, error)

TotalRows returns the total number of rows in the active screen including scrollback.

func (*Terminal) VTWrite 

func (t *Terminal) VTWrite(data []byte)

VTWrite feeds raw VT-encoded bytes through the terminal's parser, updating terminal state. Malformed input is handled gracefully and will not cause an error. Effect callbacks run synchronously before this call returns; they must not call Terminal.VTWrite on the same terminal.

func (*Terminal) WidthPx 

func (t *Terminal) WidthPx() (uint32, error)

WidthPx returns the total terminal width in pixels (cols * cell_width_px as set by Resize).

func (*Terminal) Write 

func (t *Terminal) Write(p []byte) (int, error)

Write implements io.Writer by feeding data through the terminal's VT parser. It always consumes all bytes and never returns an error.

type TerminalConfig 

type TerminalConfig struct {
	// Cols is the terminal width in cells. Must be greater than zero.
	Cols uint16

	// Rows is the terminal height in cells. Must be greater than zero.
	Rows uint16

	// MaxScrollback is the maximum number of lines to keep in scrollback
	// history. Defaults to 0 (no scrollback).
	MaxScrollback uint
	// contains filtered or unexported fields
}

TerminalConfig holds the configuration for creating a Terminal. It can be passed directly to NewTerminal or built up using functional options like WithSize and WithMaxScrollback. C: GhosttyTerminalOptions

type TerminalData 

type TerminalData int

TerminalData identifies a data field for terminal queries. C: GhosttyTerminalData 

const (
	// TerminalDataInvalid is an invalid / sentinel value.
	TerminalDataInvalid TerminalData = C.GHOSTTY_TERMINAL_DATA_INVALID

	// TerminalDataCols is the terminal width in cells (uint16_t).
	TerminalDataCols TerminalData = C.GHOSTTY_TERMINAL_DATA_COLS

	// TerminalDataRows is the terminal height in cells (uint16_t).
	TerminalDataRows TerminalData = C.GHOSTTY_TERMINAL_DATA_ROWS

	// TerminalDataCursorX is the cursor column position, 0-indexed (uint16_t).
	TerminalDataCursorX TerminalData = C.GHOSTTY_TERMINAL_DATA_CURSOR_X

	// TerminalDataCursorY is the cursor row position within the active area,
	// 0-indexed (uint16_t).
	TerminalDataCursorY TerminalData = C.GHOSTTY_TERMINAL_DATA_CURSOR_Y

	// TerminalDataCursorPendingWrap indicates whether the cursor has a
	// pending wrap (bool).
	TerminalDataCursorPendingWrap TerminalData = C.GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP

	// TerminalDataActiveScreen is the currently active screen
	// (GhosttyTerminalScreen).
	TerminalDataActiveScreen TerminalData = C.GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN

	// TerminalDataCursorVisible indicates whether the cursor is visible,
	// DEC mode 25 (bool).
	TerminalDataCursorVisible TerminalData = C.GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE

	// TerminalDataKittyKeyboardFlags is the current Kitty keyboard protocol
	// flags (uint8_t).
	TerminalDataKittyKeyboardFlags TerminalData = C.GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS

	// TerminalDataScrollbar is the scrollbar state for the terminal viewport
	// (GhosttyTerminalScrollbar).
	TerminalDataScrollbar TerminalData = C.GHOSTTY_TERMINAL_DATA_SCROLLBAR

	// TerminalDataCursorStyle is the current SGR style of the cursor
	// (GhosttyStyle).
	TerminalDataCursorStyle TerminalData = C.GHOSTTY_TERMINAL_DATA_CURSOR_STYLE

	// TerminalDataMouseTracking indicates whether any mouse tracking mode
	// is active (bool).
	TerminalDataMouseTracking TerminalData = C.GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING

	// TerminalDataTitle is the terminal title as set by escape sequences
	// (GhosttyString).
	TerminalDataTitle TerminalData = C.GHOSTTY_TERMINAL_DATA_TITLE

	// TerminalDataPwd is the terminal's current working directory as set
	// by escape sequences (GhosttyString).
	TerminalDataPwd TerminalData = C.GHOSTTY_TERMINAL_DATA_PWD

	// TerminalDataTotalRows is the total number of rows in the active screen
	// including scrollback (size_t).
	TerminalDataTotalRows TerminalData = C.GHOSTTY_TERMINAL_DATA_TOTAL_ROWS

	// TerminalDataScrollbackRows is the number of scrollback rows (size_t).
	TerminalDataScrollbackRows TerminalData = C.GHOSTTY_TERMINAL_DATA_SCROLLBACK_ROWS

	// TerminalDataWidthPx is the total terminal width in pixels (uint32_t).
	TerminalDataWidthPx TerminalData = C.GHOSTTY_TERMINAL_DATA_WIDTH_PX

	// TerminalDataHeightPx is the total terminal height in pixels (uint32_t).
	TerminalDataHeightPx TerminalData = C.GHOSTTY_TERMINAL_DATA_HEIGHT_PX

	// TerminalDataColorForeground is the effective foreground color
	// (GhosttyColorRgb).
	TerminalDataColorForeground TerminalData = C.GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND

	// TerminalDataColorBackground is the effective background color
	// (GhosttyColorRgb).
	TerminalDataColorBackground TerminalData = C.GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND

	// TerminalDataColorCursor is the effective cursor color
	// (GhosttyColorRgb).
	TerminalDataColorCursor TerminalData = C.GHOSTTY_TERMINAL_DATA_COLOR_CURSOR

	// TerminalDataColorPalette is the current 256-color palette
	// (GhosttyColorRgb[256]).
	TerminalDataColorPalette TerminalData = C.GHOSTTY_TERMINAL_DATA_COLOR_PALETTE

	// TerminalDataColorForegroundDefault is the default foreground color,
	// ignoring OSC overrides (GhosttyColorRgb).
	TerminalDataColorForegroundDefault TerminalData = C.GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT

	// TerminalDataColorBackgroundDefault is the default background color,
	// ignoring OSC overrides (GhosttyColorRgb).
	TerminalDataColorBackgroundDefault TerminalData = C.GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT

	// TerminalDataColorCursorDefault is the default cursor color,
	// ignoring OSC overrides (GhosttyColorRgb).
	TerminalDataColorCursorDefault TerminalData = C.GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT

	// TerminalDataColorPaletteDefault is the default 256-color palette,
	// ignoring OSC overrides (GhosttyColorRgb[256]).
	TerminalDataColorPaletteDefault TerminalData = C.GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT

	// TerminalDataKittyImageStorageLimit is the Kitty image storage limit
	// in bytes for the active screen (uint64_t).
	TerminalDataKittyImageStorageLimit TerminalData = C.GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_STORAGE_LIMIT

	// TerminalDataKittyImageMediumFile indicates whether the file medium
	// is enabled for Kitty image loading (bool).
	TerminalDataKittyImageMediumFile TerminalData = C.GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_FILE

	// TerminalDataKittyImageMediumTempFile indicates whether the temporary
	// file medium is enabled for Kitty image loading (bool).
	TerminalDataKittyImageMediumTempFile TerminalData = C.GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE

	// TerminalDataKittyImageMediumSharedMem indicates whether the shared
	// memory medium is enabled for Kitty image loading (bool).
	TerminalDataKittyImageMediumSharedMem TerminalData = C.GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM

	// TerminalDataKittyGraphics is the Kitty graphics image storage for
	// the active screen (GhosttyKittyGraphics).
	TerminalDataKittyGraphics TerminalData = C.GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS
)

type TerminalOption 

type TerminalOption func(*TerminalConfig)

TerminalOption is a functional option for configuring a Terminal.

func WithBell 

func WithBell(fn BellFn) TerminalOption

WithBell registers an effect handler invoked when the terminal receives a BEL character (0x07).

func WithColorScheme 

func WithColorScheme(fn ColorSchemeFn) TerminalOption

WithColorScheme registers an effect handler invoked for color scheme queries (CSI ? 996 n). Return the scheme and true, or zero value and false to silently ignore the query.

func WithDeviceAttributes 

func WithDeviceAttributes(fn DeviceAttributesFn) TerminalOption

WithDeviceAttributes registers an effect handler invoked for device attributes queries (CSI c / CSI > c / CSI = c). Return the attributes and true, or zero value and false to silently ignore the query.

func WithEnquiry 

func WithEnquiry(fn EnquiryFn) TerminalOption

WithEnquiry registers an effect handler invoked when the terminal receives an ENQ character (0x05). Return the response bytes; nil or empty means no response.

func WithMaxScrollback 

func WithMaxScrollback(lines uint) TerminalOption

WithMaxScrollback sets the maximum number of lines to keep in scrollback history. Defaults to 0 (no scrollback).

func WithSize 

func WithSize(cols, rows uint16) TerminalOption

WithSize sets the terminal dimensions in cells. Both cols and rows must be greater than zero.

func WithSizeReport 

func WithSizeReport(fn SizeFn) TerminalOption

WithSizeReport registers an effect handler invoked for XTWINOPS size queries (CSI 14/16/18 t). Return the size and true, or zero value and false to silently ignore the query.

func WithTitleChanged 

func WithTitleChanged(fn TitleChangedFn) TerminalOption

WithTitleChanged registers an effect handler invoked when the terminal title changes via OSC 0 or OSC 2.

func WithWritePty 

func WithWritePty(fn WritePtyFn) TerminalOption

WithWritePty registers an effect handler invoked when the terminal writes data back to the pty (e.g. query responses). The data slice is only valid for the duration of the call.

func WithXtversion 

func WithXtversion(fn XtversionFn) TerminalOption

WithXtversion registers an effect handler invoked for XTVERSION queries (CSI > q). Return the version string; empty uses the default "libghostty" version.

type TerminalScreen 

type TerminalScreen int

TerminalScreen identifies which screen buffer is active. C: GhosttyTerminalScreen 

const (
	// ScreenPrimary is the primary (normal) screen.
	ScreenPrimary TerminalScreen = C.GHOSTTY_TERMINAL_SCREEN_PRIMARY

	// ScreenAlternate is the alternate screen.
	ScreenAlternate TerminalScreen = C.GHOSTTY_TERMINAL_SCREEN_ALTERNATE
)

type TitleChangedFn 

type TitleChangedFn func(t *Terminal)

TitleChangedFn is called when the terminal title changes via OSC 0/2. The parameter is the terminal that triggered the effect. C: GhosttyTerminalTitleChangedFn

type WritePtyFn 

type WritePtyFn func(t *Terminal, data []byte)

WritePtyFn is called when the terminal writes data back to the pty (e.g. query responses). The first parameter is the terminal that triggered the effect. The data is only valid for the call duration. C: GhosttyTerminalWritePtyFn

type XtversionFn 

type XtversionFn func(t *Terminal) string

XtversionFn is called for XTVERSION queries (CSI > q). The first parameter is the terminal that triggered the effect. Return the version string; empty uses the default "libghostty". C: GhosttyTerminalXtversionFn

Source Files

  • alloc.go
  • build_info.go
  • cgo_static.go
  • color.go
  • device.go
  • doc.go
  • focus.go
  • formatter.go
  • get_multi.go
  • grid_ref.go
  • key_encoder.go
  • key_event.go
  • key_string.go
  • kitty_graphics.go
  • mode.go
  • mods_string.go
  • mouse_encoder.go
  • mouse_event.go
  • paste.go
  • point.go
  • render_state.go
  • render_state_cell.go
  • render_state_data.go
  • render_state_row.go
  • result.go
  • screen.go
  • size_report.go
  • style.go
  • sys.go
  • terminal.go
  • terminal_data.go
  • terminal_effect.go
  • terminal_opt.go

Directories

Path Synopsis
examples
build-info command
Example build-info demonstrates querying libghostty's compile-time build configuration using the GetBuildInfo API.
 Example build-info demonstrates querying libghostty's compile-time build configuration using the GetBuildInfo API.
colors command
Command colors demonstrates the libghostty color APIs: setting and querying foreground, background, cursor, and palette colors, as well as the distinction between "effective" (OSC-overridden) and "default" values.
 Command colors demonstrates the libghostty color APIs: setting and querying foreground, background, cursor, and palette colors, as well as the distinction between "effective" (OSC-overridden) and "default" values.
effects command
Example program demonstrating terminal effect callbacks.
 Example program demonstrating terminal effect callbacks.
formatter command
Example program demonstrating the Formatter API from libghostty.
 Example program demonstrating the Formatter API from libghostty.
grid-traverse command
Example grid-traverse demonstrates walking the terminal grid cell-by-cell using the GridRef API to inspect content and style.
 Example grid-traverse demonstrates walking the terminal grid cell-by-cell using the GridRef API to inspect content and style.
modes command
Example: modes demonstrates the Mode API from libghostty.
 Example: modes demonstrates the Mode API from libghostty.
render command
Example render demonstrates the RenderState API by creating a terminal, writing styled VT content, and iterating over the resulting rows and cells to produce ANSI-colored output.
 Example render demonstrates the RenderState API by creating a terminal, writing styled VT content, and iterating over the resulting rows and cells to produce ANSI-colored output.
sys
png
Package png provides a ready-to-use PNG decoder for libghostty using Go's standard image/png package.
 Package png provides a ready-to-use PNG decoder for libghostty using Go's standard image/png package.

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.