Turbo Vision

A modern port of Turbo Vision 2.0, the classical framework for text-based user interfaces. Now cross-platform and with Unicode support.

I started this as a personal project at the very end of 2018. By May 2020 I considered it was very close to feature parity with the original, and decided to make it open.

The original goals of this project were:

• Making Turbo Vision work on Linux by altering the legacy codebase as little as possible.
• Keeping it functional on DOS/Windows.
• Being as compatible as possible at the source code level with old Turbo Vision applications. This led me to implement some of the Borland C++ RTL functions, as explained below.

At one point I considered I had done enough, and that any attempts at revamping the library and overcoming its original limitations would require either extending the API or breaking backward compatibility, and that a major rewrite would be most likely necessary.

However, between July and August 2020 I found the way to integrate full-fledged Unicode support into the existing architecture, wrote the Turbo text editor and also made the new features available on Windows. So I am confident that Turbo Vision can now meet many of the expectations of modern users and programmers.

The original location of this project is https://github.com/magiblot/tvision.

Table of contents

• What is Turbo Vision good for?
• How do I use Turbo Vision?
• Releases and downloads
• Build environment
  • Linux
  • Windows (MSVC)
  • Windows (MinGW)
  • Windows/DOS (Borland C++)
  • Vcpkg
  • Turbo Vision as a CMake dependency
• Features
• API changes
• Applications using Turbo Vision
• Unicode support
• Clipboard interaction
• Extended color support

<div id="what-for"></div>

What is Turbo Vision good for?

A lot has changed since Borland created Turbo Vision in the early 90's. Many GUI tools today separate appearance specification from behaviour specification, use safer or dynamic languages which do not segfault on error, and support either parallel or asynchronous programming, or both.

Turbo Vision does not excel at any of those, but it certainly overcomes many of the issues programmers still face today when writing terminal applications:

1. Forget about terminal capabilities and direct terminal I/O. When writing a Turbo Vision application, all you have to care about is what you want your application to behave and look like—there is no need to add workarounds in your code. Turbo Vision tries its best to produce the same results on all environments. For example: in order to get a bright background color on the Linux console, the blink attribute has to be set. Turbo Vision does this for you.

2. Reuse what has already been done. Turbo Vision provides many widget classes (also known as views), including resizable, overlapping windows, pull-down menus, dialog boxes, buttons, scroll bars, input boxes, check boxes and radio buttons. You may use and extend these; but even if you prefer creating your own, Turbo Vision already handles event dispatching, display of fullwidth Unicode characters, etc.: you do not need to waste time rewriting any of that.

3. Can you imagine writing a text-based interface that works both on Linux and Windows (and thus is cross-platform) out-of-the-box, with no #ifdefs? Turbo Vision makes this possible. First: Turbo Vision keeps on using char arrays instead of relying on the implementation-defined and platform-dependent wchar_t or TCHAR. Second: thanks to UTF-8 support in setlocale in recent versions of Microsoft's RTL, code like the following will work as intended:

   std::ifstream f("コンピュータ.txt"); // On Windows, the RTL converts this to the system encoding on-the-fly.

<div id="how-to"></div>

How do I use Turbo Vision?

You can get started with the Turbo Vision For C++ User's Guide, and look at the sample applications hello, tvdemo and tvedit. Once you grasp the basics, I suggest you take a look at the Turbo Vision 2.0 Programming Guide, which is, in my opinion, more intuitive and easier to understand, despite using Pascal. By then you will probably be interested in the palette example, which contains a detailed description of how palettes are used.

Don't forget to check out the <a href="#features">features</a> and <a href="#apichanges">API changes</a> sections as well.

<div id="downloads"></div>

Releases and downloads

This project has no stable releases for the time being. If you are a developer, try to stick to the latest commit and report any issues you find while upgrading.

If you just want to test the demo applications:

• Unix systems: you'll have to build Turbo Vision yourself. You may follow the build instructions below.
• Windows: you can find up-to-date binaries in the Actions section. Click on the first successful workflow (with a green tick) in the list. At the bottom of the workflow page, as long as you have logged in to GitHub, you'll find an Artifacts section with the following files:
  • examples-dos32.zip: 32-bit executables built with Borland C++. No Unicode support.
  • examples-x86.zip: 32-bit executables built with MSVC. Windows Vista or later required.
  • examples-x64.zip: 64-bit executables built with MSVC. x64 Windows Vista or later required.

Build environment

<div id="build-linux"></div>

Linux

Turbo Vision can be built as an static library with CMake and GCC/Clang.

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

CMake versions older than 3.13 may not support the -B option. You can try the following instead:

mkdir -p build; cd build
cmake .. -DCMAKE_BUILD_TYPE=Release &&
cmake --build .

The above produces the following files:

• libtvision.a, which is the Turbo Vision library.
• The demo applications hello, tvdemo, tvedit, tvdir, which were bundled with the original Turbo Vision (although some of them have a few improvements).
• The demo applications mmenu and palette from Borland's Technical Support.
• tvhc, the Turbo Vision Help Compiler.

The library and executables can be found in ./build.

The build requirements are:

• A compiler supporting C++14.
• libncursesw (note the 'w').
• libgpm for mouse support on the Linux console (optional).

If your distribution provides separate devel packages (e.g. libncurses-dev, libgpm-dev in Debian-based distros), install these too.

<div id="build-linux-runtime"></div>

The runtime requirements are:

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

The minimal command line required to build a Turbo Vision application (e.g. hello.cpp with GCC) from this project's root is:

g++ -std=c++14 -o hello hello.cpp ./build/libtvision.a -Iinclude -lncursesw -lgpm

You may also need:

• -Iinclude/tvision if your application uses Turbo Vision 1.x includes (#include <tv.h> instead of #include <tvision/tv.h>).

• -Iinclude/tvision/compat/borland if your application includes Borland headers (dir.h, iostream.h, etc.).

• On Gentoo (and possibly others): -ltinfow if both libtinfo.so and libtinfow.so are available in your system. Otherwise, you may get a segmentation fault when running Turbo Vision applications (#11). Note that tinfo is bundled with ncurses.

-lgpm is only necessary if Turbo Vision was built with libgpm support.

The backward-compatibility headers in include/tvision/compat/borland emulate the Borland C++ RTL. Turbo Vision's source code still depends on them, and they could be useful if porting old applications. This also means that including tvision/tv.h will bring several std names to the global namespace.

<div id="build-msvc"></div>

Windows (MSVC)

The build process with MSVC is slightly more complex, as there are more options to choose from. Note that you will need different build directories for different target architectures. For instance, to generate optimized binaries:

cmake . -B ./build && # Add '-A x64' (64-bit) or '-A Win32' (32-bit) to override the default platform.
cmake --build ./build --config Release # Could also be 'Debug', 'MinSizeRel' or 'RelWithDebInfo'.

In the example above, tvision.lib and the example applications will be placed at ./build/Release.

If you wish to link Turbo Vision statically against Microsoft's run-time library (/MT instead of /MD), enable the TV_USE_STATIC_RTL option (-DTV_USE_STATIC_RTL=ON when calling cmake).

If you wish to link an application against Turbo Vision, note that MSVC won't allow you to mix /MT with /MD or debug with non-debug binaries. All components have to be linked against the RTL in the same way.

If you develop your own Turbo Vision application make sure to enable the following compiler flags, or else you will get compilation errors when including <tvision/tv.h>:

/permissive-
/Zc:__cplusplus

If you use Turbo Vision as a CMake submodule, these flags will be enabled automatically.

Note: Turbo Vision uses setlocale to set the RTL functions in UTF-8 mode. This won't work if you use an old version of the RTL.

With the RTL statically linked in, and if UTF-8 is supported in setlocale, Turbo Vision applications are portable and work by default on Windows Vista and later.

<div id="build-mingw"></div>

Windows (MinGW)

Once your MinGW environment is properly set up, build is done in a similar way to Linux:

cmake . -B ./build -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release &&
cmake --build ./build

In the example above, libtvision.a and all examples are in ./build if TV_BUILD_EXAMPLES option is ON (the default).

If you wish to link an application against Turbo Vision, simply add -L./build/lib -ltvision to your linker and -I./include to your compiler

<div id="build-borland"></div>

Windows/DOS (Borland C++)

Turbo Vision can still be built either as a DOS or Windows library with Borland C++. Obviously, there is no Unicode support here.

I can confirm the build process works with:

• Borland C++ 4.52 with the Borland PowerPack for DOS.
• Turbo Assembler 4.0.

You may face different problems depending on your build environment. For instance, Turbo Assembler needs a patch to work under Windows 95. On Windows XP everything seems to work fine. On Windows 10, MAKE may emit the error Fatal: Command arguments too long, which can be fixed by upgrading MAKE to the one bundled with Borland C++ 5.x.

Yes, this works on 64-bit Windows 10. What won't work is the Borland C++ installer, which is a 16-bit application. You will have to run it on another environment or try your luck with winevdm.

A Borland Makefile can be found in the project directory. Build can be done by doing:

cd project
make.exe <options>

Where <options> can be:

• -DDOS32 for 32-bit DPMI applications (which still work on 64-bit Windows).
• -DWIN32 for 32-bit native Win32 applications (not possible for TVDEMO, which relies on farcoreleft() and other antiquities).
• -DDEBUG to build debug versions of the application and the library.
• -DTVDEBUG to link the applications with the debug version of the library.
• -DOVERLAY, -DALIGNMENT={2,4}, -DEXCEPTION, -DNO_STREAMABLE, -DNOTASM for things I have nave never used but appeared in the original makefiles.

This will compile the library into a LIB directory next to project, and will compile executables for the demo applications in their respective examples/* directories.

I'm sorry, the root makefile assumes it is executed from the project directory. You can still run the original makefiles directly (in source/tvision and examples/*) if you want to use different settings.

<div id="build-vcpkg"></div>

Vcpkg

Turbo Vision can be built and installed using the vcpkg dependency manager:

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

The tvision port in vcpkg is kept up to date by Microsoft team members and community contributors. If you find it to be out of date, please create an issue or pull request in the vcpkg repository.

<div id="build-cmake"></div>

Turbo Vision as a CMake dependency (not Borland C++)

If you choose the CMake build system for your application, there are two main ways to link against Turbo Vision:

• Installing Turbo Vision and importing it with find_package. Installation depends on the generator type:

  • First, decide an install prefix. The default one will work out-of-the-box, but usually requires admin privileges. On Unix systems, you can use $HOME/.local instead. On Windows, you can use any custom path you want but you'll have to add it to the CMAKE_PREFIX_PATH environment variable when building your application.

  • For mono-config generators (Unix Makefiles, Ninja...), you only have to build and install once:

    cmake . -B ./build # '-DCMAKE_INSTALL_PREFIX=...' to override the install prefix.
    cmake --build ./build
    cmake --install ./build

  • For multi-config generators (Visual Studio, Ninja Multi-Config...) you should build and install all configurations:

    cmake . -B ./build # '-DCMAKE_INSTALL_PREFIX=...' to override the install prefix.
    cmake --build ./build --config Release
    cmake --build ./build --config Debug --target tvision
    cmake --build ./build --config RelWithDebInfo --target tvision
    cmake --build ./build --config MinSizeRel --target tvision
    cmake --install ./build --config Release
    cmake --install ./build --config Debug --component library
    cmake --install ./build --config RelWithDebInfo --component library
    cmake --install ./build --config MinSizeRel --component library

  Then, in your application's CMakeLists.txt, you may import it like this:

  find_package(tvision CONFIG)
  target_link_libraries(my_application tvision::tvision)

• Have Turbo Vision in a submodule in your repository and import it with add_subdirectory:

  add_subdirectory(tvision) # Assuming Turbo Vision is in the 'tvision' directory.
  target_link_libraries(my_application tvision)

In either case, <tvision/tv.h> will be available in your application's include path during compilation, and your application will be linked against the necessary libraries (Ncurses, GPM...) automatically.

<div id="features"></div>

Features

Modern platforms (not Borland C++)

• UTF-8 support. You can try it out in the tvedit application.
• 24-bit color support (up from the original 16 colors).
• 'Open File' dialogs accepts both Unix and Windows-style file paths and can expand ~/ into $HOME.
• Redirection of stdin/stdout/stderr does not interfere with terminal I/O.
• Compatibility with 32-bit help files.

There are a few environment variables that affect the behaviour of all Turbo Vision applications:

• TVISION_MAX_FPS: maximum refresh