% @(#)tx.twh	17.1.1.1 (ESO-IPG) 01/25/02 17:48:08 
\input{tx3.tex}
\def\TeX{{\bf TeX}}
\def\LaTeX{{\bf LaTeX}}
\def\dots{...}
\def\eg{e.g.}
\def\TW{{\sl TermWindows} }
\def\tt{}
\def\ref#1{}

\Help{0}{TermDisplay} {{\bf TermDisplay}}


There now exists good, reliable and portable text formatting packages, 
like \LaTeX
used to generate this document ---
but few similar possibilities exist for displaying a text 
on an ASCII terminal. 
The TermDisplay (Terminal--independent Displaying facilities)
package allows such a processing, 
in a way similar to \TeX: special formatting ``macros'', like tabular
environment or font selection, are embedded in the ASCII text
to specify how the text should appear.
Such terminal displaying facilities are obviously useful in
{\em Help} displays --- but definitions of \eg forms may
as well make use of these functions.
\EOF

\Help{1}{Process}{How the text is processed}

The text to display includes, besides the text itself, formatting ``macros''
starting with a backslash (`\b') with possible parameters
within braces (\{\dots\}).
Let us have a look on the {\sl Input}:
beside the text, notice some macros like {\tt\b centerline\{\dots\}}
to issue a text centered on a line, or {\tt\b bf\dots}\ 
to ask for {\bf boldface}'d text, and the possibility of commenting
using the `\%' character.

The simplest way to understand the result given after processing 
is to have a look on the \LaTeX'ed {\sl result}.

\EOF

\Help{2}{Input}{How the input look like}
\begin{verbatim}
%%%%%%%%%%%%%%%%% Table Environment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\BeginTable#1#2{\begin{table}{#1}{#2}}%
\def\EndTable{\end{table}}%
\vfill
\centerline{{\bf Table Environment}} % Title  

\BeginTable{|l|r|c|p{12em}|}{5,6,9,}
\Rule
left & right & centre & \multicolumn{1}{c}{{\bf Explanation}} \\
\Rule
-1-& -2-& -3- & The last column is justified, and may 
                   lay over several lines
                   until the end is reached. It's nice to finish
                   with graphic lines.\\
\Rule
\EndTable
\vfill
\end{verbatim}
\EOF

\Help{2}{Result}{... and the result}

\centerline{{\bf Table Environment}} % Title  

\vfill
\BeginTable{|l|r|c|p{12em}|}{5,6,9,}
\Rule
left & right & centre & \multicolumn{1}{c}{{\bf Explanation}} \\
\Rule
-1-& -2-& -3- & The last column is justified, and may 
                   lay over several lines
                   until the end is reached. It's nice to finish
                   with graphic lines.\\
\Rule
\EndTable
\vfill
\EOF

\Help{1}{Functions}{TermDisplay Functions}

Before explaining in detail how the text to be processed should
be written,
let's describe the available functions to display such a text on a window,
summarized in {\em List}.

The text to display may be specified as a parameter (in {\em ShowText},
{\em ShowString}, {\em DisplayString}, {\em DisplayText}, 
or {\em DisplayArray}), or taken from a file ({\em DisplayFile} or 
{\em DisplayFromFile}).

{\em Show} and {\em Display} differ in the sense that the former
({\em ShowString, ShowText}) displays what is specified  
starting at the current cursor location,
while the latter clears the window before displaying the text.

\EOF

\Help{2}{List}{Available TermDisplay Functions}
\begin{table}{|rl|}{12} \Rule
{\em status} =	& ShowText({\em w}, {\em str}, {\em len}) \\
{\em status} =	& ShowString({\em w}, {\em str}) \\
{\em status} =	& DisplayText({\em w}, {\em str}, {\em len}) \\
{\em status} =	& DisplayString({\em w}, {\em str}) \\
{\em status} =	& DisplayArray({\em w}, {\em astr}, {\em n}) \\
{\em status} =	& DisplayContinuation({\em w}) \\
{\em status} =	& DisplayFile({\em w}, {\em filename})\\
{\em status} =	& DisplayFromFile({\em w}, {\em fid}, {\em bytes})	\\
	\Rule
 {\em fields} =	& GetMarkedFields({\em w})	\\
 	& SetMathAction({\em function})	\\
\Rule \Rule
WINDOW & {\em * w} \\
TWFIELD & {\em * fields} \\
char 	& {\em * str, * filename} \\
char 	& {\em ** astr, ** ends} \\
int		& {\em len, bytes, n, fid}	\\
int		& {\em (*function)()}	\\
\Rule 
\end{table}

\EOF

\Help{2}{DisplayArray}{A TermDisplay Functions}

{\em DisplayArray} allows to display as a text a set of pieces of
text located in non-contiguous memory locations, avoiding therefore
a transformation into a single string. The parameters of {\em DisplayArray}
indicate the number n of strings, and the string locations are
in the {\em astr} array made of 2\times n pointers.
Each group of two consecutive pointers in the {\em astr} array must 
point to the first byte 
of a piece of text, followed by the pointer to the 
byte following the last byte in the piece of text.
To be more explicit, if the n strings 
are standard strings {\em str} terminated with the {\em nul} character,
the 2\times n {\em astr} array can be built with the following code:
\begin{verbatim}
        for (i=0; i<n; i++)
             astr[i*2]   = str[i],
             astr[i*2+1] = str[i] + strlen(str[i]);
\end{verbatim}


\EOF

\Help{2}{DisplayFile}{TermDisplay From Files}

{\em DisplayFile} displays the contents of a file,
while {\em DisplayFromFile} displays the contents of a previously opened
file, starting at the current position in this file.
Somewhere in the file used in {\em DisplayFromFile},
the special {\b EOF} macro that indicates the end of a text 
should normally appear within the {\em nbytes} bytes 
starting at the current file position.

\EOF

\Help{2}{Example}{TermDisplay Program Example}

The following example is a complete program which displays
a file which name is typed in by the user. It uses two windows, 
{\em wd} for TermDisplay lying over the n-3 upper lines
of the screen, and a bordered {\em wr} window on the bottom 3 lines
of the screen to dialogue with the user.
\begin{verbatim}
#include <tw.h>
main()
{
  WINDOW *wd, *wr;
  short int screen[2];
  int status;
  char filename[80];
  
  ScreenSize(screen);      /* Get the Screen Dimensions */
  wd = OpenWindow("Display",0,0,screen[0]-3,0, _NORMAL_, _DISPLAY_ , 0);
  wr = OpenWindow("Dialog",-3,0,3,0, _NORMAL_, _GRAPHICS_ , 10);
  ActiveWindow(wr);
  ActiveStacking(wr);

  while(1)
  {     ClearWindow(wr);
        Put(wr, "Name of file to display: ");
        if (Gets(wr, filename, sizeof(filename)) < 0)
                break; /* a negative returned value means "end-of-file" */
        ClearWindow(wr);
        status = DisplayFile(wd, filename);
        TouchWindow(wd);
        while(status == 0)      /* There is a continuation */
        {       Put(wr, "Hit S to stop: ");
                GetKey(wr, filename);
                ClearWindow(wr);
                if (filename[0] == 'S') break;
                status = DisplayContinuation(wd);
                TouchWindow(wd);
        }
  }
  EndWindows();
}
\end{verbatim}

\Help{1}{Macros}{TermDisplay Macros}

The basic list of existing macros, 
similar to the {\tt\b centerline} or {\tt\b bf} macros
is summarized as {\sl List}.
The macros in {\sl List} are called ``basic'' because 
it is possible to define
as many other macros as you want, using these ``basic'' definitions,
like in \TeX.

Let's notice first that the symbols \{ \} \% \$ \& \_ \^{ } \# 
have the same special meaning than in \TeX: \{ and \} fors groups
or parameters, the \% for comments until the end of the line, 
the \$  \^{ } and \_ for math, \# for macro definitions,
and \& to separate columns in a table. These symbols can
be displayed if they are immediately preceded by a \b,
as summarized in the first part of Table~\ref{TX:macros}.

The second part of {\sl List} summarizes how to insert blanks
or to skip lines. The {\tt\b hfill} and {\tt\b vfill} are especially
useful to center pieces of text on windows.

The third part of {\sl List} summarizes 
how to write single lines with one of the three possible justifications:
text centered on the line, pushed to the left or to right margin.

The fourth part of {\sl List} explains how to choose
special video attributes. Note that the video attributes are {\em superposed},
\eg {\tt\b VB\b Vb\b Vr} for \fbox{Bold+Blink+Reverse}.


\EOF

\Help{2}{List}{List of {\sl basic} TermDisplay Macros}

\begin{table}{|lp{32em}|}{20,} \Rule
 	Name	&	Explanation \\  		\Rule
{\tt\b b} 	&	Issue a single backslash (\b)	\\
{\tt\bx} 			&	Issue symbol x, with possibilities
					\{ \} \% \$ \& \_ \^{ } \# space \\
\Rule \Rule
\multicolumn{2}{c}{{\em Blanks and Line Position}} \\	\Rule \Rule 
{\tt\b\b} 			&	Break the current line		\\
{\tt\b quad}	{\tt\b qquad}	&	Issue 2 or 4 blanks	\\
{\tt \~{ }}			&	Issue a single non-breakable blank \\
{\tt\b Hspace\{n\}} 		&	Issue n non-breakable blanks	\\
{\tt\b tab}	 		&	Align to next ``tab''		\\
{\tt\b SkipLine} 		&	Issue a single blank line	\\
{\tt\b indent}			& 	Indentation	\\
{\tt\b hfill}			& 	Horizontal Stretchable space	\\
{\tt\b vfill}			& 	Vertical Stretchable space \\	
%
\Rule \Rule
\multicolumn{2}{c}{{\em Line Justifications}} \\	\Rule \Rule 
{\tt\b centerline\{{\em text}\}}	&	Issue a line with {\em text} 
						centered.
					(see also {\tt center} environment)\\
{\tt\b leftline\{{\em text}\}}	&	Issue a line with {\em text} 
						adjusted to the left 
					(see also {\tt left} environment)\\
{\tt\b rightline\{{\em text}\}}	&	Issue a line with {\em text} 
						adjusted to the right 
					(see also {\tt right} environment)\\
\Rule \Rule
\multicolumn{2}{c}{{\em Video Attributes}} \\	\Rule \Rule 
{\tt\b VB} or {\tt\b bf}	&	use {\bf Boldface} attribute	\\
{\tt\b Vu} or {\tt\b sl} 	&	use {\sl Underscore} attribute	\\
{\tt\b Vr} or {\tt\b em} or{ \tt\b it} 	& use {\em Reverse} attribute	\\
{\tt\b Vb} 			&	use {\tt Blink} attribute	\\
{\tt\b fbox\{{\em text}\}} 	&	use \fbox{Bold+Reverse+Blink}
						attribute	\\	
%
\Rule \Rule
\multicolumn{2}{c}{{\em Environments}} \\	\Rule \Rule 
{\tt\{verbatim\}} 		&	Display text as it is	\\
{\tt\{center\}} 		&	Centering text 		\\
{\tt\{left\}} 		&	Left-aligned (no justification),
					also called raggedright 	\\
{\tt\{right\}} 		&	Right-adjusted text, 
					also called raggedleft		\\
{\tt\{indent\}} 		&	Push left margin 	\\
{\tt\{quote\}}		&	Push left and right margins	\\
{\tt\{itemize\}}		&	Itemized  list; {\tt\b item}
					starts each item		\\
{\tt\{enumerate\}}		&	Start an enumerated list;
					{\tt\b item} starts each item	\\
{\tt \{alphaenumerate\}}	&	Start an enumerated list using 
						lowercase letters\\
{\tt \{Alphaenumerate\}}	&	Start an enumerated list using 
						uppercase letters\\
{\tt \{table\}\{{\em pos}\}\{{\em w}\}}	& 
		Table environment. 
		See explanations in the text.	\\
\Rule \Rule
\multicolumn{2}{c}{{\em Environment-specific macros}} \\	\Rule \Rule 
%
{\tt\b item} 			&	Specifies a new element in the 
				 itemize / enumerate list\\
{\tt\b crule\{\}} 		&	Issue a horizontal line over 
					one column in a table	\\
{\tt\b Rule} 			&	Issue a horizontal line over the
						whole window width	\\
{\tt\b multicolumn\{n\}\{{\em j}\}\{{\em text}\}} 
			&	define a column spreading over n
				columns with {\em j} justification.\\
\Rule \Rule
\multicolumn{2}{c}{{\em Miscellaneous}} \\	\Rule \Rule 
%
{\tt\b bell} 			&	Ring the terminal bell	\\
{\tt\b input\{{\em filename}\}}  & Get text to process from {\em filename} \\
{\tt\b def\b{\em name\#}\dots\{{\em equivalence}\}}
				& Macro definition	\\
{\tt\b EOF}			& End of text indicator	(stops when found) \\
{\tt\b iftrue} {\tt\b iffalse}
{\tt\b else} {\tt\b fi}	&	Conditional tests \\
{\tt\b CheckLines\{n\}}	&	Terminate if less than 	n lines 
						remain on the current window \\
{\tt\b Field\{{\em name}\}\{{\em text}\}}&	Define a named field
				which can be retrieved in the calling program
				via {\em GetMarkedFields}\\ 
\Rule\end{table}
\EOF

\Help{2}{Environments}{TermDisplay Environments}

The fifth part of {\em List} summarizes the available
{\em environments}. An environment starts with 
{\tt\b begin\{{\em environment\_name}\}}
and terminates with 
{\tt\b end\{{\em environment\_name}\}}.
A new environment also starts a new line.
For instance, if several lines are to be right-adjusted, it is 
advisable to use
\begin{verbatim}
\begin{right}
  Here is an example \\
  Of text adjusted \\
  To the {\bf right} margin
\end{right}
\end{verbatim}

The {\em verbatim} environment allows to display a text exactly as it
is, without any transformation. Any macro substitution is therefore
skipped between the {\tt\b begin\{verbatim\}} and the {\tt\b end\{verbatim\}} !

The {\em left}, {\em right} and {\em center} environments modify the
line justifications. Within these environments, the \b\b\ indicate
where the lines must be broken.

The {\em indent} environment reduces the size of the text
by moving the left margin, and the
{\em quote} environment reduces the size of the text by moving simultaneously
the left and right margins.

The {\em itemize}, {\em enumerate}, {\em alphaenumerate} and 
{\em Alphaenumerate} environments are used to display {\em lists}, 
each item of the list being indicated by the {\tt\b item} macro.
{\em itemize} quotes each item by the {\tt=>} symbol,
{\em enumerate} assigns a number starting from 1 to each item,
{\em alphaenumerate} assigns a lowercase letter starting from {\tt a},
and 
{\em Alphaenumerate} assigns an uppercase letter starting from {\tt A}.

\EOF

\Help{2}{Table}{TermDisplay Table Environment}

The 2 parameters of the {\tt\b begin\{table\}} macro specify:
\begin{enumerate}
\item The {\em pos} parameter, similar to the \LaTeX specification:
	possibilities of \quad l \quad r \quad c \quad p \quad for left, 
	right, centered or justified text,
	\quad | \quad for a vertical line separating columns,
	and blanks before / after the | to add a blank before and / or
	after the vertical line.
\item The {\em w} parameter specifies the {\em width} of
	each column, as numbers separated
	by commas or blanks; if the last column width is
	not specified, it is assumed to use the {\em remaining space}.
	If all column widths are specified, the table is {\em centered}
	between the left and right margins of the window.
\end{enumerate}

\EOF

\Help{3}{Example}{Table Environment Examples}

\begin{itemize}
\item 	{\tt\b begin\{table\}\{|r |p|\}\{5,50\}} will create a table 
	with 2 columns:
	a right-adjusted column (with a blank at the left of the
	second |) of 5 characters, and a justified column
	with 50 characters; the complete width of the table is 59 characters
	(don't forget the space required by the vertical lines and blanks!).
	Since the width of all columns are specified, the table
	will be {\em centered} between the left and right margins.
\item 	{\tt\b begin\{table\}\{rcp\}\{5,10\}} will create a table with 3 columns:
	a right-adjusted column of 5 characters, a centered column of 10 
	characters, and a justified column of 65 characters if the
	width of the window is 80 characters.
\end{itemize}

\EOF

\Help{3}{multicolumn}{Table MultiColumns}


Within a table, the columns are separated by a `{\bf\&}'.

The macro {\tt\b Rule} draws an horizontal line all the whole
table, while {\tt\b crule\{\}} draws an horizontal line over
the current column.

The {\tt\b multicolumn} macro defines a single column lying
over several defined ones. It requires three parameters:
\begin{enumerate}
\item the number of columns; this number may be 1 if only the
	justification is to be redefined.
\item	the justification, a single letter which can be {\tt l r c}
	for left, right or center justification. It may also include
	| for \TeX\ compatibility, but the vertical bars are
	ignored here.
\item	the text to display in this multi-column.
\end{enumerate}

\EOF

\Help{3}{Input\_Keypad}{How to generate a keypad}
\begin{verbatim}
\vfill
\begin{table}{|c|c|c|c|}{5,5,5,5}
\Rule
PF1 	& PF2 	& PF3 	& PF4	\\
\Rule
7	& 8	& 9	& -	\\
\Rule
4	& 5	& 6	& ,	\\
\Rule
1	& 2	& 3	&	\\
\crule{}	& \crule{}& \crule{} & {\bf E} \\
\CentreColumns{2}{0} & . & \\
\Rule
\end{table}
\vfill
\end{verbatim}
\EOF

\Help{3}{Keypad}{... and the result}
\vfill
\begin{table}{|c|c|c|c|}{5,5,5,5}
\Rule
PF1 	& PF2 	& PF3 	& PF4	\\
\Rule
7	& 8	& 9	& -	\\
\Rule
4	& 5	& 6	& ,	\\
\Rule
1	& 2	& 3	&	\\
\crule{}	& \crule{}& \crule{} & {\bf E} \\
\CentreColumns{2}{0} & . & \\
\Rule
\end{table}
\vfill
\EOF

\Help{2}{if}{Conditional macros}

{\tt\b CheckLines} is designed to stop the edition when the number of lines
remaining on the window is smaller than the value given as the
parameter, so that the continuation will be displayed
via a later call to {\em DisplayContinuation}.

{\tt\b iftrue} and {\tt\b iffalse} start a conditional test; the test
ends with {\tt\b fi}. The {\tt\b else} clause is executed if the
conditional starts with {\tt\b iffalse}, 
and is not executed if the conditional starts with {\tt\b iftrue}.

At first sight, such primitive if / else
statements seems rather useless. 
But the macro substitutions allow to define any new ``variable''
in terms of {\tt\b iftrue} or {\tt\b iffalse}. For instance, 
if some day names should be displayed in French, we could use:
\begin{verbatim}
\def\ifFrench{\iftrue} % ... May be changed in other applications ...
.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
\ifFrench \def \Sunday{{\em Dimanche}} \else \def \Sunday {Sunday} \fi
.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .
The last \Sunday was sunny.
\end{verbatim}
\EOF


\Help{2}{input}{Input from a File}

Two macros are available to insert a complete file at some point;
for both macros, the file name must be specified as a parameter,
\ie between \{ \} symbols.
\begin{itemize}
\item {\tt\b input} continues as if the specified file were
inserted at this point.
\item	{\tt\b inputverbatim} inserts in the text a {\tt\b input\{verbatim\}},
then includes the specified file, then inserts a {\tt\b end\{verbatim\}}.
This avoids to insert explicitely the {\em verbatim} option at the beginning
and the end of the file.
\end{itemize}
\EOF


\Help{1}{def}{Definition of new macros}

Definition of new macros
has the general form, similar to \TeX:

\begin{center}
{\tt\b def}{\tt\b{\em name}{\em[\#n]}\{{\em definition}\}}
\end{center}

where the optional {\em[\#n]} specifies the number of parameters.

The macro {\em name} can be made only of {\em alphabetical} letters,
excluding therefore digits, underscores, \$, etc...
It is case sensitive, \eg {\tt\b X} differs from macro {\tt\b x}.

Within the macro {\em definition}, the symbols {\em\#i} can be used
to specify the parameters. For instance \\
{\tt\b def\b ul\#1\{\{\b Vu\#1\}\}}
defines the new macro {\tt\b ul}, which underlines the text specified
in its argument: {\tt\b ul\{Hello\}} will appear on the screen as
{\tt\ul{Hello}}.

\EOF

\Help{1}{Field}{Definition of Fields}

The {\tt\b Field} macro allows to define
{\em fields} on a window, which can be retrieved with the
{\em GetMarkedFields} function.
This allows to define {\em forms} in a terminal-independant way;
moreover, all justifications, etc... are done, ensuring
a very well presented form display without having to think
about the size of the window used, how to present tables, etc...

\EOF

\Help{2}{Example}{Field Example}

Let's assume that a file, {\tt example.tx}, contains the
following text:
\footnotesize
\begin{verbatim}

\vfill
\begin{table}{| c | c |}{5,20}
\Rule
 Item & Explanation \\
\Rule
 \Field{item}{{\sl ~~~~~}} &
	 \Field{explanation}{{\em\Hspace{20}}} \\
\Rule
 \multicolumn{2}{p}{%---------- Comment will use 3 lines
 \Field{comment}{{\em\Hspace{80}}}
 } \\
\Rule
\end{table}
\vfill
\end{verbatim}
\normalsize

The contents of this file, applied to the {\em DisplayFile} function, 
will generate the display of {\em Display}.
There a three {\em fields} defined on this window:
{\em item}, {\em explanation}, and {\em comment}. Notice
that the {\em comment} field occupies several lines.

The program to get data on
the three {\em fields} defined could be as follows:

\begin{verbatim}
#include <tw.h>
#include <memory.h>     /* To allocate memory via MEM_GET */

main()
{
        WINDOW  *wd, *wf[3];
        char    *field[3];
        TWFIELD *a; 
        int     i, nfields;

  wd = OpenWindow("Display",0,0,0,0, _NORMAL_, _DISPLAY_ , 0);
  ActiveWindow(wd);
  DisplayFile(wd,"example.tx");

        /* Open Subwindows corresponding to the Fields,
         * and get memory to store the user's input     */
        
  if(!(a = GetMarkedFields(wd)))        return(0);

  for (i=0; a->name; i++, a++)
  {     wf[i] = OpenSubWindow(wd, a->name, a->home[0], a->home[1],
                a->dim[0], a->dim[1], _ATTRIBUTE_, 0, 2);
        ActiveStacking(wf[i]);
        field[i] = MEM_GET(char, 1+a->dim[0]*a->dim[1]);
  }
  nfields = i;          /* Number of fields */
  if (nfields > 3)      nfields = 3;

        /* Get now data in the three subwindows. */
  
  for (i=0; i<nfields; i++)
        Gets(wf[i], field[i], 81);

        /* What to do with the user's input ???
         * That's not the problem in this example... */
  
  EndWindows();
}
\end{verbatim}

This program first opens a full-screen window to display the contents
of the file {\tt example.tx}. The {\em GetMarkedFields} function
allows to retrieve the fields defined in this file.

\EOF

\Help{2}{GetMarkedFields}{Retrieving Marked Fields}

The {\em GetMarkedFields} function returns a pointer to a structure
called {\em TWFIELD}. This structure details
the location of a field defined via {\tt Field};
the contents of this structure is:

\begin{verbatim}
typedef struct {                /* What's is a field on a window */
        char *name;             /* Field Name                   */
        short int home[2];      /* Starting point of field      */
        short int dim[2];       /* Dimension of Field           */
        } TWFIELD;
\end{verbatim}

The index 0 refer to the line number, and the index 1 to the
column number. If the field requires only a single line,
{\em dim[0]} contains the value 1.
Notice that, if a field requires more than a single line,
it is extended to fill full lines or columns. 

When several such fields are defined, 
{\em GetMarkedFields} returns a pointer to the
{\em first element} of an array of {\em TWFIELD} structures.
The last valid element of this array is followed by zeroes, \ie
it is only necessary to check when {\em name} becomes null.

In the example,
subwindows are opened on each of the defined fields
with the {\em\_ATTRIBUTE\_} option, 
taking the attribute of the text already existing on the window.
The stacking facility for input commands
is enabled on each subwindow.

The example also uses the {\em MEM\_GET} function to allocate memory;
using this function with a first argument being the type of atomic
data being allocated (here {\em char}) is better suited than the
{\em malloc} standard function. The {\em MEM\_GET} moreover
issues an explicit error message if no memory is available.

A last --- but not least --- remark is that field definitions
and are kept until a new call to a {\em Display}
function applied {\em on the same window}; it is therefore possible to
define simultaneously several forms on several windows.
\EOF

\Help{1}{SetMathAction}{What to do with \_ \$ \^}

When the special {\em math} symbols \$ \^{ } and \_ are found,
\TW normally ignore them. It is possible to trap these special characters,
and execute a user--supplied function.

As an example, let's assume that some long displays, starting with a \$ sign,
should be paged automatically if the end--user doesn't enter anything
after 30 seconds, and until a \^{ } is found to indicate an infinite
wait. We'll use the {\em WhileInput} facility described in
section~\ref{tw:WhileInput}. Using the same {\em run\_automatic}
function presented in section~\ref{tw:WhileInput},
we may define a new {\em display\_automatic} function:
\begin{verbatim}
display_automatic(str,len)
        char *str;      /* The input string, starting with math symbol */
        int  len;       /* Length of str */
{
        int run_automatic();
        
   switch(*str)
   { case '$':  WhileInput(run_automatic);
                break;
     case '^':  WhileInput(((*)())0);
                break;
   }
   return(1);
}
\end{verbatim}
Two arguments are passed to the user--suplied function: the string
starting with one of the three math symbols \$ \^{} \_ which was
found during the {\em TermDisplay} processing,
and the length of this string. 
The user--supplied function must return a non-zero number to indicate that
the action is {\em complete}, or a zero number to indicate that the
{\em TermDisplay} processing should stop. In the above example,
we just assume that what follows the math symbol doesn't matter,
and 1 is returned because we never want to stop.

To activate the {\em display\_automatic} routine, there must be
in the main program of the example in section~\ref{tx:wd},
before the {\tt while(1)} loop, 
the specification of what to do when a math symbol is used as
\quad {\tt	SetMathAction(display\_automatic);}
\EOF