/*------------------------ 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. 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. 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. 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. 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.