Turbo Vision - Rust TUI Library

A Rust implementation of the classic Borland Turbo Vision text user interface framework.

Full documentation, user guide, tutorials and a side-by-side comparison with the original C++ application model live at tv.enzolombardi.net.

Version 4.1.0 - PRODUCTION READY ✅

Based on kloczek Borland Turbo Vision C++ port here

Other C++ implementations:

• Magiblot Turbo Vision for C++
• Borland Original Turbo Vision 2.0.3 code

This port achieves 100% API parity with kloczek port of Borland Turbo Vision C++. All features from the original framework have been implemented. While the codebase is complete and production-ready, it may contain bugs. Please report any issues you encounter!

Screenshots

Showcase: Multiple Windows

The showcase demo with Calculator, Calendar, ASCII Table, and Puzzle windows demonstrating overlapping window management, z-ordering, and shadows.

Code Editor

A full-featured text editor (pascal_ide) editing its own source code, with menu bar, status line, and scrollable editing area.

Help Window

Context-sensitive help system (F1) with scrollable content, rendered over the editor window.

File System Tree

A tree view widget displaying a hierarchical file system with expandable/collapsible directories, keyboard navigation, and selection highlighting.

File Chooser Dialog

The built-in file dialog with directory navigation, file list, and keyboard/mouse support.

Features

• Complete UI Component Set: Windows, dialogs, buttons, input fields, menus, status bars, scrollbars
• Z-Order Management: Click any non-modal window to bring it to the front
• Modal Dialog Support: Modal dialogs block interaction with background windows
• Borland-Accurate Styling: Menu borders and shadows match original Borland Turbo Vision
• Scrollable Views: Built-in scrollbar support with keyboard navigation
• Text Viewer: Ready-to-use scrollable text viewer with line numbers
• Event-Driven Architecture:
  • Three-phase event processing (PreProcess → Focused → PostProcess)
  • Event re-queuing for deferred processing
  • Owner-aware broadcast system to prevent echo back to sender
• Mouse Support: Full mouse support for buttons, menus, status bar, dialog close buttons, scroll wheel, and double-click detection
• Window Dragging and Resizing: Drag windows by title bar, resize by bottom-right corner
• Owner-Relative Layout: Children keep coordinates relative to their owner, as in Borland's TView::origin; views draw at (0,0) and the owners translate (see docs/OWNER-COORDINATES.md)
• Color Support: 16-color palette with Borland-accurate attribute system and context-aware remapping
• Text Styling: Bold, dim, italic, underline, reverse, and strikethrough attributes — composable via Attr::new(fg, bg).bold().italic(), emitted as real SGR codes on the terminal and in ANSI dumps (see cargo run --example text_styling)
• Editor Selection: Stream selection (Shift+arrows / drag) plus rectangular block selection with columnar copy/cut and single-step undo, switched with the global block-edit mode (Application::set_block_edit_mode, CM_TOGGLE_BLOCK_MODE) rather than a modifier key; CM_SELECT_ALL command and Ctrl+A select all content of the focused window
• Cross-Platform: Built on crossterm for wide terminal compatibility
• Modal Dialogs: Built-in support for modal dialog execution
• Focus Management: Tab navigation and keyboard shortcuts
• Screen Capture: F12 saves an ASCII (ANSI) dump of the whole screen; Ctrl+F12 saves a PNG screenshot. Programmatic dumps of screen/views/regions via //

Extensions

Niche features that version on their own pace live in the separate tv-extensions crate: an SSH server (ssh), remote input over TCP for testing and automation (remote-input), Kitty images and ANSI-art backgrounds (graphics), the log window and terminal widget (log), a CSV table editor (csv), host-driven embedding for a non-terminal host such as a WASM guest (host, no feature flag), plus ScrollPane and popup menus (no feature flag). See UPGRADING-TO-4.0.md if you used any of these from core before 4.0.0.

Quick Start

use turbo_vision::prelude::*;

fn main() -> turbo_vision::core::error::Result<()> {
    // Create a window
    let mut dialog = turbo_vision::views::dialog::DialogBuilder::new().bounds(Rect::new(10, 5, 50, 15)).title("My First Dialog").build();

    // Create a button and add it to the window
    let button = turbo_vision::views::button::Button::new(Rect::new(26, 6, 36, 8), "Quit", turbo_vision::core::command::CM_OK, true);
    dialog.add(Box::new(button));

    // Create the application and add the dialog to its desktop
    let mut app = Application::new()?;
    app.desktop.add(Box::new(dialog));

    // Event loop
    app.running = true;
    while app.running {
        app.desktop.draw(&mut app.terminal);
        app.terminal.flush()?;
        if let Ok(Some(mut event)) = app.terminal.poll_event(std::time::Duration::from_millis(50)) {
            app.desktop.handle_event(&mut event);
            if event.command == CM_OK {
                // Handle button click
                app.running = false;
            }
        }
    }
    Ok(())
}

Tip: Capture the screen at any time —

• F12 saves an ASCII (ANSI-colored) dump of the whole screen to screen-YYYYMMDD-HHMMSS.ans (view it with cat or less -R).
• Ctrl+F12 saves a PNG screenshot of the whole screen to screenshot-YYYYMMDD-HHMMSS.png.

For programmatic use, see Terminal::dump_screen(path), Terminal::dump_region(...), and Terminal::save_screenshot_png(path).

Palette System

The color palette system accurately replicates Borland Turbo Vision's behavior:

• Context-Aware Remapping: Views automatically remap colors based on their container (Dialog, Window, or Desktop)
• Owner Type Support: Each view tracks its owner type for correct palette inheritance
• Borland-Accurate Colors: All UI elements (menus, buttons, labels, dialogs) match original Borland colors
• Runtime Customization: Change the entire application palette at runtime with app.set_palette() for custom themes

The palette system uses a three-level mapping chain:

1. View palette (e.g., Button, Label) → indices 1-31
2. Container palette (Dialog/Window) → remaps to indices 32-63
3. Application palette → final RGB colors

Custom Palettes and Theming

You can customize the entire application palette at runtime to create custom themes:

// Create a custom palette (63 bytes, each encoding foreground << 4 | background)
let dark_palette = vec![/* 63 color bytes */];

// Set the palette - redraw happens automatically!
app.set_palette(Some(dark_palette));

// Reset to default Borland palette
app.set_palette(None);

See examples/palette_themes_demo.rs for a complete example with multiple themes.

Module Overview

• core: Fundamental types (geometry, events, drawing, colors)
• terminal: Terminal I/O abstraction layer
• views: UI components (dialogs, buttons, menus, etc.)
• app: Application framework and event loop

Documentation

This project includes extensive documentation for different audiences and use cases. Here's a recommended reading order based on your goals:

🚀 New to Turbo Vision? Start Here

If you're new to Turbo Vision frameworks, follow this path:

0. AGENTS.md - The Turbo Vision way in one page, the application skeleton, an index of every component, recipes and rules. Written for people and AI assistants alike; its examples are compiled as tests.
1. Quick Start (above) - Get a minimal example running
2. Examples Overview - Browse 30+ working examples

   cargo run --example showcase    # Comprehensive feature showcase
   cargo run --example gallery     # Every component, live, with its code
   cargo run --bin pascal_ide     # Full-featured text editor
   

3. User Guide - Chapter 1 - Learn the basics
4. User Guide - Chapter 2 - Handle events and commands
5. User Guide - Chapter 3 - Create your first window

Continue with: Chapters 4-18 in the User Guide for comprehensive coverage of all features.

🎯 Building Your First App

For practical application development:

1. Custom Application Example - Complete walkthrough
2. Biorhythm Calculator Tutorial - Build a real app step-by-step
3. examples/showcase.rs - Study the comprehensive demo
4. pascal_ide source - See a production-ready editor

🔧 Coming from Borland/C++ Turbo Vision?

If you're familiar with Borland Turbo Vision:

1. Architecture Overview - Understand Rust adaptations
2. Rust Implementation Reference - Technical details
3. Turbo Vision Design - Complete design document
4. Class Diagram - How the core types compose, as a Mermaid diagram

Key Differences: The Rust port uses composition over inheritance, but maintains the same event loop patterns, drawing system, and API structure as Borland's original.

📚 Feature-Specific Guides

When you need specific functionality:

• Palette & Colors: Palette System, Borland Palette Chart, Chapter 14
• Event Handling: Chapter 9 - Event-Driven Programming
• Forms & Input: Chapter 5 - Data Entry Forms, Chapter 13 - Validation
• Text Editing: Chapter 15 - Editor and Text Views
• Collections & Lists: Chapter 6 - Managing Data Collections
• Persistence: Serialization Guide, Quick Reference
• Application Structure: Chapter 10 - Application Objects
• Windows & Dialogs:

📖 API Reference

For API lookups and function signatures:

• Documentation Index - Master index of all documentation
• Rust API Catalog - Complete API listing
• API Catalog Index - Quick reference guide
• Inline Docs: Run cargo doc --open for generated documentation

🛠️ Contributing to the Project

If you want to modify or extend the codebase:

1. Rust Coding Guidelines - Code style and best practices
2. Chapter 8 - Views and Groups - Understanding the view hierarchy
3. Study existing tests in src/views/*/tests modules

📂 Complete Documentation Structure

docs/
├── DOCUMENTATION-INDEX.md              # Master index
├── RUST-CODING-GUIDELINES.md          # Code style guide
├── CUSTOM-APPLICATION-RUST-EXAMPLE.md  # Complete app walkthrough
├── BIORHYTHM-CALCULATOR-TUTORIAL.md    # Step-by-step tutorial
├── PALETTE-SYSTEM.md                   # Color system explained
├── BORLAND-PALETTE-CHART.md            # Color reference
├── RUST-API-CATALOG.md                 # API reference
├── TURBO-VISION-DESIGN.md              # Complete design document
├── CLASS-DIAGRAM.md                    # Mermaid class diagram of the core types
├── HOW-TO-BUILD-AND-DEPLOY-WEBSITE.md  # Building and deploying the MkDocs site
├── SERIALIZATION-PERSISTENCE.md         # Saving/loading data
└── user-guide/                         # 18-chapter comprehensive guide
    ├── Chapter-01-Stepping-into-Turbo-Vision.md
    ├── Chapter-02-Responding-to-Commands.md
    ├── ... (Chapters 3-17)
    └── Chapter-18-Resources.md

examples/
├── README.md                           # Examples index with descriptions
├── showcase.rs                         # Comprehensive demo
├── biorhythm.rs                        # Complete calculator app
└── ... (30+ more examples)

demo/
└── pascal_ide.rs                      # Production text editor

🔗 Quick Links

• Start Coding: Quick Start → Examples
• Learn Concepts: User Guide Chapter 1
• Build an App: Custom Application Example
• Get Help: Documentation Index
• Report Issues: GitHub Issues

Status

Currently implements:

• ✅ Core drawing and event system
• ✅ Dialog boxes with frames and close buttons
• ✅ Buttons with keyboard shortcuts
• ✅ Static text labels (with centered text support)
• ✅ Input fields
• ✅ Menu bar with dropdowns and keyboard shortcut display
• ✅ Status line with hot spots (hover highlighting, context-sensitive hints)
• ✅ Desktop manager
• ✅ Scrollbars (vertical and horizontal)
• ✅ Scroller base class for scrollable views
• ✅ Indicator (position display)
• ✅ Text viewer with scrolling
• ✅ CheckBoxes and RadioButtons (single, or multi-item clusters with one bitmask value)
• ✅ ListBoxes (single selection, or multi-select with Space and Shift+click, lazy item provider)
• ✅ Memo (multi-line text editor)
• ✅ ProgressBar (determinate and marquee, three glyph styles)
• ✅ ComboBox (read-only field with a drop-down list)
• ✅ Spinner (numeric field with steppers, range-clamped)
• ✅ Slider (horizontal value slider, keyboard step and mouse drag)
• ✅ Table (grid with header row, sized columns, cell focus, optional column separators, lazy row provider)
• ✅ TabbedPane (enclosed tabs over a stack of pages)
• ✅ SplitPane (two panes with a draggable divider)
• ✅ Tooltip (hover hints for a dialog's controls)
• ✅ Mouse support (buttons, menus, status bar, close buttons, hover effects, listbox clicks, scroll wheel, double-click detection)
• ✅ Window dragging and resizing (drag by title bar, resize from bottom-right corner with minimum size constraints)
• ✅ Window closing (non-modal windows close with close button, modal dialogs convert to cancel)
• ✅ File Dialog (fully functional with mouse/keyboard support and directory navigation)
• ✅ ANSI Dump for debugging (dump screen/views to text files with colors)
• ✅ Input Validators (FilterValidator, RangeValidator with hex/octal, LookupValidator)
• ✅ Editor with search/replace and file I/O (load_file, save_file, save_as)
• ✅ EditWindow (ready-to-use editor window wrapper)
• ✅ OS Clipboard integration (cross-platform with arboard)
• ✅ Help System (markdown-based with HelpFile, HelpViewer, HelpWindow, HelpContext)

SSH Support

SSH support moved to tv-extensions in 4.0.0: tv_extensions::ssh (feature ssh) serves TUI applications over SSH connections the same way core's removed ssh feature did, built on the same Backend trait abstraction — SshBackend plugs in beside CrosstermBackend, and InputParser (still public in core) converts raw bytes to events either way. See tv-extensions' SSH docs and UPGRADING-TO-4.0.md.

Architecture

This implementation closely follows Borland Turbo Vision's architecture, adapted for Rust:

• Event Loop: Application::run_with takes an AppHandler for the program's own commands (Borland's TApplication::handleEvent and idle overrides); Application::execute_modal is the one modal loop behind Dialog::execute
• Modal Dialogs: Use Borland's endModal() pattern to exit event loops; CloseOn says which commands close a dialog
• View Hierarchy: Borland's TView > TGroup > TWindow > TDialog is expressed as layered traits over shared cores: every view owns a ViewCore, GroupLike and WindowLike carry TGroup's and TWindow's behaviour as group_* / window_* default methods, and a window-shaped type gets its View impl from impl_view_for_window! with overrides written inline. Overrides are late-bound: Dialog::get_palette is what window_draw paints with. See docs/MISSING-INHERITANCE.md for the analysis behind it.
• Drawing: Event-driven redraws with Borland's drawUnderRect pattern for efficient updates
• Event System:
  • Three-phase processing (PreProcess → Focused → PostProcess) matching Borland's TGroup::handleEvent()
  • Event re-queuing via Terminal::put_event() matching Borland's TProgram::putEvent()
  • Owner-aware broadcasts via Group::broadcast() matching Borland's message(owner, ...) pattern

Class Diagram

A non-exhaustive map of the main types. Traits are marked <<trait>>; dashed hollow arrows are trait implementations, filled diamonds are ownership by value. The full page with notes lives in docs/CLASS-DIAGRAM.md.

classDiagram
    direction TB

    class View {
        <<trait>>
        +bounds() Rect
        +set_bounds(Rect)
        +draw(Terminal)
        +handle_event(Event)
        +can_focus() bool
        +set_focus(bool)
        +state() StateFlags
        +options() u16
        +grow_mode() GrowFlags
    }

    class IdleView {
        <<trait>>
        +idle()
    }
    class Cluster {
        <<trait>>
        +cluster_state()
    }
    class ListViewer {
        <<trait>>
        +list_state()
        +item_count() usize
    }
    class MenuViewer {
        <<trait>>
        +menu_state()
    }
    class Editor {
        <<trait>>
        +undo()
        +redo()
        +cut() bool
        +copy() bool
        +paste() bool
    }
    class FileEditor {
        <<trait>>
        +load(PathBuf)
        +save()
        +save_as(PathBuf)
    }

    View <|-- IdleView
    View <|-- Cluster
    View <|-- ListViewer
    View <|-- MenuViewer
    View <|-- Editor
    Editor <|-- FileEditor

    class Application {
        +terminal: Terminal
        +desktop: Desktop
        +menu_bar: Option~MenuBar~
        +status_line: Option~StatusLine~
        +running: bool
        +run()
        +handle_event(Event)
    }

    class Desktop {
        -children: Group
        +add(Box~View~)
        +cascade()
        +tile()
        +bring_to_front(ViewId)
    }

    class Group {
        -children: Vec~Box~View~~
        -focused: usize
        -end_state: CommandId
        +add(Box~View~) ViewId
        +execute() CommandId
        +end_modal(CommandId)
        +broadcast(Event, owner)
    }

    class Window {
        -frame: Frame
        -interior: Group
        -number: Option~u8~
        -zoom_rect: Rect
        +add(Box~View~) ViewId
        +zoom(Rect)
    }

    class Frame {
        -title: String
        -resizable: bool
        -zoomable: bool
        +is_zoomed() bool
    }

    class Dialog {
        -window: Window
        -result: CommandId
        +execute(Application) CommandId
    }

    class MenuBar {
        -submenus: Vec~SubMenu~
    }
    class MenuBox
    class StatusLine {
        -items: Vec~StatusItem~
    }

    class Button {
        -title: String
        -command: CommandId
        -is_default: bool
    }
    class InputLine
    class StaticText
    class Label
    class CheckBox
    class RadioButton
    class ListBox
    class ScrollBar
    class Scroller
    class TextViewer
    class Memo
    class EditorWindow
    class FileEditorWindow

    class Event {
        +what: EventType
        +key_code: u16
        +mouse: MouseEvent
        +command: CommandId
        +clear()
    }
    class Terminal {
        +put_event(Event)
        +flush()
    }
    class Rect
    class Palette

    Application *-- Desktop
    Application *-- Terminal
    Application o-- MenuBar
    Application o-- StatusLine
    Desktop *-- Group
    Window *-- Frame
    Window *-- Group : interior
    Dialog *-- Window
    Group o-- "0..*" View : children
    Scroller o-- ScrollBar
    TextViewer o-- ScrollBar
    MenuBar ..> MenuBox : opens

    View <|.. Desktop
    View <|.. Group
    View <|.. Window
    View <|.. Frame
    View <|.. Dialog
    View <|.. MenuBar
    View <|.. StatusLine
    View <|.. Button
    View <|.. InputLine
    View <|.. StaticText
    View <|.. Label
    View <|.. ScrollBar
    View <|.. Scroller
    View <|.. TextViewer
    View <|.. Memo
    Cluster <|.. CheckBox
    Cluster <|.. RadioButton
    ListViewer <|.. ListBox
    MenuViewer <|.. MenuBar
    MenuViewer <|.. MenuBox
    Editor <|.. EditorWindow
    FileEditor <|.. FileEditorWindow

    View ..> Event : handles
    View ..> Terminal : draws to
    View ..> Rect : bounds
    View ..> Palette : colours from

Project Statistics

===============================================================================
 Language            Files        Lines         Code     Comments       Blanks
===============================================================================
 Rust                  125        37315        28029         3557         5729
 |- Markdown           102         4695          332         3604          759
 (Total)                          42010        28361         7161         6488
===============================================================================

Generated with tokei - includes inline documentation

226 unit tests - all passing ✅

Star History

License

MIT License - see LICENSE file for details.