libvaxis/README.md

# libvaxis

```
It begins with them, but ends with me. Their son, Vaxis
```

libvaxis is a zig port of the go TUI library
[Vaxis](https://git.sr.ht/~rockorager/vaxis). The goal is to have the same
feature set, only written in zig.

Like it's sibling library, libvaxis _does not use terminfo_. Support for vt
features is detected through terminal queries.

Contributions are welcome.

## Feature comparison

| Feature                        | Vaxis | libvaxis | notcurses |
| ------------------------------ | :---: | :------: | :-------: |
| RGB                            |  ✅   |    ✅    |    ✅     |
| Hyperlinks                     |  ✅   |    ✅    |    ❌     |
| Bracketed Paste                |  ✅   |    ✅    |    ❌     |
| Kitty Keyboard                 |  ✅   |    ✅    |    ✅     |
| Styled Underlines              |  ✅   |    ✅    |    ✅     |
| Mouse Shapes (OSC 22)          |  ✅   |    ✅    |    ❌     |
| System Clipboard (OSC 52)      |  ✅   | planned  |    ❌     |
| System Notifications (OSC 9)   |  ✅   |    ✅    |    ❌     |
| System Notifications (OSC 777) |  ✅   |    ✅    |    ❌     |
| Synchronized Output (DEC 2026) |  ✅   |    ✅    |    ✅     |
| Unicode Core (DEC 2027)        |  ✅   |    ✅    |    ❌     |
| Color Mode Updates (DEC 2031)  |  ✅   | planned  |    ❌     |
| Images (full/space)            |  ✅   | planned  |    ✅     |
| Images (half block)            |  ✅   | planned  |    ✅     |
| Images (quadrant)              |  ✅   | planned  |    ✅     |
| Images (sextant)               |  ❌   |    ❌    |    ✅     |
| Images (sixel)                 |  ✅   | debating |    ✅     |
| Images (kitty)                 |  ✅   |    ✅    |    ✅     |
| Images (iterm2)                |  ❌   |    ❌    |    ✅     |
| Video                          |  ❌   |    ❌    |    ✅     |
| Dank                           |  🆗   |    🆗    |    ✅     |

## Usage

The below example can be run using `zig build run 2>log`. stderr must be
redirected in order to not print to the same screen.

```zig
const std = @import("std");
const vaxis = @import("vaxis");
const Cell = vaxis.Cell;
const TextInput = vaxis.widgets.TextInput;
const border = vaxis.widgets.border;

const log = std.log.scoped(.main);

// Our EventType. This can contain internal events as well as Vaxis events.
// Internal events can be posted into the same queue as vaxis events to allow
// for a single event loop with exhaustive switching. Booya
const Event = union(enum) {
    key_press: vaxis.Key,
    winsize: vaxis.Winsize,
    focus_in,
    foo: u8,
};

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer {
        const deinit_status = gpa.deinit();
        //fail test; can't try in defer as defer is executed after we return
        if (deinit_status == .leak) {
            log.err("memory leak", .{});
        }
    }
    const alloc = gpa.allocator();

    // Initialize Vaxis with our event type
    var vx = try vaxis.init(Event, .{});
    // deinit takes an optional allocator. If your program is exiting, you can
    // choose to pass a null allocator to save some exit time.
    defer vx.deinit(alloc);

    // Start the read loop. This puts the terminal in raw mode and begins
    // reading user input
    try vx.startReadThread();
    defer vx.stopReadThread();

    // Optionally enter the alternate screen
    try vx.enterAltScreen();

    // We'll adjust the color index every keypress for the border
    var color_idx: u8 = 0;

    // init our text input widget. The text input widget needs an allocator to
    // store the contents of the input
    var text_input = TextInput.init(alloc);
    defer text_input.deinit();

    // Sends queries to terminal to detect certain features. This should
    // _always_ be called, but is left to the application to decide when
    try vx.queryTerminal();

    // The main event loop. Vaxis provides a thread safe, blocking, buffered
    // queue which can serve as the primary event queue for an application
    outer: while (true) {
        // nextEvent blocks until an event is in the queue
        const event = vx.nextEvent();
        log.debug("event: {}\r\n", .{event});
        // exhaustive switching ftw. Vaxis will send events if your EventType
        // enum has the fields for those events (ie "key_press", "winsize")
        switch (event) {
            .key_press => |key| {
                color_idx = switch (color_idx) {
                    255 => 0,
                    else => color_idx + 1,
                };
                if (key.matches('c', .{ .ctrl = true })) {
                    break :outer;
                } else if (key.matches('l', .{ .ctrl = true })) {
                    vx.queueRefresh();
                } else {
                    try text_input.update(.{ .key_press = key });
                }
            },

            // winsize events are sent to the application to ensure that all
            // resizes occur in the main thread. This lets us avoid expensive
            // locks on the screen. All applications must handle this event
            // unless they aren't using a screen (IE only detecting features)
            //
            // This is the only call that the core of Vaxis needs an allocator
            // for. The allocations are because we keep a copy of each cell to
            // optimize renders. When resize is called, we allocated two slices:
            // one for the screen, and one for our buffered screen. Each cell in
            // the buffered screen contains an ArrayList(u8) to be able to store
            // the grapheme for that cell Each cell is initialized with a size
            // of 1, which is sufficient for all of ASCII. Anything requiring
            // more than one byte will incur an allocation on the first render
            // after it is drawn. Thereafter, it will not allocate unless the
            // screen is resized
            .winsize => |ws| try vx.resize(alloc, ws),
            else => {},
        }

        // vx.window() returns the root window. This window is the size of the
        // terminal and can spawn child windows as logical areas. Child windows
        // cannot draw outside of their bounds
        const win = vx.window();

        // Clear the entire space because we are drawing in immediate mode.
        // vaxis double buffers the screen. This new frame will be compared to
        // the old and only updated cells will be drawn
        win.clear();
        const child = win.initChild(
            win.width / 2 - 20,
            win.height / 2 - 3,
            .{ .limit = 40 },
            .{ .limit = 3 },
        );
        // draw the text_input using a bordered window
        const style: vaxis.Style = .{
            .fg = .{ .index = color_idx },
        };
        text_input.draw(border.all(child, style));

        // Render the screen
        try vx.render();
    }
}
```