VT

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

VT - virtual terminal package for STDWIN  

SYNOPSIS

#include "stdwin.h"
#include "vt.h"

VT *vtopen(char *title, int rows, int cols, int saverows);
void vtclose(VT *vt);
void vtansiputs(VT *vt, char *text, int len);
void vtsetcursor(VT *vt, int row, int col);
void vtreset(VT *vt);
bool vtresize(VT *vt, int rows, int cols, int saverows);
bool vtautosize(VT *vt);
VT *vtfind(WINDOW *win);
void vtsend(VT *vt, char *text, int buf);

/* The following functions are actually macros */
WINDOW *vtwindow(VT *vt);
int vtcwidth(VT *vt);
int vtcheight(VT *vt);
void vtsetnlcr(VT *vt, bool nlcr);
void vtsetlazy(VT *vt, bool lazy);
 

DESCRIPTION

VT is a package which emulates one or more virtual terminals in STDWIN windows. A VT structure contains a WINDOW pointer and data structures to save the screen contents, cursor position, etc. Such a virtual terminal may be used to implement a terminal emulation program on a micro-computer (which was the original goal of this programming exercise), or as a tool to simplify interfacing a program using printf-style output to STDWIN. The virtual terminal's cursor position is indicated by STDWIN's standard text caret, appearing to the left of the character at the cursor position. This actually feels very natural in most cases.

The functions you might want to know about are:

vtopen
Creates the window and returns a pointer to a VT struct. Rows and cols specify the size of the virtual terminal; saverows specifies the number of rows saved after they have scrolled off the top of the terminal. If something went wrong, a nil pointer is returned.
vtclose
Closes the window and deallocates the data contained in the VT struct.
vtansiputs
Sends an output string to the virtual terminal. Len specifies the length of the string; if it is negative, the string is terminated by a null character. Control character and escape sequence processing is done in the style of ANSI terminals, with some limitations and extensions. Warning: unless vtsetnlcr(vt, 1) has been called, both a CR and LF character must be sent to properly start a new line.
vtsetcursor
Moves the terminal's cursor to the indicated position. The top left corner of the virtual terminal is position (0, 0).
vtreset
Completely resets the virtual terminal to its initial state. The cursor is moved to position (0, 0). The lazy and nlcr flags are not changed.
vtresize
Changes the dimensions of the virtual terminal to explicitly given numbers. In case of memory shortage, this function may fail irrecoverably, leaving the VT struct in an unusable state (except to vtclose).
vtautosize
Changes the dimensions of the virtual terminal to conform to the new window size. If possible, the sum of rows and saverows is kept constant. The same limitations as for vtresize apply.
vtfind
Given a window pointer, returns a pointer to the VT struct containing that window. Returns a nil pointer if no such VT struct exists.
vtsend
This function is defined in the library, but you might want to write your own version. It is called by the library for cases where the virtual terminal must send a reply back to the computer system. (This happens in response to certain ANSI escape sequences, in particular ESC-[-6-n or ESC-[-c.) You may want to ignore this output, or actually send it down a serial line if you are implementing a terminal emulator program for a micro-computer. The library's default version calls vtansiputs with the same parameters as passed to vtsend.
vtwindow
Returns a pointer to the window contained in the VT struct.
vtcwidth
Returns the width of characters drawn in the VT's window.
vtcheight
Returns the height of characters drawn in the VT's window.
vtsetnlcr
Turns the nlcr option on or off. When on, every LF character received is translated into a CR plus LF. This is useful if you want to perform C style output to a VT window, where lines are terminated by a single LF. Initially this option is off.
vtsetlazy
Turns the lazy option on or off. When on, actual output to the terminal is delayed until the window's draw procedure is called; when off, all output is drawn immediately. Initially this option is off.
 

ANSI ESCAPE SEQUENCES

The termcap entries for xterm, vt100, vt100em and versaterm would all work with the emulated terminal (if you could somehow translate the output intended for a Unix terminal into calls to vtansiputs). Unrecognized escape sequences and control characters are ignored.

*** List all implemented escape sequences here. ***  

EXAMPLE

#include "stdwin.h"
#include "vt.h"

main() {
        VT *vt;
        winit();
        wsetdefwinsize(80*wcharwidth('0'), 24*wlineheight());
        vt= vtopen("VT", 24, 80, 100); /* Should check outcome */
        vtautosize(vt);
        vtsetnlcr(vt, 1); /* Map LF to CR LF */
        vtansiputs(vt, "Hello, world\n", -1);
        eventloop();
        wdone();
        exit(0);
}

eventloop(vt) VT *vt; {
        for (;;) {
                EVENT e;
                wgetevent(&e);
                switch (e.type) {
                case WE_SIZE:
                        vtautosize(vt); /* Should check outcome */
                        break;
                case WE_CHAR:
                        { char buf[2];
                          buf[0]= e.u.character;
                          vtansiputs(vt, buf, 1);
                          break; }
                case WE_MOUSE_DOWN:
                        vtsetcursor(vt,
                                    e.u.where.v / vtcheight(vt),
                                    e.u.where.h / vtcwidth(vt));
                        break;
                case WE_COMMAND:
                        switch (e.u.command) {
                        case WC_CLOSE:                              return;
                        case WC_RETURN: vtansiputs(vt, "\n", 1);    break;
                        case WC_BACKSPACE: vtansiputs(vt, "\b", 1); break;
                        case WC_TAB: vtansiputs(vt, "\t", 1);       break;
                        }
                        break;
                }
        }
}
 

DIAGNOSTICS

Vtopen returns a nil pointer if it can't allocate all the required memory or if the call to wopen it makes fails.
Vtresize and vtautosize return false (zero) if they can't allocate the extra memory required; in this case the VT struct has been damaged beyond repair.  

SEE ALSO

STDWIN documentation  

AUTHOR

Guido van Rossum  

BUGS

In some versions of STDWIN, the scroll bars won't appear and some other functionality won't be available unless the program calls wgetevent.
Unless the application calls vtautosize at all the right moments, it is quite possible that the window size doesn't match the size of the virtual terminal. When the window is too small, STDWIN's automatic scrolling will cause the text to jump around; when it is too large, portions of the scrolled-away text will remain visible but unreachable by the cursor.
The ANSI terminal implementation is incomplete. It certainly isn't a full-fledged VT100.
The behaviour of the cursor at the right margin is slightly unconventional.
Bold output only works on the Macintosh, and requires that a font called ``Bold'' (9 points) be available in the system file. This font can be found in the resources for (some versions of) VersaTerm(TM).
The package makes the assumption that all characters have the same width.
The order of parameters indicating rows and columns is internally consistent, but reversed with respect to order used for h and v coordinates in the rest of STDWIN.
The origin of cursor coordinates passed to vtsetcursor is (0, 0), even though the origin used by ANSI escape sequences is (1, 1).
The header file defines functions that aren't really part of the public interface.


 

Index

NAME
SYNOPSIS
DESCRIPTION
ANSI ESCAPE SEQUENCES
EXAMPLE
DIAGNOSTICS
SEE ALSO
AUTHOR
BUGS

This document was created by man2html, using the manual pages.
Time: 09:07:00 GMT, February 14, 2025