/*------------------------ VIS_FORM.TXT ------------------------*/
/*                                                              */
/*  This file contains the VISIONS Form Library Manual          */
/*                                                              */
/*         Copyright 1990 Dan Vogel & David Bernazzani          */
/*                                                              */
/*   Date        Initials        Comments                       */
/*                                                              */
/*  03/13/90       DCV       Initial Release 0.00.              */
/*--------------------------------------------------------------*/

                        Overview


   The VISIONS form library is a simple library, written in C, to 
provide color or monochrome text forms on PC/XT/AT class machines.  The 
library was originally written in Microsoft C 5.1, but an attempt to 
separate compiler specific code into a separate source file was made, and 
this file, COMPSPEC.C, is provided with the library.  The VISIONS Form  
library uses the VISIONS Window and List librarys.
   The features provided by the form library are:

     MGA, CGA, EGA, VGA, MCGA compatible color text forms.
     Automatic color conversion for monochrome adaptors.
     User selectable screen colors and highlights.
     User selectable form sizes.
     User specified text entry verification.
     Text entry editing capability.
     Optional form titles.
     Optional form borders and border type.
 




                        Theory of Operation


   The following is a brief overview of the operation of the form 
library routines.  This is intended to help the user to understand 
the library's operation better, so that it may be used more effectively.
   The VISIONS form system is intended to execute a form structure which 
defines a form.  This form structure consists of a header which defines 
form-wide parameters, such as titles, colors, and position, as well as a 
pointer to a separate list of actual form selections or itmes.  The 
form selection corresponds to a single entry field in the form with its
paired prompt field.  The information contained in the form selection 
structure consists of separate substructures for the prompt field and the 
text entry field, either of which may be NULL.  The prompt and text fields 
each contain length and position information, as well as the character 
string for that field.  The difference between the text and prompt 
structures is in the handling of the text string.  The prompt string 
is displayed only, while the text string is displayed as the default, and 
may then be modified.  This flexibility allows a form selection to be as 
simple as a name entry selection, with "Name:" for the prompt followed by 
the entry field, or something more complicated like a multiple line set of 
directions requiring on form selection per line, each with a prompt string, 
but also each with a zero length text entry structure.  Examples of both 
may be found in the demonstration program.  With this brief description of the internal data structures, we 
can proceed to how the package works.
   In order to use the VISIONS form library to execute a form, four steps 
must be taken:

        1) Define the form structure.          - DefineForm.
        2) Add the form selection items.       - AddToForm.
        3) Define the form selection prompt.   - AddToPrompt.
        4) Define the form selection text.     - AddToText.
        5) Execute the form.                   - FormEntry.
        6) Release the form storage.           - DeleteForm.

Note that while these steps must occur in this order, some variations are 
possible.  For example, the same form may be needed over and over within a 
program.  In this case the form may be created at the beginning of the 
program and released at the end, but the execution, step five, may be 
repeated several times within the program.  Another possibility is that a 
form that has already been defined and executed is needed again, but with 
more items from which to select.  This is possible by defining more form
items on the same form structure and then executing it again.  Note however 
that form items will be edited on the screen in the order in which they are 
defined!



                        Routine Definitions

   In order to use the below routines you must include the file 
"USERFORM.H" in your source code with the following statement.

                #include "USERFORM.H"

This will automatically include the window and list definitions files 
at the same time.  Examples of the use of these routines are available 
in the VISIONS demonstration program, in the file DEMOFORM.C.



/*------------------------------------------------------------------------*/
                        AddToForm

Purpose:  This routine is used to add a form selection to a defined form
 base.  This selection will then appear and can be acted upon when the 
 form is displayed.  The text and prompt fields within this selection 
 must still be defined however by the routines AddToPrompt and AddToText.

Calling Sequence: 
   status = AddToForm(form_ptr, form_valid, field_ptr);

Inputs:
   FORM_HEAD *form_ptr;  - This is a pointer to the form structure to add to.

   char *form_valid();  - This is the field validation routine that 
        determines whether an entry field contains a valid entry.

Outputs:
   FORM_FIELD **field_ptr;  - This is a pointer to the field selection 
        structure created.  It must still be filled in by calling 
        AddToPromptField and AddToTextField, passing this pointer and 
        appropriate parameters.

   int status;  - This is the value of the function.  Possible values are:
        0                        Success
        BAD_FORM_HEAD_PTR        Pointer received is not valid form header.
        OUT_OF_FIELD_HEAP        Out of heap space for allocation.
        <Others>                 As returned by called routines.

Functions called:
   AppendToList, malloc.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        AddToPrompt

Purpose:  This routine is define the prompt field of a form selection
 item.

Calling Sequence: 
  status = AddToPrompt(field_ptr,row,col,length,bkcol,txtcol,str_txt);

Inputs:
   FORM_FIELD *field_ptr;  - This is a pointer to the form selection
        structure to containing the prompt descriptor to be defined.

   BYTE length;  - This is the length of the prompt.

   BYTE row, col;  - These are the desired screen coordinates for the prompt.

   long int bkcol, txtcol; - These are the colors used for the text 
        and background display of items.

   char *str_txt;  - This is the displayed prompt for the field.

Outputs:
   int status;  - This is the result of the function.  Return values are:
        0                        Success
        BAD_FORM_FIELD_PTR       Received field pointer is invalid.

Functions called:
   SetFieldType.

/*------------------------------------------------------------------------*/



/*------------------------------------------------------------------------*/
                        AddToText

Purpose:  This routine is define the text entry field of a form selection
 item.

Calling Sequence: 
   status = AddToText(field_ptr,row,col,length,bkcol,txtcol,
        highbkcol,highcol,str_txt);

Inputs:
   FORM_FIELD *field_ptr;  - This is a pointer to the form selection
        structure to containing the text descriptor to be defined.

   BYTE length;  - This is the maximum length of the text entry.

   BYTE row, col;  - These are the desired screen coordinates for the prompt.

   long int bkcol, txtcol; - These are the colors used for the text 
        and background display of items.

   long int highbkcol, highcol; - These are the colors used for the text 
        and background display of highlighted items.

   char *str_txt;  - This is the character string to be used for the 
        text read into this field.  This string must be at least length+1 
        bytes long, and it may contain a default value on entry.

Outputs:
   status - int - This is the result of the function.  Return values are:
        0                        Success
        BAD_FORM_FIELD_PTR       Received field pointer is invalid.

Functions called:
   SetFieldType.

/*------------------------------------------------------------------------*/






/*------------------------------------------------------------------------*/
                        DefineForm

Purpose:  This routine initializes a forms screen structure, 
 consisting of a title, color definitions, position definitions, and a 
 border type.  A structure containing these values is created and handed 
 back to be added to, to define each field for forms entry.

Calling Sequence: 
   status = DefineForm(new_form,topy,leftx,height,width,
                border,bkcol,txtcol,title);

Inputs:
   BYTE topy, height, leftx, width;  - These are the desired screen 
        coordinates for the form.

   BYTE border;  - This is the type of border desired for the form.  
        Possibilities are NOBORDER, SINGLEBORDER, and DOUBLEBORDER.

   long int bkcol, txtcol;  - These are the colors used for the text 
        and background display of the form.

   char *title;  - This is the displayed title of the form.  It will be 
        automatically center justified.  A null or empty string causes 
        no title to be displayed.

Outputs:
   FORM_HEAD **new_form;  - This is a pointer to the form structure created.

   int status;  - This is the result of the function.  Possible values are:
        0                Success.
        <Others>         As returned by called routines.

Functions called:
   DefineList,  AllocateForm.

/*------------------------------------------------------------------------*/



/*------------------------------------------------------------------------*/
                        DeleteForm

Purpose:  This routine releases the form memory structure to the heap.

Calling Sequence: 
   status = DeleteForm(new_form);

Inputs:
   FORM_HEAD *new_form;  - This is a structure defining the form to 
        be released.

Outputs:
   int status;  - This is the result of the function.  Possible values are:
        0                       Success.
        BAD_FORM_HEAD_PTR       Pointer received is not valid form header.
        <Others>                As returned by called routines.

Functions called:
   DeleteList,  free.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        FormEntry

Purpose:  This routine displays the passed form and handles user 
 keystrokes to the form.  Special keys recognized include cursor keys,
 delete, enter, escape, backspace, home, end, and all other keys as text.

Calling Sequence: 
   status = FormEntry(new_form);

Inputs:
   FORM_HEAD *new_form;  - This is a structure defining the form to 
        be executed.

Outputs:
   int status;  - This is the result of the function.  Possible values are:
        0                       Success, user hit Enter.
        USER_ABORT              User aborted by hitting Esc.
        BAD_FORM_HEAD_PTR       Passed form pointer is invalid.
        <Other>                 As returned by called routines.

Functions called:  (Mostly Forms internal..)
   FormToggleCursor,  FormExitField,  FormDownCursor,  FormEndCursor,  
   FormUpCursor,  FormDelete,  FormInsert,  FormLeftCursor,  FormRightCursor
   FormHomeCursor,  FormText,  FormDisplay,  RemoveWindow,  DeleteWindow.

/*------------------------------------------------------------------------*/





                        Error Codes

   The following is the list of error codes that can be returned from the 
VISIONS form library.  Errors from calls to the windows or list librarys 
will be passed back unchanged.  These error values can be found in the 
window and list manuals.

Error Name              Value       Description.

USER_ABORT                -1        User aborted out of a form.

OUT_OF_FORM_HEAP        -301        No heap available for form definition.
OUT_OF_FIELD_HEAP       -302        No heap available for field definition.
BAD_FORM_HEAD_PTR       -303        Pointer received was not a form head.
BAD_FORM_FIELD_PTR      -304        Pointer received was not a form field.
BAD_FORM_TEXT           -305        Illegal character rec'vd as data entry.
INVALID_FIELD_ENTRY     -306        Field contents not legal as modified.

               