| 1 | /** |
| 2 | * @file vt.h |
| 3 | * |
| 4 | * libghostty-vt - Virtual terminal emulator library |
| 5 | * |
| 6 | * This library provides functionality for parsing and handling terminal |
| 7 | * escape sequences as well as maintaining terminal state such as styles, |
| 8 | * cursor position, screen, scrollback, and more. |
| 9 | * |
| 10 | * WARNING: This is an incomplete, work-in-progress API. It is not yet |
| 11 | * stable and is definitely going to change. |
| 12 | */ |
| 13 | |
| 14 | /** |
| 15 | * @mainpage libghostty-vt - Virtual Terminal Emulator Library |
| 16 | * |
| 17 | * libghostty-vt is a C library which implements a modern terminal emulator, |
| 18 | * extracted from the [Ghostty](https://ghostty.org) terminal emulator. |
| 19 | * |
| 20 | * libghostty-vt contains the logic for handling the core parts of a terminal |
| 21 | * emulator: parsing terminal escape sequences, maintaining terminal state, |
| 22 | * encoding input events, etc. It can handle scrollback, line wrapping, |
| 23 | * reflow on resize, and more. |
| 24 | * |
| 25 | * @warning This library is currently in development and the API is not yet stable. |
| 26 | * Breaking changes are expected in future versions. Use with caution in production code. |
| 27 | * |
| 28 | * @section groups_sec API Reference |
| 29 | * |
| 30 | * The API is organized into the following groups: |
| 31 | * - @ref terminal "Terminal" - Complete terminal emulator state and rendering |
| 32 | * - @ref render "Render State" - Incremental render state updates for custom renderers |
| 33 | * - @ref formatter "Formatter" - Format terminal content as plain text, VT sequences, or HTML |
| 34 | * - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences |
| 35 | * - @ref sgr "SGR Parser" - Parse SGR (Select Graphic Rendition) sequences |
| 36 | * - @ref paste "Paste Utilities" - Validate paste data safety |
| 37 | * - @ref unicode "Unicode Utilities" - Codepoint properties for text layout |
| 38 | * - @ref build_info "Build Info" - Query compile-time build configuration |
| 39 | * - @ref allocator "Memory Management" - Memory management and custom allocators |
| 40 | * - @ref wasm "WebAssembly Utilities" - WebAssembly convenience functions |
| 41 | * |
| 42 | * Encoding related APIs: |
| 43 | * - @ref focus "Focus Encoding" - Encode focus in/out events into terminal sequences |
| 44 | * - @ref key "Key Encoding" - Encode key events into terminal sequences |
| 45 | * - @ref mouse "Mouse Encoding" - Encode mouse events into terminal sequences |
| 46 | * |
| 47 | * @section examples_sec Examples |
| 48 | * |
| 49 | * Complete working examples: |
| 50 | * - @ref c-vt-build-info/src/main.c - Build info query example |
| 51 | * - @ref c-vt/src/main.c - OSC parser example |
| 52 | * - @ref c-vt-encode-key/src/main.c - Key encoding example |
| 53 | * - @ref c-vt-encode-mouse/src/main.c - Mouse encoding example |
| 54 | * - @ref c-vt-paste/src/main.c - Paste safety check example |
| 55 | * - @ref c-vt-sgr/src/main.c - SGR parser example |
| 56 | * - @ref c-vt-formatter/src/main.c - Terminal formatter example |
| 57 | * - @ref c-vt-grid-traverse/src/main.c - Grid traversal example using grid refs |
| 58 | * - @ref c-vt-grid-ref-tracked/src/main.c - Tracked grid ref example |
| 59 | * - @ref c-vt-compression/src/main.c - Idle scrollback compression example |
| 60 | * |
| 61 | */ |
| 62 | |
| 63 | /** @example c-vt-build-info/src/main.c |
| 64 | * This example demonstrates how to query compile-time build configuration |
| 65 | * such as SIMD support, Kitty graphics, and tmux control mode availability. |
| 66 | */ |
| 67 | |
| 68 | /** @example c-vt/src/main.c |
| 69 | * This example demonstrates how to use the OSC parser to parse an OSC sequence, |
| 70 | * extract command information, and retrieve command-specific data like window titles. |
| 71 | */ |
| 72 | |
| 73 | /** @example c-vt-encode-key/src/main.c |
| 74 | * This example demonstrates how to use the key encoder to convert key events |
| 75 | * into terminal escape sequences using the Kitty keyboard protocol. |
| 76 | */ |
| 77 | |
| 78 | /** @example c-vt-encode-mouse/src/main.c |
| 79 | * This example demonstrates how to use the mouse encoder to convert mouse events |
| 80 | * into terminal escape sequences using the SGR mouse format. |
| 81 | */ |
| 82 | |
| 83 | /** @example c-vt-paste/src/main.c |
| 84 | * This example demonstrates how to use the paste utilities to check if |
| 85 | * paste data is safe before sending it to the terminal. |
| 86 | */ |
| 87 | |
| 88 | /** @example c-vt-sgr/src/main.c |
| 89 | * This example demonstrates how to use the SGR parser to parse terminal |
| 90 | * styling sequences and extract text attributes like colors and underline styles. |
| 91 | */ |
| 92 | |
| 93 | /** @example c-vt-formatter/src/main.c |
| 94 | * This example demonstrates how to use the terminal and formatter APIs to |
| 95 | * create a terminal, write VT-encoded content into it, and format the screen |
| 96 | * contents as plain text. |
| 97 | */ |
| 98 | |
| 99 | /** @example c-vt-grid-traverse/src/main.c |
| 100 | * This example demonstrates how to traverse the entire terminal grid using |
| 101 | * grid refs to inspect cell codepoints, row wrap state, and cell styles. |
| 102 | */ |
| 103 | |
| 104 | /** @example c-vt-grid-ref-tracked/src/main.c |
| 105 | * This example demonstrates how to track a grid ref as the terminal scrolls, |
| 106 | * detect when it loses its value, and move it to a new point. |
| 107 | */ |
| 108 | |
| 109 | /** @example c-vt-compression/src/main.c |
| 110 | * This example demonstrates how to schedule incremental scrollback compression |
| 111 | * after compression-relevant terminal activity becomes idle. |
| 112 | */ |
| 113 | |
| 114 | /** @example c-vt-selection-gesture/src/main.c |
| 115 | * This example demonstrates how to use synthetic selection gesture events to |
| 116 | * derive drag and deep-press selection snapshots. |
| 117 | */ |
| 118 | |
| 119 | /** @example c-vt-kitty-graphics/src/main.c |
| 120 | * This example demonstrates how to use the system interface to install a |
| 121 | * PNG decoder callback and send a Kitty Graphics Protocol image. |
| 122 | */ |
| 123 | |
| 124 | #ifndef GHOSTTY_VT_H |
| 125 | #define GHOSTTY_VT_H |
| 126 | |
| 127 | #ifdef __cplusplus |
| 128 | extern "C" { |
| 129 | #endif |
| 130 | |
| 131 | #include <ghostty/vt/types.h> |
| 132 | #include <ghostty/vt/allocator.h> |
| 133 | #include <ghostty/vt/build_info.h> |
| 134 | #include <ghostty/vt/color.h> |
| 135 | #include <ghostty/vt/color_scheme.h> |
| 136 | #include <ghostty/vt/device.h> |
| 137 | #include <ghostty/vt/focus.h> |
| 138 | #include <ghostty/vt/formatter.h> |
| 139 | #include <ghostty/vt/render.h> |
| 140 | #include <ghostty/vt/terminal.h> |
| 141 | #include <ghostty/vt/grid_ref.h> |
| 142 | #include <ghostty/vt/grid_ref_tracked.h> |
| 143 | #include <ghostty/vt/osc.h> |
| 144 | #include <ghostty/vt/sgr.h> |
| 145 | #include <ghostty/vt/style.h> |
| 146 | #include <ghostty/vt/sys.h> |
| 147 | #include <ghostty/vt/key.h> |
| 148 | #include <ghostty/vt/kitty_graphics.h> |
| 149 | #include <ghostty/vt/modes.h> |
| 150 | #include <ghostty/vt/mouse.h> |
| 151 | #include <ghostty/vt/paste.h> |
| 152 | #include <ghostty/vt/point.h> |
| 153 | #include <ghostty/vt/screen.h> |
| 154 | #include <ghostty/vt/selection.h> |
| 155 | #include <ghostty/vt/size_report.h> |
| 156 | #include <ghostty/vt/unicode.h> |
| 157 | #include <ghostty/vt/wasm.h> |
| 158 | |
| 159 | #ifdef __cplusplus |
| 160 | } |
| 161 | #endif |
| 162 | |
| 163 | #endif /* GHOSTTY_VT_H */ |