Modern Turbo Vision 2.0
source link: https://github.com/magiblot/tvision
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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 arquitecture, 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?
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:
-
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.
-
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.
-
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
#ifdef
s? Turbo Vision makes this possible. First: Turbo Vision keeps on usingchar
arrays instead of relying on the implementation-defined and platform-dependentwchar_t
orTCHAR
. Second: thanks to UTF-8 support insetlocale
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.
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 features and API changes sections as well.
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
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
andpalette
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.
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
if your application includes Borland headers (dir.h
,iostream.h
, etc.). -
On Gentoo (and possibly others):
-ltinfow
if bothlibtinfo.so
andlibtinfow.so
are available in your system. Otherwise, you may get a segmentation fault when running Turbo Vision applications (#11). Note thattinfo
is bundled withncurses
.
-lgpm
is only necessary if Turbo Vision was built with libgpm
support.
The backward-compatibility headers in include/tvision/compat
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.
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 Microsofts'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.
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
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 onfarcoreleft()
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.
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 theCMAKE_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.
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 rate, default60
. This can help keep smoothness in terminal emulators with unefficient handling of box-drawing characters. Special values for this option are0
, to disable refresh rate limiting, and-1
, to actually draw to the terminal in every call toTHardwareInfo::screenWrite
(useful when debugging). -
TVISION_CODEPAGE
: the character set used internally by Turbo Vision to translate extended ASCII into Unicode. Valid values at the moment are437
and850
, with437
being the default, although adding more takes very little effort.
- Ncurses-based terminal support.
- Extensive mouse and keyboard support:
- Support for X10 and SGR mouse encodings.
- Support for Xterm's modifyOtherKeys.
- Support for Paul Evans' fixterms and Kitty's keyboard protocol.
- Support for key modifiers (via
TIOCLINUX
) and mouse (via GPM) in the Linux console.
- Custom signal handler that restores the terminal state before the program crashes.
- When
stderr
is a tty, messages written to it are redirected to a buffer to prevent them from messing up the display and are eventually printed to the console when the application shuts down or is suspended.
The following environment variables are also taken into account:
-
TERM
: Ncurses uses it to determine terminal capabilities. It is set automatically by the terminal emulator. -
COLORTERM
: when set totruecolor
or24bit
, Turbo Vision will assume the terminal emulator supports 24-bit color. It is set automatically by terminal emulators that support it. -
TVISION_ESCDELAY
: the number of milliseconds to wait after receiving an ESC key press, default10
. If another key is pressed during this delay, it will be interpreted as an Alt+Key combination. Using a larger value is useful when the terminal doesn't support the Alt key. -
TVISION_USE_STDIO
: when not empty, terminal I/O is performed throughstdin
/stdout
, so that it can be redirected from the shell. By default, Turbo Vision performs terminal I/O through/dev/tty
, allowing the user to redirectstdin
,stdout
andstderr
for their needs, without affecting the application's stability.For example, the following will leave
out.txt
empty:tvdemo | tee out.txt
While the following will dump all the escape sequences and text printed by the application into
out.txt
:TVISION_USE_STDIO=1 tvdemo | tee out.txt
-
TVISION_DISPLAY
: strategy for drawing to screen. Valid values areansi
andncurses
, withansi
being the default. The Ncurses library is used in either case, with the difference thatncurses
uses Ncurses' own draw methods and is limited to 16 colors, whileansi
supports 24-bit color and avoids redundant buffering and UTF-8 to wide char conversions.
Windows
- Only compatible with the Win32 Console API. On terminal emulators that don't support this, Turbo Vision will automatically pop up a separate console window.
- Applications fit the console window size instead of the buffer size (no scrollbars are visible) and the console buffer is restored when exiting or suspending Turbo Vision.
The following are not available when compiling with Borland C++:
- The console's codepage is set to UTF-8 on startup and restored on exit.
- Microsoft's C runtime functions are set automatically to UTF-8 mode, so you as a developer don't need to use the
wchar_t
variants. - If the console crashes, a new one is allocated automatically.
Note: Turbo Vision writes UTF-8 text directly to the Windows console. If the console is set in legacy mode and the bitmap font is being used, Unicode characters will not be displayed properly (photo). To avoid this, Turbo Vision detects this situation and tries to change the console font to Consolas
or Lucida Console
.
All platforms
The following are new features not available in Borland's release of Turbo Vision or in previous open source ports (Sigala, SET):
- Middle mouse button and mouse wheel support.
- Arbitrary screen size support (up to 32767 rows or columns) and graceful handling of screen resize events.
- Windows can be resized from their bottom left corner.
- Windows can be dragged from empty areas with the middle mouse button.
- Improved usability of menus: they can be closed by clicking again on the parent menu item.
- Improved usability of scrollbars: dragging them also scrolls the page. Clicking on an empty area of the scrollbar moves the thumb right under the cursor. They respond by default to mouse wheel events.
TInputLine
s no longer scroll the text display on focus/unfocus, allowing relevant text to stay visible.- Support for LF line endings in
TFileViewer
(tvdemo
) andTEditor
(tvedit
).TEditor
preserves the line ending on file save but all newly created files use CRLF by default. TEditor
: context menu on right click.TEditor
: drag scroll with middle mouse button.TEditor
,TInputLine
: delete whole words withkbAltBack
,kbCtrlBack
andkbCtrlDel
.TEditor
: the Home key toggles between beginning of line and beginning of indented text.TEditor
: support for files bigger than 64 KiB on 32-bit or 64-bit builds.tvdemo
: event viewer applet useful for event debugging.tvdemo
: option to change the background pattern.
API changes
-
Screen writes are buffered and are usually sent to the terminal once for every iteration of the active event loop (see also
TVISION_MAX_FPS
). If you need to update the screen during a busy loop, you may useTScreen::flushScreen()
. -
TDrawBuffer
is no longer a fixed-length array. The equivalent ofsizeof(TDrawBuffer)/sizeof(ushort)
is the.length()
method. -
TTextDevice
is now buffered, so if you were usingotstream
you may have to sendstd::flush
orstd::endl
through it fordo_sputn
to be invoked. -
TApplication
now providesdosShell()
,cascade()
andtile()
, and handlescmDosShell
,cmCascade
andcmTile
by default. These functions can be customized by overridinggetTileRect()
andwriteShellMsg()
. This is the same behaviour as in the Pascal version. -
Mouse wheel support: new mouse event
evMouseWheel
. The wheel direction is specified in the new fieldevent.mouse.wheel
, whose possible values aremwUp
,mwDown
,mwLeft
ormwRight
. -
Middle mouse button support: new mouse button flag
mbMiddleButton
. -
The
buttons
field inevMouseUp
events is no longer empty. It now indicates which button was released. -
Triple-click support: new mouse event flag
meTripleClick
. -
TRect
methodsmove
,grow
,intersect
andUnion
now returnTRect&
instead of beingvoid
so that they can be chained. -
TOutlineViewer
now allows the root node to have siblings. -
New function
ushort popupMenu(TPoint where, TMenuItem &aMenu, TGroup *receiver=0)
which spawns aTMenuPopup
on the desktop. Seesource/tvision/popupmnu.cpp
. -
New virtual method
TMenuItem& TEditor::initContextMenu(TPoint p)
that determines the entries of the right-click context menu inTEditor
. -
fexpand
can now take a second parameterrelativeTo
. -
New class
TStringView
, inspired bystd::string_view
.- Many functions which originally had null-terminated string parameters now receive
TStringView
instead.TStringView
is compatible withstd::string_view
,std::string
andconst char *
(evennullptr
).
- Many functions which originally had null-terminated string parameters now receive
-
New class
TSpan<T>
, inspired bystd::span
. -
New classes
TDrawSurface
andTSurfaceView
, see<tvision/surface.h>
. -
New method
TVMemMgr::reallocateDiscardable()
which can be used alongallocateDiscardable
andfreeDiscardable
. -
New method
TView::textEvent()
which allows receiving text in an efficient manner, see Clipboard interaction. -
Unicode support, see Unicode.
-
True Color support, see extended colors.
-
New method
static void TEvent::waitEvent(int timeoutMs)
which may block for up totimeoutMs
milliseconds waiting for input events. If it blocks, it has the side effect of flushing screen updates. It is invoked byTProgram::getEvent()
withstatic int TProgram::appEventTimeout
(default20
) as argument so that the event loop doesn't consume 100% CPU. -
New method
static void TEvent::putNothing()
which puts anevNothing
event into the event queue and causesTEvent::waitEvent()
not to block until anevNothing
is returned byTEvent::getKeyEvent()
. This will usually cause the main thread to wake up fromTEvent::waitEvent()
and to invokeTApplication::idle()
immediately. This method is thread-safe, so it can be used to unblock the event loop from any other thread. -
It is now possible to specify a maximum text width or maximum grapheme count in
TInputLine
. This is done through a new parameter inTInputLine
's constructor,ushort limitMode
, which controls how the second constructor parameter,uint limit
, is to be treated. TheilXXXX
constants define the possible values oflimitMode
:ilMaxBytes
(the default): the text can be up tolimit
bytes long, including the null terminator.ilMaxWidth
: the text can be up tolimit
columns wide.ilMaxGraphemes
: the text can contain up tolimit
non-combining characters.
In any case, the text in a
TInputLine
can never be more than 256 bytes long, including the null terminator.
Screenshots
You will find some screenshots here. Feel free to add your own!
Contributing
If you know of any Turbo Vision applications whose source code has not been lost and that could benefit from this, let me know.
Applications using Turbo Vision
If your application is based on this project and you'd like it to appear in the following list, just let me know.
- Turbo by magiblot, a proof-of-concept text editor.
- tvterm by magiblot, a proof-of-concept terminal emulator.
- TMBASIC by Brian Luft, a programming language for creating console applications.
Unicode support
The Turbo Vision API has been extended to allow receiving Unicode input and displaying Unicode text. The supported encoding is UTF-8, for a number of reasons:
- It is compatible with already present data types (
char *
), so it does not require intrusive modifications to existing code. - It is the same encoding used for terminal I/O, so redundant conversions are avoided.
- Conformance to the UTF-8 Everywhere Manifesto, which exposes many other advantages.
Note that when built with Borland C++, Turbo Vision does not support Unicode. However, this does not affect the way Turbo Vision applications are written, since the API extensions are designed to allow for encoding-agnostic code.
Reading Unicode input
The traditional way to get text from a key press event is as follows:
// 'ev' is a TEvent, and 'ev.what' equals 'evKeyDown'. switch (ev.keyDown.keyCode) { // Key shortcuts are usually checked first. // ... default: { // The character is encoded in the current codepage // (CP437 by default). char c = ev.keyDown.charScan.charCode; // ... } }
Some of the existing Turbo Vision classes that deal with text input still depend on this methodology, which has not changed. Single-byte characters, when representable in the current codepage, continue to be available in ev.keyDown.charScan.charCode
.
Unicode support consists in two new fields in ev.keyDown
(which is a struct KeyDownEvent
):
char text[4]
, which may contain whatever was read from the terminal: usually a UTF-8 sequence, but possibly any kind of raw data.uchar textLength
, which is the number of bytes of data available intext
, from 0 to 4.
Note that the text
field may contain garbage or uninitialized data from position textLength
on.
You can also get a TStringView
out of a KeyDownEvent
with the getText()
method.
So a Unicode character can be retrieved from TEvent
in the following way:
switch (ev.keyDown.keyCode) { // ... default: { std::string_view sv = ev.keyDown.getText(); processText(sv); } }
Let's see it from another perspective. If the user types ñ
, a TEvent
is generated with the following keyDown
struct:
KeyDownEvent { union { .keyCode = 0xA4, .charScan = CharScanType { .charCode = 164 ('ñ'), // In CP437 .scanCode = 0 } }, .controlKeyState = 0x200 (kbInsState), .text = {'\xC3', '\xB1'}, // In UTF-8 .textLength = 2 }
However, if they type €
the following will happen:
KeyDownEvent { union { .keyCode = 0x0 (kbNoKey), // '€' not part of CP437 .charScan = CharScanType { .charCode = 0, .scanCode = 0 } }, .controlKeyState = 0x200 (kbInsState), .text = {'\xE2', '\x82', '\xAC'}, // In UTF-8 .textLength = 3 }
If a key shortcut is pressed instead, text
is empty:
KeyDownEvent { union { .keyCode = 0xB (kbCtrlK), .charScan = CharScanType { .charCode = 11 ('♂'), .scanCode = 0 } }, .controlKeyState = 0x20C (kbCtrlShift | kbInsState), .text = {}, .textLength = 0 }
So, in short: views designed without Unicode input in mind will continue to work exactly as they did before, and views which want to be Unicode-aware will have no issues in being so.
Displaying Unicode text
The original design of Turbo Vision uses 16 bits to represent a screen cell—8 bit for a character and 8 bit for BIOS color attributes.
A new TScreenCell
type is defined in <tvision/scrncell.h>
which is capable of holding a limited number of UTF-8 codepoints in addition to extended attributes (bold, underline, italic...). However, you should not write text into a TScreenCell
directly but make use of Unicode-aware API functions instead.
Text display rules
A character provided as argument to any of the Turbo Vision API functions that deal with displaying text is interpreted as follows:
- Non-printable characters in the range
0x00
to0xFF
are interpreted as characters in the active codepage. For instance,0x7F
is displayed as⌂
and0xF0
as≡
if using CP437. As an exception,0x00
is always displayed as a regular space. These characters are all one column wide. - Character sequences which are not valid UTF-8 are interpreted as sequences of characters in the current codepage, as in the case above.
- Valid UTF-8 sequences with a display width other than one are taken care of in a special way, see below.
For example, the string "╔[\xFE]╗"
may be displayed as ╔[■]╗
. This means that box-drawing characters can be mixed with UTF-8 in general, which is useful for backward compatibility. If you rely on this behaviour, though, you may get unexpected results: for instance, "\xC4\xBF"
is a valid UTF-8 sequence and is displayed as Ŀ
instead of ─┐
.
One of the issues of Unicode support is the existence of multi-width characters and combining characters. This conflicts with Turbo Vision's original assumption that the screen is a grid of cells occupied by a single character each. Nevertheless, these cases are handled in the following way:
-
Multi-width characters can be drawn anywhere on the screen and nothing bad happens if they overlap partially with other characters.
-
Zero-width characters overlay the previous character. For example, the sequence
में
consists of the single-width characterम
and the combining charactersे
andं
. In this case, three Unicode codepoints are fit into the same cell.The
ZERO WIDTH JOINER
(U+200D
) is always omitted, as it complicates things too much. For example, it can turn a string like"👩👦"
(4 columns wide) into"👩👦"
(2 columns wide). Not all terminal emulators respect the ZWJ, so, in order to produce predictable results, Turbo Vision will print both"👩👦"
and"👩👦"
as👩👦
. -
No notable graphical glitches will occur as long as your terminal emulator respects character widths as measured by
wcwidth
.
Here is an example of such characters in the Turbo text editor:
Unicode-aware API functions
The usual way of writing to the screen is by using TDrawBuffer
. A few methods have been added and others have changed their meaning:
void TDrawBuffer::moveChar(ushort indent, char c, TColorAttr attr, ushort count); void TDrawBuffer::putChar(ushort indent, char c);
c
is always interpreted as a character in the active codepage.
ushort TDrawBuffer::moveStr(ushort indent, TStringView str, TColorAttr attr); ushort TDrawBuffer::moveCStr(ushort indent, TStringView str, TAttrPair attrs);
str
is interpreted according to the rules exposed previously.
ushort TDrawBuffer::moveStr(ushort indent, TStringView str, TColorAttr attr, ushort width, ushort begin=0); // New
str
is interpreted according to the rules exposed previously. However:
width
specifies the maximum number of display columns that should be read fromstr
.begin
specifies the number of display columns that should be skipped at the beginning ofstr
. This is useful for horizontal scrolling. Ifbegin
is in the middle of a multi-width character, the remaining positions in that character are filled with spaces.
The return values are the number of display columns that were actually filled with text.
void TDrawBuffer::moveBuf(ushort indent, const void *source, TColorAttr attr, ushort count);
The name of this function is misleading. Even in its original implementation, source
is treated as a string. So it is equivalent to moveStr(indent, TStringView((const char*) source, count), attr)
.
There are other useful Unicode-aware functions:
int cstrlen(TStringView s);
Returns the displayed length of s
according to the aforementioned rules, discarding ~
characters.
int strwidth(TStringView s); // New
Returns the displayed length of s
.
On Borland C++, these methods assume a single-byte encoding and all characters being one column wide. This makes it possible to write encoding-agnostic draw()
and handleEvent()
methods that work on both platforms without a single #ifdef
.
The functions above are implemented using the functions from the TText
namespace, another API extension. You will have to use them directly if you want to fill TScreenCell
objects with text manually. To give an example, below are some of the TText
functions. You can find all of them with complete descriptions in <tvision/ttext.h>
.
size_t TText::next(TStringView text); size_t TText::prev(TStringView text, size_t index); void TText::drawChar(TSpan<TScreenCell> cells, char c); size_t TText::drawStr(TSpan<TScreenCell> cells, size_t indent, TStringView text, int textIndent); bool TText::drawOne(TSpan<TScreenCell> cells, size_t &i, TStringView text, size_t &j);
For drawing TScreenCell
buffers into a view, the following methods are available:
void TView::writeBuf(short x, short y, short w, short h, const TScreenCell *b); // New void TView::writeLine(short x, short y, short w, short h, const TScreenCell *b); // New
Example: Unicode text in menus and status bars
It's as simple as it can be. Let's modify hello.cpp
as follows:
TMenuBar *THelloApp::initMenuBar( TRect r ) { r.b.y = r.a.y+1; return new TMenuBar( r, *new TSubMenu( "~Ñ~ello", kbAltH ) + *new TMenuItem( "階~毎~料入報最...", GreetThemCmd, kbAltG ) + *new TMenuItem( "五劫~の~擦り切れ", cmYes, kbNoKey, hcNoContext ) + *new TMenuItem( "העברית ~א~ינטרנט", cmNo, kbNoKey, hcNoContext ) + newLine() + *new TMenuItem( "E~x~it", cmQuit, cmQuit, hcNoContext, "Alt-X" ) ); } TStatusLine *THelloApp::initStatusLine( TRect r ) { r.a.y = r.b.y-1; return new TStatusLine( r, *new TStatusDef( 0, 0xFFFF ) + *new TStatusItem( "~Alt-Ç~ Exit", kbAltX, cmQuit ) + *new TStatusItem( 0, kbF10, cmMenu ) ); }
Here is what it looks like:
Example: writing Unicode-aware draw()
methods
The following is an excerpt from an old implementation of TFileViewer::draw()
(part of the tvdemo
application), which does not draw Unicode text properly:
if (delta.y + i < fileLines->getCount()) { char s[maxLineLength+1]; p = (char *)(fileLines->at(delta.y+i)); if (p == 0 || strlen(p) < delta.x) s[0] = EOS; else strnzcpy(s, p+delta.x, maxLineLength+1); b.moveStr(0, s, c); } writeBuf( 0, i, size.x, 1, b );
All it does is move part of a string in fileLines
into b
, which is a TDrawBuffer
. delta
is a TPoint
representing the scroll offset in the text view, and i
is the index of the visible line being processed. c
is the text color. A few issues are present:
TDrawBuffer::moveStr(ushort, const char *, TColorAttr)
takes a null-terminated string. In order to pass a substring of the current line, a copy is made into the arrays
, at the risk of a buffer overrun. The case where the line does not fit intos
is not handled, so at mostmaxLineLenght
characters will be copied. What's more, a multibyte character near positionmaxLineLength
could be copied incompletely and be displayed as garbage.delta.x
is the first visible column. With multibyte-encoded text, it is no longer true that such column begins at positiondelta.x
in the string.
Below is a corrected version of the code above that handles Unicode properly:
if (delta.y + i < fileLines->getCount()) { p = (char *)(fileLines->at(delta.y+i)); if (p) b.moveStr(0, p, c, size.x, delta.x); } writeBuf( 0, i, size.x, 1, b );
The overload of moveStr
used here is TDrawBuffer::moveStr(ushort indent, TStringView str, TColorAttr attr, ushort width, ushort begin)
. This function not only provides Unicode support, but also helps us write cleaner code and overcome some of the limitations previously present:
- The intermediary copy is avoided, so the displayed text is not limited to
maxLineLength
bytes. moveStr
takes care of printing the string starting at columndelta.x
. We do not even need to worry about how many bytes correspond todelta.x
columns.- Similarly,
moveStr
is instructed to copy at mostsize.x
columns of text without us having to care about how many bytes that is nor dealing with edge cases. The code is written in an encoding-agnostic way and will work whether multibyte characters are being considered or not. - In case you hadn't realized yet, the intermediary copy in the previous version was completely unnecessary. It would have been necessary only if we had needed to trim the end of the line, but that was not the case: text occupies all of the view's width, and
TView::writeBuf
already takes care of not writing beyond it. Yet it is interesting to see how an unnecessary step not only was limiting functionality but also was prone to bugs.
Unicode support across standard views
Support for creating Unicode-aware views is in place, and most views in the original Turbo Vision library have been adapted to handle Unicode.
The following views can display Unicode text properly. Some of them also do horizontal scrolling or word wrapping; all of that should work fine.
-
TStaticText
(7b15d45d
). -
TFrame
(81066ee5
). -
TStatusLine
(477b3ae9
). -
THistoryViewer
(81066ee5
). -
THelpViewer
(81066ee5
,8c7dac2a
,20f331e3
). -
TListViewer
(81066ee5
). -
TMenuBox
(81066ee5
). -
TTerminal
(ee821b69
). -
TOutlineViewer
(6cc8cd38
). -
TFileViewer
(from thetvdemo
application) (068bbf7a
). -
TFilePane
(from thetvdir
application) (9bcd897c
).
The following views can, in addition, process Unicode text or user input:
-
TInputLine
(81066ee5
,cb489d42
). -
TEditor
(702114dc
). Instances are in UTF-8 mode by default. You may switch back to single-byte mode by pressingCtrl+P
. This only changes how the document is displayed and the encoding of user input; it does not alter the document. This class is used in thetvedit
application; you may test it there.
Views not in this list may not have needed any corrections or I simply forgot to fix them. Please submit an issue if you notice anything not working as expected.
Use cases where Unicode is not supported (not an exhaustive list):
- Highlighted key shortcuts, in general (e.g.
TMenuBox
,TStatusLine
,TButton
...).
Clipboard interaction
The Turbo Vision API offers no integration with the system clipboard. As a developer you can still access it by other means (e.g. via libclipboard). But unless you do that, the only way for a user to paste text into your application is to do so through the terminal emulator.
Unfortunately, each character is processed as a separate evKeyDown
event. If the user pastes 5000 characters, the application will execute the same operations as if the user pressed the keyboard 5000 times. This involves drawing views, completing the event loop, updating the screen, etcetera. As you can imagine, this is far from optimal.
For the purpose of dealing with this situation, the Turbo Vision API has been extended with the following function:
Boolean TView::textEvent(TEvent &event, TSpan<char> dest, size_t &length);
TEditor
takes advantage of this function to provide a good user experience when pasting text through the terminal. You can check it out in the tvedit
application. As a developer, you may be interested in using it if you are implementing a text editing component. Otherwise, you don't need to care about it.
Just for the record, here is a more detailed explanation:
textEvent()
tries to read text from standard input and stores it in a user-provided buffer dest
. It returns False
when no more events are available in the program's input queue or if a non-text event is found, in which case this event is saved with putEvent()
so that it can be processed in the next iteration of the event loop.
The exact number of bytes read is stored in the output parameter length
, which can never be greater than dest.size()
.
It is intended to be used as follows:
// 'ev' is a TEvent, and 'ev.what' equals 'evKeyDown'. // If the event contains text... if (ev.keyDown.textLength) { char buf[512]; size_t length; // Fill 'buf' with text from the input queue, // including the text in 'ev'. while (textEvent(ev, buf, length)) { // Process 'length' bytes of text in 'buf'. // ... } // 'textEvent()' clears 'ev' after reading it the first time // (by this point, 'ev.what' is 'evNothing'). }
Extended color support
The Turbo Vision API has been extended to allow more than the original 16 colors.
Colors can be specified using any of the following formats:
- BIOS color attributes (4-bit), the format used originally on MS-DOS.
- RGB (24-bit).
xterm-256color
palette indices (8-bit).- The terminal default color. This is the color used by terminal emulators when no display attributes (bold, color...) are enabled (usually white for foreground and black for background).
Although Turbo Vision applications are likely to be ran in a terminal emulator, the API makes no assumptions about the display device. That is, the complexity of dealing with terminal emulators is hidden from the programmer and managed by Turbo Vision itself.
For example: color support varies among terminals. If the programmer uses a color format not supported by the terminal emulator, Turbo Vision will quantize it to what the terminal can display. The following images represent the quantization of a 24-bit RGB picture to 256, 16 and 8 color palettes:
24-bit color (original) 256 colors
16 colors 8 colors (bold as bright)
Extended color support basically comes down to the following:
- Turbo Vision has originally used BIOS color attributes stored in an
uchar
.ushort
is used to represent attribute pairs. This is still the case when using Borland C++. - In modern platforms a new type
TColorAttr
has been added which replacesuchar
. It specifies a foreground and background color and a style. Colors can be specified in different formats (BIOS color attributes, 24-bit RGB...). Styles are the typical ones (bold, italic, underline...). There's alsoTAttrPair
, which replacesushort
. TDrawBuffer
's methods, which used to takeuchar
orushort
parameters to specify color attributes, now takeTColorAttr
orTAttrPair
.TPalette
, which used to contain an array ofuchar
, now contains an array ofTColorAttr
. TheTView::mapColor
method also returnsTColorAttr
instead ofuchar
.TView::mapColor
has been made virtual so that the palette system can be bypassed without having to rewrite anydraw
methods.TColorAttr
andTAttrPair
can be initialized with and casted intouchar
andushort
in a way such that legacy code still compiles out-of-the-box without any change in functionality.
Below is a more detailed explanation aimed at developers.
API reference of extended color support (click to expand).
Recommend
-
90
turbo-rpc is super fast
-
100
GitHub is where people build software. More than 28 million people use GitHub to discover, fork, and contribute to over 79 million projects.
-
104
程序员 - @Lispre - 最近要做一个新的东西,类似工具类的东西。对比了市面上的开源选择和需求情况,最终决定用 C 从 0 做起。不知道内心是出于什么考虑(好像是情怀在作怪吧),我选择用 **TC 2.0 作为
-
67
In this 4-part introductory React Native series, we go from learning some React Native basic components and layout all the way to integrating Redux and storing camera images in the cloud. By going over some React Native...
-
38
There's a software ready to help ethereum scale – right now. Revealed exclusively to CoinDesk, the raw architecture of Turbo Geth has been completed — and is currently available to early adopters for testing. Al...
-
36
Supporting the UFS turbo-write mode By Jake Edge May 20, 2019 LSFMM UFS是Universal Flash Storage的简称,跟eMMC设备类似的存储设备。Avri Altman在 2019 LS...
-
12
Day One at the TIBCO Analytics Forum 2021: A Vision for the Modern Analytics Enterprise Search ...
-
5
https://github.com/eduardolundgren/tracking.js/issues/395
-
3
Thanks to modern science and one artist's vision, plants can now wield swords Crouching Tiger Lily, Hidden Snap Dragon? By
-
6
Introduction The Swin Transformer is a significant innovation in the field of vision transformers.
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK