path: root/vendor/libghostty-vt/include/ghostty/vt/screen.h

/**
 * @file screen.h
 *
 * Terminal screen cell and row types.
 */

#ifndef GHOSTTY_VT_SCREEN_H
#define GHOSTTY_VT_SCREEN_H

#include <stdbool.h>
#include <stdint.h>
#include <ghostty/vt/color.h>
#include <ghostty/vt/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/** @defgroup screen Screen
 *
 * Terminal screen cell and row types.
 *
 * These types represent the contents of a terminal screen. A GhosttyCell
 * is a single grid cell and a GhosttyRow is a single row. Cell fields can
 * be accessed via ghostty_cell_get() or decoded from the packed layout in
 * ghostty_type_json(). Rows are opaque and accessed via ghostty_row_get().
 *
 * @{
 */

/**
 * Packed cell value.
 *
 * Represents a single terminal cell. Portable callers can query fields via
 * ghostty_cell_get(). Boundary-sensitive callers can decode the packed value
 * using the GhosttyCell descriptor returned by ghostty_type_json(). The
 * manifest is authoritative for the linked build; hardcoding bit positions
 * is unsupported.
 *
 * @ingroup screen
 */
typedef uint64_t GhosttyCell;

/**
 * Opaque row value.
 *
 * Represents a single terminal row. The internal layout is opaque and
 * must be queried via ghostty_row_get(). Obtain row values from
 * terminal query APIs.
 *
 * @ingroup screen
 */
typedef uint64_t GhosttyRow;

/**
 * A borrowed view of contiguous raw cell values.
 *
 * The memory is not owned by this struct. The pointer is only valid
 * for the lifetime documented by the API that produces it. Each value
 * can be queried via ghostty_cell_get() or decoded using the GhosttyCell
 * packed descriptor returned by ghostty_type_json().
 *
 * @ingroup screen
 */
typedef struct {
  /** Pointer to len contiguous cell values. */
  const GhosttyCell* ptr;

  /** Number of cells. */
  size_t len;
} GhosttyCellsView;

/**
 * Cell content tag.
 *
 * Describes what kind of content a cell holds.
 *
 * @ingroup screen
 */
typedef enum GHOSTTY_ENUM_TYPED {
  /** A single codepoint (may be zero for empty). */
  GHOSTTY_CELL_CONTENT_CODEPOINT = 0,

  /** A codepoint that is part of a multi-codepoint grapheme cluster. */
  GHOSTTY_CELL_CONTENT_CODEPOINT_GRAPHEME = 1,

  /** No text; background color from palette. */
  GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE = 2,

  /** No text; background color as RGB. */
  GHOSTTY_CELL_CONTENT_BG_COLOR_RGB = 3,
  GHOSTTY_CELL_CONTENT_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyCellContentTag;

/**
 * Cell wide property.
 *
 * Describes the width behavior of a cell.
 *
 * @ingroup screen
 */
typedef enum GHOSTTY_ENUM_TYPED {
  /** Not a wide character, cell width 1. */
  GHOSTTY_CELL_WIDE_NARROW = 0,

  /** Wide character, cell width 2. */
  GHOSTTY_CELL_WIDE_WIDE = 1,

  /** Spacer after wide character. Do not render. */
  GHOSTTY_CELL_WIDE_SPACER_TAIL = 2,

  /** Spacer at end of soft-wrapped line for a wide character. */
  GHOSTTY_CELL_WIDE_SPACER_HEAD = 3,
  GHOSTTY_CELL_WIDE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyCellWide;

/**
 * Semantic content type of a cell.
 *
 * Set by semantic prompt sequences (OSC 133) to distinguish between
 * command output, user input, and shell prompt text.
 *
 * @ingroup screen
 */
typedef enum GHOSTTY_ENUM_TYPED {
  /** Regular output content, such as command output. */
  GHOSTTY_CELL_SEMANTIC_OUTPUT = 0,

  /** Content that is part of user input. */
  GHOSTTY_CELL_SEMANTIC_INPUT = 1,

  /** Content that is part of a shell prompt. */
  GHOSTTY_CELL_SEMANTIC_PROMPT = 2,
  GHOSTTY_CELL_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyCellSemanticContent;

/**
 * Cell data types.
 *
 * These values specify what type of data to extract from a cell
 * using `ghostty_cell_get`.
 *
 * @ingroup screen
 */
typedef enum GHOSTTY_ENUM_TYPED {
  /** Invalid data type. Never results in any data extraction. */
  GHOSTTY_CELL_DATA_INVALID = 0,

  /**
   * The codepoint of the cell (0 if empty or bg-color-only).
   *
   * Output type: uint32_t *
   */
  GHOSTTY_CELL_DATA_CODEPOINT = 1,

  /**
   * The content tag describing what kind of content is in the cell.
   *
   * Output type: GhosttyCellContentTag *
   */
  GHOSTTY_CELL_DATA_CONTENT_TAG = 2,

  /**
   * The wide property of the cell.
   *
   * Output type: GhosttyCellWide *
   */
  GHOSTTY_CELL_DATA_WIDE = 3,

  /**
   * Whether the cell has text to render.
   *
   * Output type: bool *
   */
  GHOSTTY_CELL_DATA_HAS_TEXT = 4,

  /**
   * Whether the cell has non-default styling.
   *
   * Output type: bool *
   */
  GHOSTTY_CELL_DATA_HAS_STYLING = 5,

  /**
   * The style ID for the cell (for use with style lookups).
   *
   * Output type: uint16_t *
   */
  GHOSTTY_CELL_DATA_STYLE_ID = 6,

  /**
   * Whether the cell has a hyperlink.
   *
   * Output type: bool *
   */
  GHOSTTY_CELL_DATA_HAS_HYPERLINK = 7,

  /**
   * Whether the cell is protected.
   *
   * Output type: bool *
   */
  GHOSTTY_CELL_DATA_PROTECTED = 8,

  /**
   * The semantic content type of the cell (from OSC 133).
   *
   * Output type: GhosttyCellSemanticContent *
   */
  GHOSTTY_CELL_DATA_SEMANTIC_CONTENT = 9,

  /**
   * The palette index for the cell's background color.
   * Only valid when content_tag is GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE.
   *
   * Output type: GhosttyColorPaletteIndex *
   */
  GHOSTTY_CELL_DATA_COLOR_PALETTE = 10,

  /**
   * The RGB value for the cell's background color.
   * Only valid when content_tag is GHOSTTY_CELL_CONTENT_BG_COLOR_RGB.
   *
   * Output type: GhosttyColorRgb *
   */
  GHOSTTY_CELL_DATA_COLOR_RGB = 11,
  GHOSTTY_CELL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyCellData;

/**
 * Row semantic prompt state.
 *
 * Indicates whether any cells in a row are part of a shell prompt,
 * as reported by OSC 133 sequences.
 *
 * @ingroup screen
 */
typedef enum GHOSTTY_ENUM_TYPED {
  /** No prompt cells in this row. */
  GHOSTTY_ROW_SEMANTIC_NONE = 0,

  /** Prompt cells exist and this is a primary prompt line. */
  GHOSTTY_ROW_SEMANTIC_PROMPT = 1,

  /** Prompt cells exist and this is a continuation line. */
  GHOSTTY_ROW_SEMANTIC_PROMPT_CONTINUATION = 2,
  GHOSTTY_ROW_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyRowSemanticPrompt;

/**
 * Row data types.
 *
 * These values specify what type of data to extract from a row
 * using `ghostty_row_get`.
 *
 * @ingroup screen
 */
typedef enum GHOSTTY_ENUM_TYPED {
  /** Invalid data type. Never results in any data extraction. */
  GHOSTTY_ROW_DATA_INVALID = 0,

  /**
   * Whether this row is soft-wrapped.
   *
   * Output type: bool *
   */
  GHOSTTY_ROW_DATA_WRAP = 1,

  /**
   * Whether this row is a continuation of a soft-wrapped row.
   *
   * Output type: bool *
   */
  GHOSTTY_ROW_DATA_WRAP_CONTINUATION = 2,

  /**
   * Whether any cells in this row have grapheme clusters.
   *
   * Output type: bool *
   */
  GHOSTTY_ROW_DATA_GRAPHEME = 3,

  /**
   * Whether any cells in this row have styling (may have false positives).
   *
   * Output type: bool *
   */
  GHOSTTY_ROW_DATA_STYLED = 4,

  /**
   * Whether any cells in this row have hyperlinks (may have false positives).
   *
   * Output type: bool *
   */
  GHOSTTY_ROW_DATA_HYPERLINK = 5,

  /**
   * The semantic prompt state of this row.
   *
   * Output type: GhosttyRowSemanticPrompt *
   */
  GHOSTTY_ROW_DATA_SEMANTIC_PROMPT = 6,

  /**
   * Whether this row contains a Kitty virtual placeholder.
   *
   * Output type: bool *
   */
  GHOSTTY_ROW_DATA_KITTY_VIRTUAL_PLACEHOLDER = 7,

  /**
   * Whether this row is dirty and requires a redraw.
   *
   * Output type: bool *
   */
  GHOSTTY_ROW_DATA_DIRTY = 8,
  GHOSTTY_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyRowData;

/**
 * Get data from a cell.
 *
 * Extracts typed data from the given cell based on the specified
 * data type. The output pointer must be of the appropriate type for the
 * requested data kind. Valid data types and output types are documented
 * in the `GhosttyCellData` enum.
 *
 * @param cell The cell value
 * @param data The type of data to extract
 * @param out Pointer to store the extracted data (type depends on data parameter)
 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
 *         data type is invalid
 *
 * @ingroup screen
 */
GHOSTTY_API GhosttyResult ghostty_cell_get(GhosttyCell cell,
                                GhosttyCellData data,
                                void *out);

/**
 * Get multiple data fields from a cell in a single call.
 *
 * Each element in the keys array specifies a data kind, and the
 * corresponding element in the values array receives the result.
 *
 * Processing stops at the first error; on success out_written
 * is set to count, on error it is set to the index of the
 * failing key (i.e. the number of values successfully written).
 *
 * @param cell The cell value
 * @param count Number of key/value pairs
 * @param keys Array of data kinds to query
 * @param values Array of output pointers (types must match each key's
 *               documented output type)
 * @param[out] out_written On return, receives the number of values
 *             successfully written (may be NULL)
 * @return GHOSTTY_SUCCESS if all queries succeed
 *
 * @ingroup screen
 */
GHOSTTY_API GhosttyResult ghostty_cell_get_multi(GhosttyCell cell,
                                     size_t count,
                                     const GhosttyCellData* keys,
                                     void** values,
                                     size_t* out_written);

/**
 * Get data from a row.
 *
 * Extracts typed data from the given row based on the specified
 * data type. The output pointer must be of the appropriate type for the
 * requested data kind. Valid data types and output types are documented
 * in the `GhosttyRowData` enum.
 *
 * @param row The row value
 * @param data The type of data to extract
 * @param out Pointer to store the extracted data (type depends on data parameter)
 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
 *         data type is invalid
 *
 * @ingroup screen
 */
GHOSTTY_API GhosttyResult ghostty_row_get(GhosttyRow row,
                               GhosttyRowData data,
                               void *out);

/**
 * Get multiple data fields from a row in a single call.
 *
 * Each element in the keys array specifies a data kind, and the
 * corresponding element in the values array receives the result.
 *
 * Processing stops at the first error; on success out_written
 * is set to count, on error it is set to the index of the
 * failing key (i.e. the number of values successfully written).
 *
 * @param row The row value
 * @param count Number of key/value pairs
 * @param keys Array of data kinds to query
 * @param values Array of output pointers (types must match each key's
 *               documented output type)
 * @param[out] out_written On return, receives the number of values
 *             successfully written (may be NULL)
 * @return GHOSTTY_SUCCESS if all queries succeed
 *
 * @ingroup screen
 */
GHOSTTY_API GhosttyResult ghostty_row_get_multi(GhosttyRow row,
                                    size_t count,
                                    const GhosttyRowData* keys,
                                    void** values,
                                    size_t* out_written);

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* GHOSTTY_VT_SCREEN_H */