.TH XTTY 3X "28 January 1985" "X Version 10"
.SH NAME
Xtty \- routines to provide terminal emulator windows
.SH SYNOPSIS
.nf
.B #include <X/Xlib.h>
.B #include <X/Xtty.h>
.PP
.fi
.B TTYWindow *CreateTTYWindow(cols, lines, x, y,
.B normalFont, boldFont, bwidth, reverse)
.br
.B int cols, lines, x, y,
.B bwidth, reverse;
.nf
.B char *normalFont, *boldFont;
.PP
.B DestroyTTYWindow(t);
.B TTYWindow *t;
.PP
.B TTYPutString(t, str);
.B TTYWindow *t;
.B char *str;
.PP
.B TTYPutChar(t, ch);
.B TTYWindow *t;
.B char ch;
.PP
.fi
.B TTYPrintf(t, format
.B  [ , arg ] ... )
.nf
.B TTYWindow *t;
.B char *format;
.PP
.B char *TTYGetString(t, string, n)
.B TTYWindow *t;
.B char *string;
.B int n;
.PP
.B int TTYGetChar(t)
.B TTYWindow *t;
.PP
.B SetStdout(t)
.B TTYWindow *t;
.PP
.B ResetStdout()
.SH DESCRIPTION
.fi
These functions allow applications to create terminal emulator windows.
The windows are managed by creating a subprocess \fIxterm(1)\fP
and communicating
with it through a pty.  The \fITTYWindow\fP data structure is defined in
\fI<X/Xtty.h>\fP:
.PP
.nf
.B typedef struct _TTYWindow {
.B
	Window w;		/* The window id */
.B
	int pid;		/* The pid of the subprocess xterm */
.B
	short file;		/* The file id to read and write characters 
.B
	    	    	    	   characters to/from */
.B } TTYWindow;
.fi
.PP
.I CreateTTYWindow
creates a window that is
.I cols
characters wide and
.I lines
characters high.  It is located with its upper left hand corner located
at the point
.I x, y
in the root window.
The border is
.I bwidth
pixels wide.
Normal text is displayed in
.I normalFont
and boldface text is displayed in
.I boldFont.
If 
.I boldFont
is 
.B NULL,
the normal font is used for both.  If
.I reverse
is non-zero, the window is created in reverse-video.
.PP
The new window is created and mapped to the screen, and emulates a DEC
VT102 terminal precisely as well as
\fIxterm(1)\fP
does.
.PP
.I DestroyTTYWindow
destroys the window described by its argument.  The window is also destroyed
if the creating process terminates or is killed.
See the
.B BUGS
section, below.
.PP
.I TTYPutString
prints its string in its window.
An application may instead wish to use the
.I file
field of the
.I TTYWindow
directly.
.PP
.I TTYPutChar
is similar to
.I TextPutString
but only prints a single character.
.PP
.I TTYPrintf
is similar to the standard function
.I printf
except that it prints its result in the specified window.  The
resulting string is passed to
.I TTYPutString.
See also the 
.B BUGS
section, below.
.PP
.I TTYGetString
fills the array
.I string
with at most
.I n
characters.
.I TTYGetString
will also return before 
.I n
characters are read if a newline (\\n) is encountered.
An application may instead wish to use the
.I file
field of the
.I TTYWindow
directly.
.PP
.I TTYGetChar
returns one character from the window.
.PP
.I SetStdout
sets things up so that the standard I/O
routines which write to stdout will write to the window instead.  This is
particularly useful with the \fIcurses(3X)\fP package since it always writes to
stdout.
.PP
.I ResetStdout
resets stdout to its original value.
.SH "SEE ALSO"
printf(3S), xterm(1), Xtext(3X), curses(3X), X(8C)
.SH AUTHOR
Paul Asente, Stanford University
.SH BUGS
\fITTYPrintf\fP truncates its output if the resulting string is more than
2048 characters long.
.PP
It is impossible to make one implementation that works correctly for both
monochrome and color displays since you cannot specify colors on a
monochrome display and reverse-video doesn't make much sense on a color
display.  This version works for monochrome displays.