GhosttyTerminalOption enum

Terminal option identifiers.

These values are used with ghostty_terminal_set() to configure terminal callbacks and associated state.

@ingroup terminal

Inheritance

• Object
• Enum
• GhosttyTerminalOption

Available extensions

• EnumName

Values

GHOSTTY_TERMINAL_OPT_USERDATA → const GhosttyTerminalOption

Opaque userdata pointer passed to all callbacks.

Input type: void*

const GhosttyTerminalOption(0)

GHOSTTY_TERMINAL_OPT_WRITE_PTY → const GhosttyTerminalOption

Callback invoked when the terminal needs to write data back to the pty (e.g. in response to a DECRQM query, device status report, or VT-driven mode 2048 enable). Set to NULL to ignore such sequences.

Input type: GhosttyTerminalWritePtyFn

const GhosttyTerminalOption(1)

GHOSTTY_TERMINAL_OPT_BELL → const GhosttyTerminalOption

Callback invoked when the terminal receives a BEL character (0x07). Set to NULL to ignore bell events.

Input type: GhosttyTerminalBellFn

const GhosttyTerminalOption(2)

GHOSTTY_TERMINAL_OPT_ENQUIRY → const GhosttyTerminalOption

Callback invoked when the terminal receives an ENQ character (0x05). Set to NULL to send no response.

Input type: GhosttyTerminalEnquiryFn

const GhosttyTerminalOption(3)

GHOSTTY_TERMINAL_OPT_XTVERSION → const GhosttyTerminalOption

Callback invoked when the terminal receives an XTVERSION query (CSI > q). Set to NULL to report the default "libghostty" string.

Input type: GhosttyTerminalXtversionFn

const GhosttyTerminalOption(4)

GHOSTTY_TERMINAL_OPT_TITLE_CHANGED → const GhosttyTerminalOption

Callback invoked when the terminal title changes via escape sequences (e.g. OSC 0 or OSC 2). Set to NULL to ignore title change events.

Input type: GhosttyTerminalTitleChangedFn

const GhosttyTerminalOption(5)

GHOSTTY_TERMINAL_OPT_SIZE → const GhosttyTerminalOption

Callback invoked in response to XTWINOPS size queries (CSI 14/16/18 t). Set to NULL to silently ignore size queries.

Input type: GhosttyTerminalSizeFn

const GhosttyTerminalOption(6)

GHOSTTY_TERMINAL_OPT_COLOR_SCHEME → const GhosttyTerminalOption

Callback invoked in response to a color scheme device status report query (CSI ? 996 n). Return true and fill the out pointer to report the current scheme, or return false to silently ignore. Set to NULL to ignore color scheme queries.

Input type: GhosttyTerminalColorSchemeFn

const GhosttyTerminalOption(7)

GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES → const GhosttyTerminalOption

Callback invoked in response to a device attributes query (CSI c, CSI > c, or CSI = c). Return true and fill the out pointer with response data, or return false to silently ignore. Set to NULL to ignore device attributes queries.

Input type: GhosttyTerminalDeviceAttributesFn

const GhosttyTerminalOption(8)

GHOSTTY_TERMINAL_OPT_TITLE → const GhosttyTerminalOption

Set the terminal title manually.

The string data is copied into the terminal. A NULL value pointer clears the title (equivalent to setting an empty string).

Input type: GhosttyString*

const GhosttyTerminalOption(9)

GHOSTTY_TERMINAL_OPT_PWD → const GhosttyTerminalOption

Set the terminal working directory manually.

The string data is copied into the terminal. A NULL value pointer clears the pwd (equivalent to setting an empty string).

Input type: GhosttyString*

const GhosttyTerminalOption(10)

GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND → const GhosttyTerminalOption

Set the default foreground color.

A NULL value pointer clears the default (unset).

Input type: GhosttyColorRgb*

const GhosttyTerminalOption(11)

GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND → const GhosttyTerminalOption

Set the default background color.

A NULL value pointer clears the default (unset).

Input type: GhosttyColorRgb*

const GhosttyTerminalOption(12)

GHOSTTY_TERMINAL_OPT_COLOR_CURSOR → const GhosttyTerminalOption

Set the default cursor color.

A NULL value pointer clears the default (unset).

Input type: GhosttyColorRgb*

const GhosttyTerminalOption(13)

GHOSTTY_TERMINAL_OPT_COLOR_PALETTE → const GhosttyTerminalOption

Set the default 256-color palette.

The value must point to an array of exactly 256 GhosttyColorRgb values. A NULL value pointer resets to the built-in default palette.

Input type: GhosttyColorRgb[256]*

const GhosttyTerminalOption(14)

GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT → const GhosttyTerminalOption

Set 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. A NULL value pointer is equivalent to zero (disables). Has no effect when Kitty graphics are disabled at build time.

Input type: uint64_t*

const GhosttyTerminalOption(15)

GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_FILE → const GhosttyTerminalOption

Enable or disable Kitty image loading via the file medium.

A NULL value pointer is a no-op. Has no effect when Kitty graphics are disabled at build time.

Input type: bool*

const GhosttyTerminalOption(16)

GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE → const GhosttyTerminalOption

Enable Kitty image loading via the temporary file medium, restricted to the provided directory. The string data is copied into the terminal.

A NULL value pointer disables the temporary file medium. Has no effect when Kitty graphics are disabled at build time.

Input type: GhosttyString*

const GhosttyTerminalOption(17)

GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM → const GhosttyTerminalOption

Enable or disable Kitty image loading via the shared memory medium.

A NULL value pointer is a no-op. Has no effect when Kitty graphics are disabled at build time.

Input type: bool*

const GhosttyTerminalOption(18)

GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES → const GhosttyTerminalOption

Set the maximum bytes the APC handler will buffer for all protocols. This prevents malicious input from causing unbounded memory allocation. A NULL value pointer removes all overrides, reverting to the built-in defaults.

Input type: size_t*

const GhosttyTerminalOption(19)

GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES_KITTY → const GhosttyTerminalOption

Set the maximum bytes the APC handler will buffer for Kitty graphics protocol data. A NULL value pointer removes the override, reverting to the built-in default.

Input type: size_t*

const GhosttyTerminalOption(20)

GHOSTTY_TERMINAL_OPT_SELECTION → const GhosttyTerminalOption

Set the active screen selection.

The value must point to a GhosttySelection whose grid references are valid for this terminal's active screen at the time of the call. The terminal copies the selection immediately and converts it to terminal-owned tracked state, so the GhosttySelection struct and its untracked grid references do not need to outlive this call.

Passing NULL clears the active screen selection.

Input type: GhosttySelection*

const GhosttyTerminalOption(21)

GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE → const GhosttyTerminalOption

Set the default cursor style used by DECSCUSR reset (CSI 0 q).

A NULL value pointer resets to the built-in default block cursor.

Input type: GhosttyTerminalCursorStyle*

const GhosttyTerminalOption(22)

GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_BLINK → const GhosttyTerminalOption

Set whether the default cursor should blink when reset by DECSCUSR (CSI 0 q).

A NULL value pointer resets to the built-in default of not blinking.

Input type: bool*

const GhosttyTerminalOption(23)

GHOSTTY_TERMINAL_OPT_GLYPH_PROTOCOL → const GhosttyTerminalOption

Enable or disable Glyph Protocol APC handling.

When disabled, Glyph Protocol APC sequences are ignored and no support/query/register/clear responses are emitted. Disabling also clears the terminal session's glyph glossary. A NULL value pointer is a no-op.

Input type: bool*

const GhosttyTerminalOption(24)

GHOSTTY_TERMINAL_OPT_PWD_CHANGED → const GhosttyTerminalOption

Callback invoked when the terminal pwd changes via escape sequences (OSC 7, OSC 9, or OSC 1337 CurrentDir). Set to NULL to ignore pwd change events.

Input type: GhosttyTerminalPwdChangedFn

const GhosttyTerminalOption(25)

GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE → const GhosttyTerminalOption

Callback invoked when the running program performs a clipboard write. OSC 52, iTerm2 OSC 1337 Copy, and Kitty clipboard (OSC 5522) writes are normalized to an atomic set of decoded MIME representations. Set to NULL to ignore clipboard writes (Kitty clipboard writes are then refused with ENOSYS). Clipboard read requests are delivered to GHOSTTY_TERMINAL_OPT_CLIPBOARD_READ instead.

Input type: GhosttyTerminalClipboardWriteFn

const GhosttyTerminalOption(26)

GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_BYTES → const GhosttyTerminalOption

Set the maximum scrollback allocation in bytes.

This is an estimate. Internally, libghostty only prunes bytes up to a "page"-granularity. A page is the minimum allocated unit of grid space within Ghostty. A page at the time of writing these docs is about 400KB, so the byte limit will be within this delta.

This works alongside the line limit configuration. If both are set, the first-reached limit is used first. Both limits are dependent on external state (byte limit can be reached with less lines if more styles are used for example, line limit can be reached with a narrower terminal viewport). So, they are useful together.

Lowering the limit immediately removes eligible complete historical pages. A value of zero disables scrollback and erases retained history. A NULL value pointer removes the byte limit.

Input type: size_t*

const GhosttyTerminalOption(27)

GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_LINES → const GhosttyTerminalOption

Set the maximum number of physical lines retained in scrollback.

This is an estimate. Internally, libghostty only prunes lines up to a "page"-granularity. A page is the minimum allocated unit of grid space within Ghostty. As a result, the actual available scrollback lines will almost always be higher than configured. The magnitude of the difference depends on the number of used styles, graphemes, etc. since the row-count in a page is dynamic based on that. In general, it ranges from dozens to a hundred or so lines.

This works alongside the line limit configuration. If both are set, the first-reached limit is used first. Both limits are dependent on external state (byte limit can be reached with less lines if more styles are used for example, line limit can be reached with a narrower terminal viewport). So, they are useful together.

Lowering the limit immediately removes eligible complete historical pages. A NULL value pointer removes the line limit.

Input type: size_t*

const GhosttyTerminalOption(28)

GHOSTTY_TERMINAL_OPT_DESKTOP_NOTIFICATION → const GhosttyTerminalOption

Callback invoked when the running program requests a desktop notification via OSC 9 or OSC 777. Set to NULL to ignore desktop notification requests.

Input type: GhosttyTerminalDesktopNotificationFn

const GhosttyTerminalOption(29)

GHOSTTY_TERMINAL_OPT_PROGRESS_REPORT → const GhosttyTerminalOption

Callback invoked when the running program reports progress via OSC 9;4. Set to NULL to ignore progress reports.

Input type: GhosttyTerminalProgressReportFn

const GhosttyTerminalOption(30)

GHOSTTY_TERMINAL_OPT_CONTINUATION_MAX_BYTES → const GhosttyTerminalOption

Set the maximum number of replay-safe VT continuation bytes retained.

Continuation bytes reconstruct an escape sequence or UTF-8 codepoint which was unfinished at the end of the most recent VT write call. They are used automatically by terminal snapshots and may also be exported directly with the continuation APIs.

Tracking is disabled by default. A nonzero value enables tracking and sets its byte limit. Passing NULL or a pointer to zero disables tracking. Lowering the limit below an already-retained continuation, or enabling tracking while the parser is already unfinished, makes the current continuation unavailable because earlier bytes cannot be reconstructed. Tracking recovers automatically after a later write reaches the ground state or contains a fresh replay start.

Input type: size_t*

const GhosttyTerminalOption(31)

GHOSTTY_TERMINAL_OPT_TITLE_REPORT → const GhosttyTerminalOption

Enable window title reports in response to CSI 21 t.

This is disabled by default because a running program can set a title and query it back into the pty input stream, potentially injecting commands that execute after user interaction. Passing NULL or a pointer to false disables title reporting.

Input type: bool*

const GhosttyTerminalOption(32)

GHOSTTY_TERMINAL_OPT_MODE_DEFAULT → const GhosttyTerminalOption

Set the reset default for a terminal mode.

This unconditionally updates both the current value and the value restored by a full terminal reset (RIS).

Some recognized modes represent transitions or mirror additional terminal state and cannot safely be configured as reset defaults. Those modes return GHOSTTY_INVALID_VALUE. A NULL value pointer also returns GHOSTTY_INVALID_VALUE.

Input type: GhosttyTerminalModeConfig*

const GhosttyTerminalOption(33)

GHOSTTY_TERMINAL_OPT_MODE → const GhosttyTerminalOption

Set the current value of a terminal mode.

This does not change the value restored by a full terminal reset (RIS). A NULL value pointer or unknown mode returns GHOSTTY_INVALID_VALUE.

Input type: GhosttyTerminalModeConfig*

const GhosttyTerminalOption(34)

GHOSTTY_TERMINAL_OPT_UNKNOWN_SEQUENCE → const GhosttyTerminalOption

Callback invoked for unsupported terminal sequence identifiers. Set to NULL to ignore unsupported sequences. Capture must also be enabled with GHOSTTY_TERMINAL_OPT_UNKNOWN_MAX_BYTES.

Input type: GhosttyTerminalUnknownSequenceFn

const GhosttyTerminalOption(35)

GHOSTTY_TERMINAL_OPT_UNKNOWN_MAX_BYTES → const GhosttyTerminalOption

Set the maximum content bytes retained for each unsupported terminal sequence. A NULL value pointer or zero disables capture and prevents unknown-sequence callbacks.

When this limit is hit, the unknown sequence callback will still be invoked but truncated will be set to true.

Input type: size_t*

const GhosttyTerminalOption(36)

GHOSTTY_TERMINAL_OPT_TERMINFO_NAME → const GhosttyTerminalOption

Set the name of the terminfo entry this terminal runs as, reported in response to an XTGETTCAP query for "TN" (e.g. "xterm-256color").

The string data is copied into the terminal. A NULL value pointer clears the name (equivalent to setting an empty string). A name longer than 128 bytes returns GHOSTTY_INVALID_VALUE.

If this is unset then we don't report anything for an XTGETTCAP TN query, because we don't know what the embedding terminal around libghostty is advertising itself as.

Input type: GhosttyString*

const GhosttyTerminalOption(37)

GHOSTTY_TERMINAL_OPT_CLIPBOARD_READ → const GhosttyTerminalOption

Callback invoked when the running program requests clipboard contents via OSC 52 with a "?" payload or a Kitty clipboard (OSC 5522) read. The read is synchronous and must be answered before the callback returns. Set to NULL (the default) to ignore OSC 52 read requests and refuse OSC 5522 reads with EPERM.

Input type: GhosttyTerminalClipboardReadFn

const GhosttyTerminalOption(38)

GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE_MAX_BYTES → const GhosttyTerminalOption

Set the maximum total decoded bytes a single Kitty clipboard protocol (OSC 5522) write transaction may accumulate. The limit is captured when a transaction begins; an in-flight transaction keeps the limit it started with.

Data beyond the limit fails the whole transaction with EFBIG. The transaction is discarded, later write-related packets are ignored until a new write begins, and nothing reaches the clipboard write callback.

Transactions are buffered in memory, so this limit bounds how much memory a single write can make the terminal allocate. Pass SIZE_MAX to remove the limit. A NULL value pointer reverts to the built-in default of 64MiB, the minimum required by the protocol.

This limit doesn't apply to OSC 52 writes, which are bounded by the maximum length of an escape sequence instead.

Input type: size_t*

const GhosttyTerminalOption(39)

GHOSTTY_TERMINAL_OPT_MAX_VALUE → const GhosttyTerminalOption

const GhosttyTerminalOption(2147483647)

Properties

hashCode → int

The hash code for this object.

no setter, inherited

index → int

A numeric identifier for the enumerated value.

no setter, inherited

name → String

Available on Enum, provided by the EnumName extension

The name of the enum value.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

value → int

final

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

fromValue(int value) → GhosttyTerminalOption

Constants

values → const List<GhosttyTerminalOption>

A constant List of the values in this enum, in order of their declaration.