4.3BSD-UWisc/man/man3/xtext.3x

.TH XTEXT 3X "April 10 1986" "X Version 10"
.SH NAME
Xtext \- routines to provide simple text output windows
.SH SYNOPSIS
.nf
.B #include <X/Xtext.h>
.PP
.fi
.B TextWindow *TextCreate(width, height, x, y, parent, 
.br
.B		fontname, bwidth, fgpixel, bgpixel,
.br
.B		bordercolor, fastscroll);
.br
.B int height, width, x, y,
.B bwidth, fgpixel, bgpixel, fastscroll;
.nf
.B Window parent;
.B char *fontname;
.B Pixmap bordercolor;
.PP
.B TextDestroy(t);
.B TextWindow *t;
.PP
.B TextClear(t);
.B TextWindow *t;
.PP
.B TextRedisplay(t);
.B TextWindow *t;
.PP
.B int TextEvent(t, e);
.B TextWindow *t;
.B XEvent *e;
.PP
.B TextPutString(t, str);
.B TextWindow *t;
.B char *str;
.PP
.B TextPutChar(t, ch);
.B TextWindow *t;
.B char ch;
.PP
.fi
.B TextPrintf(t, format
.B  [ , arg ] ... )
.nf
.B TextWindow *t;
.B char *format;
.PP
.B TextFlush(t);
.B TextWindow *t;
.SH DESCRIPTION
These functions provide a simple interface to text output windows.
.PP
.I TextCreate
creates a window that is
.I width
characters wide and
.I height
characters high.  It is located with its upper left hand corner located
at the point
.I x, y
in the window
.I parent.
The foreground (i.e. the characters) is in the color
.I fgpixel
and the background is the color
.I bgpixel.
The border is
.I bwidth
pixels wide and filled with the Pixmap
.I bordercolor.
If
.I fastscroll
is nonzero, text containing multiple newlines is displayed with a single
jump scroll rather than with a single scroll for each newline.
.PP
The structure
.I TextWindow
is defined in
\fI/usr/include/X/Xtext.h\fP.
The only field that should be of interest to most applications is
.I w,
the X Window id of the created window.  This is quite useful if the
application wishes to map the created window.
.PP
.I TextDestroy
destroys the window described by its argument.  The window is also
destroyed automatically if the process creating it is terminated.
.PP
.I TextClear
clears the window described by its argument.
.PP
.I TextRedisplay
redisplays the window described by its argument.  If the argument
is NULL, all active text windows are redisplayed.
.PP
.I TextEvent
handles the event passed to it.  It returns 0 if it was an event
the library knows how to deal with, and 1 if it was an event of an
unknown type; the latter should only happen if the application has
changed the event mask for the window.  Any event that the application
receives that has as its
.I window
the window id of the text window should be passed to
.I TextEvent
for handling.  Scrolling text generates an event per line of events, so the
application should check for them frequently.  An alternative routine,
.I TextFlush,
can be used to handle all outstanding events for all active text windows.
.PP
.I TextPutString
prints its string in its window.  The character '\\n' (newline) is
treated specially, and any other character is taken from the font.
If the string contains multiple newlines, a single scroll is done for
each line unless the
.I fastscroll
argument was non-zero in the call to
.I TextCreate.
.PP
.I TextPutChar
is similar to
.I TextPutString
but only prints a single character.  Again, newline is treated
specially.
.PP
.I TextPrintf
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 TextPutString.
See also the 
.B BUGS
section at the end of this page.
.PP
.I TextFlush
is analogous to the stdio function
.I fflush
in that it causes all outstanding output requests to be flushed
to the specified window.  If the argument is NULL, all windows are
flushed.  For novice X developers, this routine
eliminates the need for event handling from X applications.
.SH "SEE ALSO"
printf(3S), xterm(1), X(8C)
.SH AUTHORS
Paul Asente, Stanford University; Mark Colan, MIT Project Athena/IBM
.SH BUGS
\fITextPrintf\fP will truncate the output if the resulting string is more than
2048 characters long.
.PP
Since X operates asynchronously, it is possible to get way ahead of the
server.  This means that it may be quite a while between when a scroll
happens on the screen and when \fIXtext\fP gets around to filling in areas
that couldn't be scrolled normally.  This should only happen if the
application issues a great many output requests very quickly, or if it
doesn't get around to receiving the events \fIXtext\fP needs to fill these
areas in.  Also, some strange TCP bugs are invoked if an application
which has gotten far ahead of the X server is stopped (as with a
control-Z).