turbo-vision 1.0.0

A Rust implementation of the classic Borland Turbo Vision text-mode UI framework
Documentation

Turbo Vision - Rust TUI Library

Turbo Vision Logo

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

Version 1.0.0 - PRODUCTION READY ✅

Based on kloczek Borland Turbo Vision C++ port here

Other C++ implementations:

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!

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
  • Flexible Layout System: Geometry primitives with absolute and relative positioning
  • Color Support: 16-color palette with Borland-accurate attribute system and context-aware remapping
  • 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
  • ANSI Dump: Debug UI by dumping screen/views to ANSI text files (F12 for full screen, Shift+F12 for active view, with flash effect)

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: Press F12 at any time to capture full screen to screen-dump.txt, or F11 to capture active window/dialog to active-view-dump.txt - both with a visual flash effect for debugging!

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:

  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 --bin rust_editor     # 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. rust_editor 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

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:

📖 API Reference

For API lookups and function signatures:

🛠️ 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
├── 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/
└── rust_editor.rs                      # Production text editor

🔗 Quick Links

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
  • ✅ RadioButtons
  • ✅ ListBoxes
  • ✅ Memo (multi-line text editor)
  • ✅ 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)

Architecture

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

  • Event Loop: Located in Group (matching Borland's TGroup::execute()), not in individual views
  • Modal Dialogs: Use Borland's endModal() pattern to exit event loops
  • View Hierarchy: Composition-based design (Window contains Group, Dialog wraps Window)
  • 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

Project Statistics

===============================================================================
 Language            Files        Lines         Code     Comments       Blanks
===============================================================================
 Rust                  115        33955        25389         3304         5262
 |- Markdown            90         3846          255         3010          581
 (Total)                          37801        25644         6314         5843
===============================================================================

Generated with tokei - includes inline documentation

210 unit tests - all passing ✅

License

MIT License - see LICENSE file for details.