[Top] [Contents] [Index] [ ? ]

TVision library installation handbook

This document covers the installation and operation of TVision under the FreeBSD and Linux operating systems.

1. Overview  An overview of the TVision package.
2. Reporting Bugs  Submitting effective bug reports.
3. File Structure  Notes on the file hierarchy.
4. Copyright  This copyright license says how you can copy and use TVision.

5. Portability issues  The portability of the package.
6. Keyboard  The keyboard handling.
7. Screen  The screen handling.
8. Mouse  The mouse handling.
9. Environment Variables  The user modifiable environment variables.

10. Compiling TVision  How to compile the library.
11. Resources  A list of useful sites.

12. Credits  Contributors and useful links.
13. Author's address  To send him a nice postcard.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Overview

Turbo Vision (or TV, for short) is a library that provides an application framework. With TV you can write a beautiful object-oriented character-mode user interface in a short time.

TV is available in C++ and Pascal and is a product of Borland International. It was developed to run on MS-DOS systems, but today it is available for many other platforms (ported by independent programmers).

This port is based on the Borland 2.0 version with fixes. Original Turbo Vision 2.0 sources should be available at:

ftp://ftp.borland.com/pub/borlandcpp/devsupport/archive/turbovision

ftp://ftp.inprise.com/pub/borlandcpp/devsupport/archive/turbovision

See the 12. Credits section for a list of other useful sites.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Reporting Bugs

We welcome bug reports or suggestions for the TVision system, both programs and documentations. Please email them to sergio@sigala.it. You can download the latest version of TVision from http://www.sigala.it/sergio/tvision.

For bug reports, please include enough information for the maintainers to reproduce the problem. Generally speaking, that means:

When in doubt whether something is needed or not, include it. It's better to include too much than to leave out something important.

Patches are most welcome; if possible, please make them with `diff -ru' (see See section `Overview' in The diff program, for details).

When sending email, please do not encode or split the messages in any way if possible; it's much easier to deal with one plain text message, however large, than many small ones.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. File Structure

A few notes on the file hierarchy used in this package.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Copyright

All changes copyright (c) 1997-2001 Sergio Sigala, Brescia, Italy. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Warning: this BSD-style copyright is applicable only to the modifications brought by Sergio Sigala to the original code. Borland has released the code to the public, but still owns the original copyright (see file `lib/tv.h' for instance).

Other contributors have their respective copyright.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Portability issues

The TV library was originally written to run on 80x86 processor. These processors are little-endian and the original library assumes this as a premise. In fact, some code may not run properly on big-endian machines. This means it requires a big effort to make the library fully portable across all Unix machines.

I made various changes in the code to make it run correctly under big-endian machines. I tested it with a PowerPC running Linux and it works fine (maybe some other minor changes are required).

Another problem is the massive usage of the PC-specific character set. This usually gives a nice look when the applications run in the system console, but can show very annoying characters when they run in a remote terminal or under a X shell.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Keyboard

The ncurses library is systematically used in TVision to perform keyboard input, and usually to do video output also. These routines give the user a terminal-independent method for getting input characters and to update character screens with reasonable optimization. The name `ncurses' stands for `new curses' and is the approved replacement for the 4.4BSD classic `curses' library, which has been discontinued.

More specifically, the ncurses package supports:

In addition to drawing characters on the screen, video attributes and colors may be supported, causing the characters to show up in such modes as underlined, in reverse video, or in color on terminals that support such display enhancements. Line drawing characters may be specified to be output. On input, ncurses is also able to translate arrow and function keys that transmit escape sequences into single value integers. Type `man ncurses' for more.

Under Linux a special output mechanism called VCS, which gives direct access to the console screen memory, may be used. This is noticeably faster than the standard ncurses output. See 7. Screen for details.

Key combinations

Two notes, whose applicability is strictly dependent on the operating system you are using:

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Screen

A few, useful notes about screen handling.

The importance of SIGWINCH

The `SIGWINCH' signal is always hooked, so we can resize the screen at runtime and the application will adapt itself. Obviously, this capability is especially useful in X shells.

Two drawbacks of ncurses

Like mentioned previously, the ncurses library is usually used to perform video output. This should work well under any operating system, in any kind of terminal (system console, dumb terminal or X shell). But there are at least two problems with this otherwise perfectly portable solution:

  1. This mechanism can't output all the 256 characters the 8 bit encoding would permit, including those nice semi-graphical signs usually used in text-mode applications on PCs. Since TVision uses them all (to draw frames, window icons and various other views), your application may appear graphically poor.

  2. This mechanism is slow. On the system console it's slower on Linux than FreeBSD, because of the advanced system FreeBSD uses to update the screen memory. Equally slow on the other kinds of terminal. This limit appears noticeably on 486 and low-end Pentiums.

There is no way to speedup this process without doing some low-level, operating-system-specific trickery, necessarily non portable across the various operating systems.

The Linux way: virtual console mode versus remote mode

Linux has a special output mechanism called VCS (or VCSA), which gives direct access to the screen memory. VCS stands for virtual console system.

This mechanism is a lot faster than the standard ncurses output; we'll call it virtual console mode. For clearness, we'll refer to the conventional, ncurses-based output approach, as remote mode. Not surprising, this facility is capable of displaying all of the 256 characters with all colors the graphic adapter allows, so it fixes the first problem too.

The Linux kernel provides a handful of special devices which refer to the memories of the various virtual consoles; they are described below:

These devices replace the screendump ioctls of `console(4)', so the system administrator can control access using file system permissions. Your application may require root privileges, in order to gain access to these devices. Type `man vcs' for more.

If not already present, the devices for the first eight virtual consoles may be created by:

 
for x in 0 1 2 3 4 5 6 7 8; do
        mknod -m 644 /dev/vcs$x c 7 $x;
        mknod -m 644 /dev/vcsa$x c 7 $[$x+128];
done
chown root:tty /dev/vcs*

Alternatively, you may try the following script, taken from the Midnight Commander, which builds all the 64 devices:

 
#!/bin/sh
#
# Script by Jakub Jelinek
#
if test -e /dev/vcs0
then
        exit
fi

I=0
while [ $I -lt 64 ] 
do
        mknod /dev/vcs$I c 7 $I
        chmod 622 /dev/vcs$I
        chown root.tty /dev/vcs$I
        mknod /dev/vcsa$I c 7 `expr $I + 128`
        chmod 622 /dev/vcsa$I
        chown root.tty /dev/vcsa$I
        I=`expr $I + 1`
done

Conclusions on Linux

Under Linux every program can run in two ways:

In any case, colors are used if the terminal supports them. Otherwise, a monochrome palette with bold and inverse attributes is used to mark the text.

Two notes on FreeBSD

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8. Mouse

The mouse handling varies a lot, depending on the operating system you are using. If you need to change some timing see the `system.cc' file.

Mouse support under FreeBSD

The library requires the `moused' daemon to be loaded. See the moused man page (by typing `man moused') for more details. For example, if you have a Microsoft compatible mouse connected to COM1, you should issue this command:

 
moused -p /dev/cuaa0 -t microsoft

By using the `TVOPT' environment variable, you can modify the shape of the cursor. Setting it to `noarrow' disables the arrow pointer; the block pointer will instead be used. See the 9. Environment Variables section for more.

Mouse support under Linux

The library requires `Gpm'. The Gpm package is a mouse server for the Linux console. It is meant to provide cooked mouse events to text-only applications, such as editors and simple menu-based programs. I tested TVision with Gpm version 1.18.1.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. Environment Variables

By setting the two environment variables `TVLOG' and `TVOPT', you can modify the way TVision applications act on your system.

TVLOG

With `TVLOG' you can force TVision to write a log file. For example, the following line will produce a log file named `mylog' when the application is executed:

 
TVLOG=mylog

The log file creation can be suppressed by assigning an empty string to this variable.

TVOPT

You can modify some of the behavior of the library by defining the other environment variable `TVOPT'. This variable is a set of strings separated by one or more space characters. Valid strings are:

`cyrillic'
enables cyrillic character set mapping (for Linux and VCS only). See 7. Screen for more about VCS.

`latin'
enables latin character set mapping (for Linux and VCS only). See 7. Screen for more about VCS.

Note: this option and the one above are useful only when the VCS is enabled; in any other mode the application should automatically select the correct mapping, thanks to the translation kindly done by ncurses and the operating system.

`noarrow'
disables the arrow pointer (FreeBSD only); the block pointer will instead be used. See 8. Mouse for more about mouse handling.

`nogpm'
disables support for the Gpm mouse driver (Linux only); the application will run without mouse. See 8. Mouse for more about mouse handling.

`novcs'
inhibits the use of VCS to do video output (Linux only); the application will always use remote mode. See 7. Screen for more about VCS.

Examples for the Bourne shell

 
export TVOPT=nogpm         ==> does not use Gpm
export TVOPT="nogpm novcs" ==> disables both Gpm and VCS
export TVOPT=              ==> cleans the environment variable

Examples for the C shell

 
setenv TVOPT nogpm         ==> does not use Gpm
setenv TVOPT "nogpm novcs" ==> disables both Gpm and VCS
unsetenv TVOPT             ==> cleans the environment variable

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10. Compiling TVision

This section gives you some information for installing TVision. For further details please read the `INSTALL' file that can be found in the root directory of the source package.

Quick start

To start, just say `./configure && make' to your shell. Binaries are not released with the package because it's safer for you to compile the package by yourself.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. Resources

Please connect to http://www.sigala.it/sergio/tvision for fresh resources. It is the official TVision site, from which you can download the latest version of the package; there is a number of example programs too.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12. Credits

The following are most of the contributors, listed in chronologic order. Sorry if I missed somebody (please contact me in case I did, sergio@sigala.it).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13. Author's address 

Sergio Sigala sergio@sigala.it
Viale De Gasperi, 8
25041 Boario Terme (BS)
Italy

[Top] [Contents] [Index] [ ? ]

Table of Contents

1. Overview
2. Reporting Bugs
3. File Structure
4. Copyright
5. Portability issues
6. Keyboard
7. Screen
8. Mouse
9. Environment Variables
10. Compiling TVision
11. Resources
12. Credits
13. Author's address
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Overview
2. Reporting Bugs
3. File Structure
4. Copyright
5. Portability issues
6. Keyboard
7. Screen
8. Mouse
9. Environment Variables
10. Compiling TVision
11. Resources
12. Credits
13. Author's address
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated using texi2html

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack previous or up-and-previous section 1.1
[ Up ] Up up section 1.2
[ >> ] FastForward next or up-and-next section 1.3
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index concept index  
[ ? ] About this page  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated by Sergio Sigala on September, 22 2001 using texi2html