SCROLLTEXT(3)

NAME
scrollText - Multi-font scrollable text windows for X

SYNOPSIS
#include <X/Xlib.h>
#include scrollText.h

int TxtGrab(textWin, program, mainFont, bg, fg, cur)
Window textWin;
char *program;
FontInfo *mainFont;
int bg, fg, cur;

int TxtRelease(w)
Window w;

int TxtAddFont(textWin, fontNumber, newFont, newColor)
Window textWin;
int fontNumber;
FontInfo *newFont;
int newColor;

int TxtWinP(w)
Window w;

int TxtClear(w)
Window w;

int TxtWriteStr(w, str)
Window w;
char *str;

int TxtJamStr(w, str)
Window w;
char *str;

int TxtRepaint(w)
Window w;

int TxtFilter(evt)
XEvent *evt;

DESCRIPTION
The scrollText package implements a multi-font, multi-color, scrollable text window abstraction which runs over the X Window System. The package supports any number of windows each with its own scroll bar and character buffer. Each window can have up to eight fonts loaded. A color may be specified for each loaded font. The fonts can be mixed freely using a change font character control sequence. The scrolling operations supported are scroll relative to scroll bar, line to top, and top line to here. The size of the character buffer for each window is limited only by the process space of the controlling program.

TxtGrab takes control of a previously created window, textWin, and makes it into a scrollable output window. The string program is used to look up X defaults for the package (see section X Defaults). The parameter mainFont is the initial font used for drawing text in the window. This font is loaded into slot zero. TxtGrab assumes this record is fully filled (including the width table). The X library routine XOpenFont can be used to obtain fully filled font record structures. Additional fonts can be loaded using TxtAddFont (described below). The pixel value fg will be used to draw the scroll bar and is also used as the initial color for mainFont. The pixel value bg will be used as the background for drawing all text. bg is also used as the background for the scroll bar subwindow. The color of the text cursor is set to cur. In order for the text window to work properly, the programmer must select ExposeRegion and ExposeCopy events on the window in addition to any other events the programmer might wish to register. The routine returns a non-zero value if the window was sucessfully grabbed.

TxtRelease releases control of a previously grabbed window. All resources consumed by the text window package are reclaimed. The window itself is not destroyed.

TxtAddFont loads a new font so that it can be used in a previously grabbed text window. The parameter fontNumber is used to specify the slot for the new font. There are eight font slots numbered 0 through 7. If there is already a font in the specified slot, it will be replaced with the new one and an automatic redraw of the screen contents will take place. See TxtWriteStr and TxtJamStr for details on using multiple fonts. The pixel value newColor specifies the foreground color for the font. If TXT_NO_COLOR is specified, the color will default to the foreground color supplied when the window was grabbed. The programmer can change just the color of a font by specifing a null font for a given slot. The routine returns a non-zero value if the font was sucessfully loaded.

TxtWinP returns a non-zero value if the specified window has been previously grabbed using TxtGrab. If it is not a text window, the routine returns zero.

TxtClear clears the specified window of its contents and resets the current writing position to the upper left hand corner of the screen. The routine also clears the contents of the text window buffer and resets the scroll bar. The routine returns zero if the window is not a text window. This procedure should be used instead of the X library call XClear.

TxtWriteStr writes a null-terminated string into the specified text window. The text is always appended to the end of the text buffer. If the scroll bar is positioned such that the end of the text is not visible, an automatic scroll to the bottom will be done before the text is appended. Non-printable ASCII characters are ignored. The newline character (\n) causes the current text position to advance one line and start at the left. Tabs are not supported. Lines too wide to fit on the screen will be wrapped to the next line and a line wrap indicator will be drawn in the right margin. Backspace deletes the previous character. It will do the right thing if asked to backspace past a normal or wrapped line marker. A new text font can be specified using the sequence control-F followed by a digit. The digit must be 0, 1, 2, or 3. The directive will be ignored if there is no font loaded in the specified slot. If there is no more space at the bottom of the screen, the window will scroll to make room. The routine will return zero if it could not append the text.

TxtJamStr is identical to TxtWriteStr except the current screen position is not updated. This routine should be used if the programmer wants to append text to the buffer without causing the window to scroll. After the text has been added, the programmer should call TxtRepaint to update the screen contents.

TxtRepaint redraws the specified scrollable text window. The routine repaints the entire window including the scroll bar. NOTE: for handling exposure events, TxtFilter should be used.

TxtFilter handles events associated with scrollable text windows. It will handle ExposeRegion and ExposeCopy events on the main window, and ExposeWindow and ButtonReleased events in the scroll bar. It does not handle any other events. If it does not want to handle the event, the routine will return zero. A call to this routine should be included in the main event loop of the programmers controlling program.

USER INTERFACE

The scrollText package supports user controlled browsing through a buffer built using TxtWriteStr or TxtJamStr. Along the right side of the window is a scroll bar window. The scroll bar window displays a filled square representing the relative position through the buffer and the relative amount of the buffer currently on the screen. Scrolling is controlled by clicking mouse buttons in the scroll bar.

This package supports three scrolling operations: scroll to spot, line to top, and top to here. The middle button is used to select scroll to spot. This operation causes the screen to scroll such that the center of the scroll bar indicator moves to the current position of the mouse. This is used to scroll to a relative spot in the buffer. Line to top and top to here operations are for scrolling down or up some proportion of the screen. The left button selects line to top. This operation causes the screen to scroll such that the line adjacent to the mouse position becomes the top line of the screen. Thus, clicking near the top of the scroll bar scrolls only a couple of lines while a click near the bottom will scroll almost an entire screen. The right button is used for the top to here command. This function causes the top line of the screen to scroll down to the current position of the mouse. This allows the user to scroll up and down by the same amounts if the mouse position is kept constant.

X DEFAULTS
The current version of the library reads one default:

JumpScroll
    If on, the line to top and top to here operations will not scroll to the target position smoothly. Instead, the window will be repainted once at the correct spot.

FILES
libScroll.a - Scrollable text library

SEE ALSO
Xlib - C Language X Interface, X(8C)

AUTHOR
David Harrison, University of California, Berkeley

BUGS
Sometimes when the window is resized, the scroll bar is repainted without a border. The origin of this bug is unknown but a work-around is to iconify and deiconify the window forcing a complete redraw.

Loading large files with many font changes is slow. Unfortunately, there is simply a lot of work which must be done. Resizing windows with extrodinarily large buffers may also take some time (the line breaks must be recomputed).