terminal.h

Go to the documentation of this file.

 
#ifndef GHOSTTY_VT_TERMINAL_H
#define GHOSTTY_VT_TERMINAL_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ghostty/vt/types.h>
#include <ghostty/vt/allocator.h>
#include <ghostty/vt/device.h>
#include <ghostty/vt/modes.h>
#include <ghostty/vt/size_report.h>
#include <ghostty/vt/grid_ref.h>
#include <ghostty/vt/io.h>
#include <ghostty/vt/kitty_graphics.h>
#include <ghostty/vt/screen.h>
#include <ghostty/vt/point.h>
#include <ghostty/vt/selection.h>
#include <ghostty/vt/style.h>
 
#ifdef __cplusplus
extern "C" {
#endif


typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_TERMINAL_COMPRESSION_MODE_INCREMENTAL = 0,

  GHOSTTY_TERMINAL_COMPRESSION_MODE_FULL = 1,
  GHOSTTY_TERMINAL_COMPRESSION_MODE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalCompressionMode;

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_TERMINAL_COMPRESSION_RESULT_UNSUPPORTED = 0,

  GHOSTTY_TERMINAL_COMPRESSION_RESULT_PENDING = 1,

  GHOSTTY_TERMINAL_COMPRESSION_RESULT_COMPLETE = 2,
  GHOSTTY_TERMINAL_COMPRESSION_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalCompressionResult;

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_SCROLL_VIEWPORT_TOP,

  GHOSTTY_SCROLL_VIEWPORT_BOTTOM,

  GHOSTTY_SCROLL_VIEWPORT_DELTA,

  GHOSTTY_SCROLL_VIEWPORT_ROW,
  GHOSTTY_SCROLL_VIEWPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalScrollViewportTag;

typedef union {
  intptr_t delta;

  size_t row;

  uint64_t _padding[2];
} GhosttyTerminalScrollViewportValue;

typedef struct {
  GhosttyTerminalScrollViewportTag tag;
  GhosttyTerminalScrollViewportValue value;
} GhosttyTerminalScrollViewport;

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_TERMINAL_SCREEN_PRIMARY = 0,

  GHOSTTY_TERMINAL_SCREEN_ALTERNATE = 1,
  GHOSTTY_TERMINAL_SCREEN_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalScreen;

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_TERMINAL_CURSOR_STYLE_BAR = 0,

  GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK = 1,

  GHOSTTY_TERMINAL_CURSOR_STYLE_UNDERLINE = 2,

  GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK_HOLLOW = 3,
  GHOSTTY_TERMINAL_CURSOR_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalCursorStyle;

typedef struct {
  uint64_t total;

  uint64_t offset;

  uint64_t len;
} GhosttyTerminalScrollbar;

typedef void (*GhosttyTerminalBellFn)(GhosttyTerminal terminal,
                                      void* userdata);

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_TERMINAL_UNKNOWN_SEQUENCE_APC = 0,
  GHOSTTY_TERMINAL_UNKNOWN_SEQUENCE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalUnknownSequenceTag;

typedef struct {
  bool truncated;

  GhosttyString content;
} GhosttyTerminalUnknownStringSequence;

typedef union {
  GhosttyTerminalUnknownStringSequence apc;

  uint64_t _padding[16];
} GhosttyTerminalUnknownSequenceValue;

typedef struct {
  GhosttyTerminalUnknownSequenceTag tag;
  GhosttyTerminalUnknownSequenceValue value;
} GhosttyTerminalUnknownSequence;

typedef void (*GhosttyTerminalUnknownSequenceFn)(
    GhosttyTerminal terminal,
    void* userdata,
    const GhosttyTerminalUnknownSequence* sequence);

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_CLIPBOARD_LOCATION_STANDARD = 0,

  GHOSTTY_CLIPBOARD_LOCATION_SELECTION = 1,

  GHOSTTY_CLIPBOARD_LOCATION_PRIMARY = 2,
  GHOSTTY_CLIPBOARD_LOCATION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyClipboardLocation;

typedef struct {
  GhosttyString mime;

  GhosttyString data;
} GhosttyClipboardContent;

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_CLIPBOARD_WRITE_RESULT_SUCCESS = 0,

  GHOSTTY_CLIPBOARD_WRITE_RESULT_DENIED = 1,

  GHOSTTY_CLIPBOARD_WRITE_RESULT_UNSUPPORTED = 2,

  GHOSTTY_CLIPBOARD_WRITE_RESULT_BUSY = 3,

  GHOSTTY_CLIPBOARD_WRITE_RESULT_INVALID_DATA = 4,

  GHOSTTY_CLIPBOARD_WRITE_RESULT_IO_ERROR = 5,
  GHOSTTY_CLIPBOARD_WRITE_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyClipboardWriteResult;

typedef struct {
  size_t size;

  GhosttyClipboardWriteResult result;

  bool remember;
} GhosttyClipboardWriteReply;
 
typedef struct GhosttyClipboardWrite GhosttyClipboardWrite;

typedef void (*GhosttyClipboardWriteReplyFn)(
    const GhosttyClipboardWrite* write,
    const GhosttyClipboardWriteReply* reply);

struct GhosttyClipboardWrite {
  size_t size;

  GhosttyClipboardLocation location;

  const GhosttyClipboardContent* contents;

  size_t contents_len;

  GhosttyString name;

  bool granted;

  bool can_remember;

  const void* ctx;

  GhosttyClipboardWriteReplyFn reply;
};

typedef void (*GhosttyTerminalClipboardWriteFn)(
    GhosttyTerminal terminal,
    void* userdata,
    const GhosttyClipboardWrite* write);

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_CLIPBOARD_READ_RESULT_SUCCESS = 0,

  GHOSTTY_CLIPBOARD_READ_RESULT_DENIED = 1,

  GHOSTTY_CLIPBOARD_READ_RESULT_UNSUPPORTED = 2,

  GHOSTTY_CLIPBOARD_READ_RESULT_BUSY = 3,

  GHOSTTY_CLIPBOARD_READ_RESULT_IO_ERROR = 4,
  GHOSTTY_CLIPBOARD_READ_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyClipboardReadResult;

typedef struct {
  size_t size;

  GhosttyClipboardReadResult result;

  const GhosttyClipboardContent* contents;

  size_t contents_len;

  const GhosttyString* available;

  size_t available_len;

  bool remember;
} GhosttyClipboardReadReply;
 
typedef struct GhosttyClipboardRead GhosttyClipboardRead;

typedef void (*GhosttyClipboardReadReplyFn)(
    const GhosttyClipboardRead* read,
    const GhosttyClipboardReadReply* reply);

struct GhosttyClipboardRead {
  size_t size;

  GhosttyClipboardLocation location;

  const GhosttyString* mimes;

  size_t mimes_len;

  bool list;

  GhosttyString name;

  bool granted;

  bool can_remember;

  const void* ctx;

  GhosttyClipboardReadReplyFn reply;
};

typedef void (*GhosttyTerminalClipboardReadFn)(
    GhosttyTerminal terminal,
    void* userdata,
    const GhosttyClipboardRead* read);

typedef struct {
  size_t size;

  GhosttyString title;

  GhosttyString body;
} GhosttyTerminalDesktopNotification;

typedef void (*GhosttyTerminalDesktopNotificationFn)(
    GhosttyTerminal terminal,
    void* userdata,
    const GhosttyTerminalDesktopNotification* notification);

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_TERMINAL_PROGRESS_STATE_REMOVE = 0,

  GHOSTTY_TERMINAL_PROGRESS_STATE_SET = 1,

  GHOSTTY_TERMINAL_PROGRESS_STATE_ERROR = 2,

  GHOSTTY_TERMINAL_PROGRESS_STATE_INDETERMINATE = 3,

  GHOSTTY_TERMINAL_PROGRESS_STATE_PAUSE = 4,
  GHOSTTY_TERMINAL_PROGRESS_STATE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalProgressState;

typedef struct {
  size_t size;

  GhosttyTerminalProgressState state;

  int8_t progress;
} GhosttyTerminalProgressReport;

typedef void (*GhosttyTerminalProgressReportFn)(
    GhosttyTerminal terminal,
    void* userdata,
    const GhosttyTerminalProgressReport* report);

typedef bool (*GhosttyTerminalColorSchemeFn)(GhosttyTerminal terminal,
                                             void* userdata,
                                             GhosttyColorScheme* out_scheme);

typedef bool (*GhosttyTerminalDeviceAttributesFn)(GhosttyTerminal terminal,
                                                   void* userdata,
                                                   GhosttyDeviceAttributes* out_attrs);

typedef GhosttyString (*GhosttyTerminalEnquiryFn)(GhosttyTerminal terminal,
                                                   void* userdata);

typedef bool (*GhosttyTerminalSizeFn)(GhosttyTerminal terminal,
                                      void* userdata,
                                      GhosttySizeReportSize* out_size);

typedef void (*GhosttyTerminalTitleChangedFn)(GhosttyTerminal terminal,
                                              void* userdata);

typedef void (*GhosttyTerminalPwdChangedFn)(GhosttyTerminal terminal,
                                            void* userdata);

typedef void (*GhosttyTerminalWritePtyFn)(GhosttyTerminal terminal,
                                          void* userdata,
                                          const uint8_t* data,
                                          size_t len);

typedef GhosttyString (*GhosttyTerminalXtversionFn)(GhosttyTerminal terminal,
                                                     void* userdata);

typedef struct {
  GhosttyMode mode;

  bool value;
} GhosttyTerminalModeConfig;

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_TERMINAL_OPT_USERDATA = 0,

  GHOSTTY_TERMINAL_OPT_WRITE_PTY = 1,

  GHOSTTY_TERMINAL_OPT_BELL = 2,

  GHOSTTY_TERMINAL_OPT_ENQUIRY = 3,

  GHOSTTY_TERMINAL_OPT_XTVERSION = 4,

  GHOSTTY_TERMINAL_OPT_TITLE_CHANGED = 5,

  GHOSTTY_TERMINAL_OPT_SIZE = 6,

  GHOSTTY_TERMINAL_OPT_COLOR_SCHEME = 7,

  GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES = 8,

  GHOSTTY_TERMINAL_OPT_TITLE = 9,

  GHOSTTY_TERMINAL_OPT_PWD = 10,

  GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND = 11,

  GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND = 12,

  GHOSTTY_TERMINAL_OPT_COLOR_CURSOR = 13,

  GHOSTTY_TERMINAL_OPT_COLOR_PALETTE = 14,

  GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT = 15,

  GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_FILE = 16,

  GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE = 17,

  GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM = 18,

  GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES = 19,

  GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES_KITTY = 20,

  GHOSTTY_TERMINAL_OPT_SELECTION = 21,

  GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE = 22,

  GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_BLINK = 23,

  GHOSTTY_TERMINAL_OPT_GLYPH_PROTOCOL = 24,

  GHOSTTY_TERMINAL_OPT_PWD_CHANGED = 25,

  GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE = 26,

  GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_BYTES = 27,

  GHOSTTY_TERMINAL_OPT_SCROLLBACK_MAX_LINES = 28,

  GHOSTTY_TERMINAL_OPT_DESKTOP_NOTIFICATION = 29,

  GHOSTTY_TERMINAL_OPT_PROGRESS_REPORT = 30,

  GHOSTTY_TERMINAL_OPT_CONTINUATION_MAX_BYTES = 31,

  GHOSTTY_TERMINAL_OPT_TITLE_REPORT = 32,

  GHOSTTY_TERMINAL_OPT_MODE_DEFAULT = 33,

  GHOSTTY_TERMINAL_OPT_MODE = 34,

  GHOSTTY_TERMINAL_OPT_UNKNOWN_SEQUENCE = 35,

  GHOSTTY_TERMINAL_OPT_UNKNOWN_MAX_BYTES = 36,

  GHOSTTY_TERMINAL_OPT_TERMINFO_NAME = 37,

  GHOSTTY_TERMINAL_OPT_CLIPBOARD_READ = 38,

  GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE_MAX_BYTES = 39,
  GHOSTTY_TERMINAL_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalOption;

typedef enum GHOSTTY_ENUM_TYPED {
  GHOSTTY_TERMINAL_DATA_INVALID = 0,

  GHOSTTY_TERMINAL_DATA_COLS = 1,

  GHOSTTY_TERMINAL_DATA_ROWS = 2,

  GHOSTTY_TERMINAL_DATA_CURSOR_X = 3,

  GHOSTTY_TERMINAL_DATA_CURSOR_Y = 4,

  GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP = 5,

  GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN = 6,

  GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE = 7,

  GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS = 8,

  GHOSTTY_TERMINAL_DATA_SCROLLBAR = 9,

  GHOSTTY_TERMINAL_DATA_CURSOR_STYLE = 10,

  GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING = 11,

  GHOSTTY_TERMINAL_DATA_TITLE = 12,

  GHOSTTY_TERMINAL_DATA_PWD = 13,

  GHOSTTY_TERMINAL_DATA_TOTAL_ROWS = 14,

  GHOSTTY_TERMINAL_DATA_SCROLLBACK_ROWS = 15,

  GHOSTTY_TERMINAL_DATA_WIDTH_PX = 16,

  GHOSTTY_TERMINAL_DATA_HEIGHT_PX = 17,

  GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND = 18,

  GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND = 19,

  GHOSTTY_TERMINAL_DATA_COLOR_CURSOR = 20,

  GHOSTTY_TERMINAL_DATA_COLOR_PALETTE = 21,

  GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT = 22,

  GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT = 23,

  GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT = 24,

  GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT = 25,

  GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_STORAGE_LIMIT = 26,

  GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_FILE = 27,

  GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE = 28,

  GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM = 29,

  GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS = 30,

  GHOSTTY_TERMINAL_DATA_SELECTION = 31,

  GHOSTTY_TERMINAL_DATA_VIEWPORT_ACTIVE = 32,

  GHOSTTY_TERMINAL_DATA_VT_PROCESSING_ERROR = 33,

  GHOSTTY_TERMINAL_DATA_SCROLLBACK_MAX_BYTES = 34,

  GHOSTTY_TERMINAL_DATA_SCROLLBACK_MAX_LINES = 35,

  GHOSTTY_TERMINAL_DATA_CONTINUATION_MAX_BYTES = 36,

  GHOSTTY_TERMINAL_DATA_MODE = 37,

  GHOSTTY_TERMINAL_DATA_VT_GROUND = 38,

  GHOSTTY_TERMINAL_DATA_CURSOR_AT_PROMPT = 39,

  GHOSTTY_TERMINAL_DATA_CLIPBOARD_WRITE_MAX_BYTES = 40,
  GHOSTTY_TERMINAL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalData;

GHOSTTY_API GhosttyResult ghostty_terminal_new(const GhosttyAllocator* allocator,
                                               GhosttyTerminal* terminal,
                                               uint16_t cols,
                                               uint16_t rows);

GHOSTTY_API void ghostty_terminal_free(GhosttyTerminal terminal);

GHOSTTY_API void ghostty_terminal_reset(GhosttyTerminal terminal);

GHOSTTY_API GhosttyResult ghostty_terminal_resize(GhosttyTerminal terminal,
                                      uint16_t cols,
                                      uint16_t rows,
                                      uint32_t cell_width_px,
                                      uint32_t cell_height_px);

GHOSTTY_API GhosttyResult ghostty_terminal_set(GhosttyTerminal terminal,
                                   GhosttyTerminalOption option,
                                   const void* value);

GHOSTTY_API void ghostty_terminal_vt_write(GhosttyTerminal terminal,
                                const uint8_t* data,
                                size_t len);

GHOSTTY_API GhosttyResult ghostty_terminal_vt_write_until_ground(
    GhosttyTerminal terminal,
    const uint8_t* data,
    size_t len,
    size_t* out_consumed);

GHOSTTY_API GhosttyResult ghostty_terminal_continuation_write(
    GhosttyTerminal terminal,
    GhosttyWriter writer);

GHOSTTY_API GhosttyResult ghostty_terminal_continuation_buf(
    GhosttyTerminal terminal,
    uint8_t* buf,
    size_t buf_len,
    size_t* out_written);

GHOSTTY_API GhosttyResult ghostty_terminal_continuation_alloc(
    GhosttyTerminal terminal,
    const GhosttyAllocator* allocator,
    uint8_t** out_ptr,
    size_t* out_len);

GHOSTTY_API void ghostty_terminal_scroll_viewport(GhosttyTerminal terminal,
                                       GhosttyTerminalScrollViewport behavior);

GHOSTTY_API GhosttyResult ghostty_terminal_compression_activity(
    GhosttyTerminal terminal,
    uint64_t* out_activity);

GHOSTTY_API GhosttyResult ghostty_terminal_compress(
    GhosttyTerminal terminal,
    GhosttyTerminalCompressionMode mode,
    GhosttyTerminalCompressionResult* out_result);

GHOSTTY_API GhosttyResult ghostty_terminal_get(GhosttyTerminal terminal,
                                    GhosttyTerminalData data,
                                    void *out);

GHOSTTY_API GhosttyResult ghostty_terminal_get_multi(GhosttyTerminal terminal,
                                    size_t count,
                                    const GhosttyTerminalData* keys,
                                    void** values,
                                    size_t* out_written);

GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref(GhosttyTerminal terminal,
                                        GhosttyPoint point,
                                        GhosttyGridRef *out_ref);

GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref_track(
    GhosttyTerminal terminal,
    GhosttyPoint point,
    GhosttyTrackedGridRef *out_ref);

GHOSTTY_API GhosttyResult ghostty_terminal_point_from_grid_ref(
    GhosttyTerminal terminal,
    const GhosttyGridRef *ref,
    GhosttyPointTag tag,
    GhosttyPointCoordinate *out);

 
#ifdef __cplusplus
}
#endif
 
#endif /* GHOSTTY_VT_TERMINAL_H */