Turbo Vision

Turbo Vision is a modern, cross-platform port of the classical Turbo Vision 2.0 framework for building text-based user interfaces (TUI). It provides a widget-based system (views) for creating applications with resizable/overlapping windows, menus, dialog boxes, buttons, and more.

Key features include:

• Cross-platform compatibility: Write code once for Linux and Windows without using #ifdef for platform-specific terminal handling.
• Unicode support: Full support for displaying full-width Unicode characters.
• Abstraction of terminal capabilities: Handles terminal-specific quirks (like setting the blink attribute for bright backgrounds on Linux) automatically.
• Legacy compatibility: Maintains high source-level compatibility with original Turbo Vision applications by implementing certain Borland C++ RTL functions.

Most standard Turbo Vision views have been adapted to handle Unicode text properly, including support for horizontal scrolling and word wrapping.

Unicode-aware views (display only):

• TStaticText
• TFrame
• TStatusLine
• THistoryViewer
• THelpViewer
• TListViewer
• TMenuBox
• TTerminal
• TOutlineViewer
• TFileViewer (from tvdemo)
• TFilePane (from tvdir)

Views that process Unicode user input:

• TInputLine
• TEditor (defaults to UTF-8 mode; use Ctrl+P to switch to single-byte mode)
• TMenuView (shortcuts)

To begin using Turbo Vision, it is recommended to study the following resources:

1. User's Guide: Consult the Turbo Vision For C++ User's Guide.
2. Sample Applications: Examine the following repository examples to understand implementation patterns:
   • hello.cpp: A basic entry point.
   • tvdemo: A demonstration of framework capabilities.
   • tvedit: A text editor implementation.
3. Programming Guide: For a more intuitive understanding of the architecture, the Turbo Vision 2.0 Programming Guide is recommended (note: this guide uses Pascal).
4. Advanced Topics: Once basics are mastered, review the palette example for detailed information on how palettes are utilized.

The Window menu (Alt-W) provides management commands for active windows:

• {Size/Move:WSizeMove} (Ctrl-F5): Change the size or position of the active window. Use Shift + arrow keys to resize. Press Enter to confirm.
• {Zoom:WZoom} (F5): Toggle between maximum size and the previous size. Double-clicking the title bar also toggles zoom.
• {Tile:WTile}: Tile all file viewers on the desktop.
• {Cascade:WCascade}: Stack all file viewers on the desktop.
• {Next:WNext}: Cycle forward through windows.
• {Previous:WPrevious}: Cycle backward through windows.
• {Close:WClose} (Alt-F3): Close the active window or click the close box.

To provide a custom color scheme for a view, inherit from TView and override the getPalette() virtual function. The palette is defined as a character string where each byte represents a reference index for the next level in the hierarchy.

Implementation Pattern:

1. Define a character string (usually via hex escapes) containing the palette indices.
2. Use a static TPalette inside getPalette() to ensure the palette exists for the lifetime of the application.
3. Return a reference to the TPalette object.

#define cpTestView "\x9\xA\xB\xC\xD\xE"
TPalette& TTestView::getPalette() const
{
    static TPalette palette(cpTestView, sizeof(cpTestView)-1);
    return palette;
}

If you only wish to test the demo applications on Windows and do not want to build from source, you can download binaries from the GitHub Actions section of the repository.

1. Navigate to the Actions tab.
2. Click on the most recent successful workflow (indicated by a green tick).
3. Scroll to the Artifacts section at the bottom of the page to find:
   • examples-dos32.zip: 32-bit executables (Borland C++, no Unicode support).
   • examples-x86.zip: 32-bit executables (MSVC, requires Windows Vista or later).
   • examples-x64.zip: 64-bit executables (MSVC, requires Windows Vista or later).

You can use the vcpkg dependency manager to install Turbo Vision:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install tvision

Turbo Vision can be built as a static library using CMake and GCC/Clang.

Build Requirements:

• A C++14 compatible compiler.
• libncursesw (required).
• libgpm (optional, for mouse support on the Linux console).
• If using Debian-based distributions, install libncurses-dev and libgpm-dev.

Runtime Requirements:

• xsel or xclip for clipboard support in X11.
• wl-clipboard for clipboard support in Wayland.

Build Steps:

cmake . -B ./build -DCMAKE_BUILD_TYPE=Release
cmake --build ./build

Note: If using CMake versions older than 3.13, use the manual directory creation method.

cmake . -B ./build -DCMAKE_BUILD_TYPE=Release && # Could also be 'Debug', 'MinSizeRel' or 'RelWithDebInfo'.
cmake --build ./build # or `cd ./build; make`

The TClipboard class allows access to the system clipboard. If the system clipboard is unavailable, it falls back to an internal clipboard.

Setup: You must define the macro Uses_TClipboard before including <tvision/tv.h> to enable clipboard support.

Platform Support:

• Windows/macOS/WSL: Supported out-of-the-box.
• Unix (non-macOS): Requires external dependencies (see runtime requirements).
• Remote (SSH): Supported via X11 forwarding, terminal extensions (far2l, putty4far2l), or OSC 52 escape codes (Alacritty, Kitty, Foot, xterm with allowWindowOps).