THE TXT FUNCTIONS

There are too many functions provided by the txt module to describe them all
in detail here. Instead, only the ones we need for our application are
described. The remaining functions are mentioned in passing only, but full
details can be found in the ANSI C user guide.

Listing 1 is a source file containing two exported functions -
showtext_init() and showtext_display(). These functions can be compiled
separately and then linked into a complete program, providing a suitable
showtext.h header is also included to provide prototype declarations for the
two functions.

showtext_init() takes no parameters and returns no results. It should be
called once before calling showtext_display(). The only action this function
takes is to call txt_init(), which initialises the remainder of the txt
functions. txt_init() must be called before any other txt functions, but
after calling flex_init().

showtext_display takes two parameters - the first a pointer to the filename
to load, and the second a pointer to the title to use in the window. If for
any reason the text cannot be loaded and displayed, the function returns
FALSE. Otherwise, the function waits until the window is closed (processing
Wimp events in the meantime) and then returns TRUE.

The first thing showtext_display() does is to use OS_File 17 to find the
length of the text file. Assuming the file is found, txt_new() is called to
create a new txt object. This call is passed the title for the window and
returns an object of type txt which is a handle used for all future
references to the newly created txt. Zero is returned if the txt could not
be created.
