XTEXT(3X)

NAME
Xtext - routines to provide simple text output windows

SYNOPSIS
#include <X/Xtext.h>

TextWindow *TextCreate(width, height, x, y, parent,
fontname, bwidth, fgpixel, bgpixel,
bordercolor, fastscroll);
int height, width, x, y, bwidth, fgpixel, bgpixel, fastscroll;
Window parent;
char *fontname;
Pixmap bordercolor;

TextDestroy(t);
TextWindow *t;

TextClear(t);
TextWindow *t;

TextRedisplay(t);
TextWindow *t;

int TextEvent(t, e);
TextWindow *t;
XEvent *e;

TextPutString(t, str);
TextWindow *t;
char *str;

TextPutChar(t, ch);
TextWindow *t;
char ch;

TextPrintf(t, format [ , arg ] ... )
TextWindow *t;
char *format;

TextFlush(t);
TextWindow *t;

DESCRIPTION
These functions provide a simple interface to text output windows.

TextCreate creates a window that is width characters wide and height characters high. It is located with its upper left hand corner located at the point x, y in the window parent. The foreground (i.e. the characters) is in the color fgpixel and the background is the color bgpixel. The border is bwidth pixels wide and filled with the Pixmap bordercolor. If fastscroll is nonzero, text containing multiple newlines is displayed with a single jump scroll rather than with a single scroll for each newline.

The structure TextWindow is defined in /usr/include/X/Xtext.h. The only field that should be of interest to most applications is w, the X Window id of the created window. This is quite useful if the application wishes to map the created window.

TextDestroy destroys the window described by its argument. The window is also destroyed automatically if the process creating it is terminated.

TextClear clears the window described by its argument.

TextRedisplay redisplays the window described by its argument. If the argument is NULL, all active text windows are redisplayed.

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 window the window id of the text window should be passed to TextEvent for handling. Scrolling text generates an event per line of events, so the application should check for them frequently. An alternative routine, TextFlush, can be used to handle all outstanding events for all active text windows.

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 fastscroll argument was non-zero in the call to TextCreate.

TextPutChar is similar to TextPutString but only prints a single character. Again, newline is treated specially.

TextPrintf is similar to the standard function printf except that it prints its result in the specified window. The resulting string is passed to TextPutString. See also the BUGS section at the end of this page.

TextFlush is analogous to the stdio function 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.

SEE ALSO
printf(3S), xterm(1), X(8C)

AUTHORS
Paul Asente, Stanford University; Mark Colan, MIT Project Athena/IBM

BUGS
TextPrintf will truncate the output if the resulting string is more than 2048 characters long.

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 Xtext 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 Xtext 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).