< PRELIMINARY >

User/Programmer Documentation for the 'SForm' Package
-----------------------------------------------------

Note - This doc is intended for the 'intelligent user'. If you are not intel-
ligent, put this down!



The SForm package is a collection of routines which implement 'screen i/o'.
These routines can paint or clear screen windows, display prompts and data
fields, enter new data, and edit existing data. There are several 'standard'
types of data fields already defined, but there are 'hooks' available which
allow the user program to define its own data fields.

The SForm routines are written in 'c', and expect to interface to a 'c' user
program. The SForm routines are invoked as 'c' functions. The pgmr should
'#include' the file 'sform.h' in any module which interfaces with the SForm
routines.


The SForm source code contains a good deal of 'self documentation'. In
particular, the reader should peruse the following:
	/sform/sform.h
	/sform/src/sfinit.c
	/sform/src/winio.c
	/sform/src/sfdata.c
	



Below is a definition of terms which will be used in this documentation:
user -
	The 'nut loose on the keyboard'. This is the person who is running
	a program which uses the SForm package. He is not assumed to be 
	real smart.
pgmr / programmer -
	The applications programmer. This is the person who writes the program
	which interfaces to the SForm routines. Upon his broad shoulders rests
	the responsibility to properly interface to and invoke the routines.
	He is assumed to be pretty smart (especially if the creation of
	windows is not automated with a 'CSM' type utility).
pgm / program -
	This is the applications program which invokes the SForm routines.
	It may also be refered to as the 'user pgm'.

		Interfacing
		-----------

This section describes the program interface to the SForm package.
Note that 'sform.h' must be included in every user pgm which uses the
SForm routines. Also note the section in the sfdata.c source module which
describes the 'user definable' global variables.


The sform routines library is in the following file -
Altos	- /sform/sform.o
PC		- \sform\sform.lib
This library must be linked into the user program.


The user must create a 'window' structure to define each window. This
struct defines the size of the window and defines the 'fields' within that
window. NOTE that the SForm routines assume the information in the window
structure (and substructures) is ABSOLUTELY correct. If a 'CSM' style
utility is not available, the pgmr will have to define his/her own structures.
Be Careful!

The file '/sform/testdir/allwin.h' is an example of a window with many
different types of fields. The file '/sform/opus/menu.c' is an example of
multiple windows.


The user's pgm interfaces to the sform routines using (mainly) the following
functions -

  sfinit()						/* sfinit.c */
	This function initializes for use of the SForm routines. Note that,
	in general and on most systems, the user pgm should not attempt
	any other form of i/o until the sfterm() function has been invoked.
	Note that the user pgm does not have to explicitly invoke this 
	function, the first call to sfclrwin(), sfwinio(), sffldio(), or
	sfwfdio() will implicitly invoke sfinit() if necessary.

  sfclrwin( winptr )					/* sfinit.c */
  struct SF_WINDOW	*winptr ;
	This function 'open's the window by 'painting' the portion of the
	screen which is the window. Note that this only paints the window,
	no fields (label or data) are displayed. Note that this function must
	be called explicitly if the user pgm wants to clear the window
	while/before using it.
	Note that this routine is much more efficient if the 'window' is
	defined either to be the entire screen (using SF_MAXCOL & SF_MAXROW),
	or if the right side of the window is at the right side of the
	screen (using SF_MAXCOL).
  
  sfwinio( winptr, fld, mode )			/* winio.c */
  struct SF_WINDOW	*winptr ;
  int					*fld ;
  int					mode ;
	This function performs the i/o to/from the window, starting at field
	number '*fld'. Note the modes and what they do (see winio.c & sform.h).
	Note that the function 'sffldio()' can be used to access individual
	fields.
	The return value is a 'completion code' (see sform.h for definitions).
  
  sffldio( fld_desc, mode )				/* winio.c */
  struct SF_FIELD		*fld_desc ;
  int					mode ;
	This function is used to perform i/o on an individual field. It
	is more efficient than sfwinio() is there is only one field of
	interest.
	The return value is a 'completion code' (see sform.h for definitions).

  sfwfdio( winptr, fldnum, mode )		/* winio.c */
  struct SF_WINDOW	*winptr ;
  int					fldnum ;
  inti				mode ;
	This function is analagous to the sffldio() function, but the args are
	different. This function does the necessary addressing to derive a 
	field descriptor ptr from the window ptr and the field number, then
	it calls sffldio().
  
  sfterm()								/* sfinit.c */
	This function MUST be called after sform i/o is completed (well,
	at least on the Altos). The user should not attempt any non-sform
	i/o without first calling sfexit().


The following functions with the sform routines may be useful to the pgmr -

  sfmsg( msg )							/* errs.c */
  char	*msg ;
	The message is displayed on the status line.

  sfbeep()								/* errs.c */
	Outputs a 'beep'.

  sfquery( prmpt, answ, anssiz )		/* query.c */
  char	*prmpt, *answ ;
  int	anssiz ;
	Displays the prompt on the status line and gets user input in the string
	buffer 'answ'. Note that the user response can only be a string. Use
	sfmsgio() if more control is needed.
	Note that, if a 'default' response is not desired, the answer string
	must be nulled out before calling sfquery().

  sfmsgio( prm_desc, ans_desc )			/* query.c */
  struct SF_FIELD	*prm_desc, *ans_desc ;
	Does i/o on status line. Similar to sfquery(), except the user pgm 
	supplies the full fld descriptors for both the prompt and the response.

		General Notes
		-------------

These notes are considered to be particularly important. See also the file
'/sform/doc/notes' for further notes/tips/suggestions.


> The SF_LABFLD bit MUST be set in the fld descriptor of every label fld.
This is how SForm differentiates between label flds and data flds.
