API Reference

Complete API documentation for TUI.zig.

Core Modules

Application

• App - Main application runner
• AppConfig - Application configuration

Rendering

• Screen - Screen buffer management
• Renderer - Diff-based rendering engine
• Cell - Cell representation

Styling

• Style - Text styling
• Color - Color system

Events

• Event - Event types
• EventResult - Event handling results
• InputReader - Input parsing

Layout

• Rect - Rectangle bounds
• FlexRow - Horizontal flex layout
• FlexColumn - Vertical flex layout
• Grid - Grid layout
• Stack - Stack layout

Animation

• Animation - Generic animation
• Easing - Easing functions
• Timer - Timer system
• FpsCounter - FPS tracking

Widgets

Form Widgets

tui.InputField      // Single-line text input
tui.TextArea        // Multi-line text editor
tui.Checkbox        // Boolean checkbox
tui.RadioGroup      // Radio button group
tui.Switch          // Toggle switch
tui.Slider          // Numeric slider
tui.Button          // Clickable button

Display Widgets

tui.Text            // Static/dynamic text
tui.Badge           // Label badge
tui.Card            // Content card
tui.Table           // Data table
tui.ListView        // Scrollable list
tui.TreeView        // Hierarchical tree
tui.Image           // Image display

Navigation Widgets

tui.Navbar          // Top navigation bar
tui.Sidebar         // Side navigation panel
tui.Breadcrumb      // Breadcrumb trail
tui.Tabs            // Tabbed interface
tui.Menu            // Dropdown menu
tui.Pagination      // Page navigation

Feedback Widgets

tui.Alert           // Alert message
tui.AlertDialog     // Confirmation dialog
tui.Toast           // Toast notification
tui.Tooltip         // Contextual tooltip
tui.Modal           // Modal overlay
tui.ProgressBar     // Progress indicator
tui.Spinner         // Loading spinner
tui.Skeleton        // Loading placeholder

Layout Widgets

tui.Grid            // Grid layout
tui.Accordion       // Collapsible sections
tui.SplitView       // Split panes
tui.ScrollView      // Scrollable container
tui.Separator       // Visual separator
tui.Statusbar       // Status bar

Quick Reference

Creating an App

var app = try tui.App.init(.{
    .theme = tui.Theme.dracula,
    .alternate_screen = true,
    .hide_cursor = true,
    .enable_mouse = true,
    .target_fps = 60,
});
defer app.deinit();

Widget Pattern

const MyWidget = struct {
    pub fn render(self: *MyWidget, ctx: *tui.RenderContext) void {
        var screen = ctx.getSubScreen();
        // Render logic
    }

    pub fn handleEvent(self: *MyWidget, event: tui.Event) tui.EventResult {
        // Event handling
        return .ignored;
    }
};

Styling

const style = tui.Style.default
    .setFg(tui.Color.cyan)
    .setBg(tui.Color.black)
    .bold()
    .underline();

screen.setStyle(style);

Colors

// Named colors
tui.Color.red
tui.Color.green
tui.Color.blue

// RGB colors
tui.Color.fromRGB(255, 100, 50)

// Hex colors
tui.Color.hex(0xFF6432)

// 256-color palette
tui.Color{ .palette = 196 }

Events

pub fn handleEvent(self: *Widget, event: tui.Event) tui.EventResult {
    switch (event) {
        .key => |k| {
            switch (k.key) {
                .char => |c| {
                    // Handle character
                },
                .up, .down, .left, .right => {
                    // Handle arrows
                },
                .enter => {
                    // Handle enter
                },
                else => {},
            }
        },
        .mouse => |m| {
            // Handle mouse
        },
        .resize => |r| {
            // Handle resize
        },
        else => {},
    }
    return .ignored;
}

Layouts

// Flex layout
var row = tui.FlexRow.init(&widgets);
var column = tui.FlexColumn.init(&widgets);

// Grid layout
var grid = tui.Grid.init(3, 3);
const cell_bounds = grid.getCellBounds(.{ .row = 0, .col = 0 }, width, height);

// Stack layout
var stack = tui.Stack.init().withAlignment(.center);
const aligned = stack.alignChild(child_w, child_h, container_w, container_h);

Animations

// Create animation
var anim = tui.animation.Animation(f32).init(0.0, 100.0, 1000)
    .withEasing(tui.animation.Easing.easeInOutBounce)
    .loopForever()
    .withAlternate();

// Start and update
anim.start();
anim.update(delta_ms);
const value = anim.getValue();

Type Definitions

EventResult

pub const EventResult = enum {
    ignored,        // Event not handled
    consumed,       // Event handled, stop propagation
    needs_redraw,   // Request screen redraw
    request_focus,  // Request focus
    yield_focus,    // Release focus
};

AnimationState

pub const AnimationState = enum {
    idle,
    running,
    paused,
    completed,
};

BorderStyle

pub const BorderStyle = enum {
    none,
    single,
    double,
    rounded,
    thick,
    ascii,
};

Utilities

Unicode

// String width calculation
const width = tui.unicode.stringWidth("Hello 世界");

// Grapheme iteration
var iter = tui.unicode.graphemeIterator(text);
while (iter.next()) |grapheme| {
    // Process grapheme
}

Platform

// Platform detection
const is_windows = tui.platform.isWindows();
const is_unix = tui.platform.isUnix();

Error Handling

// Common errors
pub const Error = error{
    TerminalError,
    RenderError,
    InputError,
    AllocationError,
};

Best Practices

1. Always defer deinit

   var app = try tui.App.init(.{});
   defer app.deinit();

2. Use child contexts for positioning

   const rect = tui.Rect{ .x = 10, .y = 5, .width = 30, .height = 10 };
   var child_ctx = ctx.child(rect);
   widget.render(&child_ctx);

3. Return appropriate EventResult

   if (state_changed) {
       return .needs_redraw;
   }
   return .ignored;

4. Handle allocations properly

   var widget = tui.InputField.init(allocator);
   defer widget.deinit();

See Also

• Getting Started Guide
• Widget Reference
• Layout Guide
• Animation Guide