/*------------------------ 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. */ /* 07/24/90 DCV Release 1.2. Mouse usage and */ /* modification of routine names. */ /*--------------------------------------------------------------*/ 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. Optional mouse support. Background routine processing. 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. - Form_Define. 2) Add the form selection items. - Form_Add. 3) Define the form selection prompt. - Form_PromptAdd. 4) Define the form selection text. - Form_TextAdd. 5) Execute the form. - Form_Entry. 6) Release the form storage. - Form_Delete. 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, list, and mouse 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. If you are compiling a program written for VISIONS 1.0 and do not wish to modify the routine names in your source, add the following statement to provide name conversions. #include "FORMCONV.H" /*------------------------------------------------------------------------*/ Form_Add 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 Form_PromptAdd and Form_TextAdd. Calling Sequence: status = Form_Add(form_ptr, form_valid, field_ptr); Inputs: FORM_HEAD *form_ptr; - This is a pointer to the form structure to add to. FLAG *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 Form_PromptAddField and Form_TextAddField, passing this pointer and appropriate parameters. WORD status; - This is the value of the function. Possible values are: FORM_ERR_NO_ERR Success FORM_ERR_BAD_HEAD Pointer received is not valid form header. FORM_ERR_ALLOC_FIELD Out of heap space for allocation. As returned by called routines. Functions called: List_Append. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Form_Define 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 = Form_Define(new_form,topy,leftx,height,width, bkcol,txtcol,title,options); Inputs: UBYTE topy, height, leftx, width; - These are the desired screen coordinates for the form. DWORD bkcol, txtcol; - These are the colors used for the text and background display of the form. TEXT *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. TBITS options; - This is the set of bits defining different window options. Possible bit settings are: SINGLE_BORDER_BIT - Single line border. -No border is also DOUBLE_BORDER_BIT - Double line border. -possible by setting MOUSE_ENABLE_BIT - Enable the mouse. -no bit. Outputs: FORM_HEAD **new_form; - This is a pointer to the form structure created. WORD status; - This is the result of the function. Possible values are: FORM_ERR_NO_ERR Success. As returned by called routines. Functions called: List_Define. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Form_Delete Purpose: This routine releases the form memory structure to the heap. Calling Sequence: status = Form_Delete(new_form); Inputs: FORM_HEAD *new_form; - This is a structure defining the form to be released. Outputs: WORD status; - This is the result of the function. Possible values are: FORM_ERR_NO_ERR Success. FORM_ERR_BAD_HEAD Pointer received is not valid form header. As returned by called routines. Functions called: List_Delete. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Form_Entry 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 = Form_Entry(new_form); Inputs: FORM_HEAD *new_form; - This is a structure defining the form to be executed. Outputs: WORD status; - This is the result of the function. Possible values are: FORM_ERR_NO_ERR Success, user hit Enter. FORM_USER_ABORT User aborted by hitting Esc. FORM_ERR_BAD_HEAD Passed form pointer is invalid. As returned by called routines. Functions called: Comp_GetKey, Window_SetPtr, Comp_SetTextWindow, Comp_Kbhit. Mouse_TextCursorLimits, Mouse_ClearButtons, Mouse_Init, Mouse_AllocAndSave, Mouse_CursorControl, Mouse_GetButtonPress, Mouse_VirToPhys, Mouse_RestoreState. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Form_GetDefine Purpose: This routine returns the parameters for the form screen structure. Calling Sequence: status = Form_GetDefine(formptr, &topy, &leftx, &height, &width, &bkcol, &txtcol, &title, &options); Inputs: struct FormHead *formptr; - This is a structure defining the form. UBYTE *topy, *height, *leftx, *width; - These are the screen coordinates for the form. DWORD *bkcol, *txtcol; - These are the colors used for the text and background display of the form. TEXT *(*title); - This is the displayed title of the form. BITS *options; - This is the set of bits defining different window options. Possible bit settings are: SINGLE_BORDER_BIT - Single line border. -No border is also DOUBLE_BORDER_BIT - Double line border. -possible by setting no bit. MOUSE_ENABLE_BIT - Enable the mouse. Outputs: WORD status; - This is the result of the function. Possible values are: FORM_ERR_NO_ERR Success. FORM_ERR_BAD_HEAD Pointer received is not valid form header. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Form_PromptAdd Purpose: This routine is define the prompt field of a form selection item. Calling Sequence: status = Form_PromptAdd(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 prompt descriptor to be defined. UBYTE length; - This is the length of the prompt. UBYTE row, col; - These are the desired screen coordinates for the prompt. DWORD bkcol, txtcol; - These are the colors used for the text and background display of items. DWORD highbkcol, highcol; - These are the colors used for the highlighted text and background display of items. Not currently implemented. TEXT *str_txt; - This is the displayed prompt for the field. Outputs: WORD status; - This is the result of the function. Return values are: FORM_ERR_NO_ERR Success FORM_ERR_BAD_FIELD Received field pointer is invalid. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Form_ReDefine Purpose: This routine changes the parameters to a form screen structure. These changes will not take effect until the form is redisplayed. Calling Sequence: status = Form_ReDefine(formptr, topy, leftx, height, width, bkcol, txtcol, title, options); Inputs: struct FormHead *formptr; - This is a structure defining the form. UBYTE topy, height, leftx, width; - These are the desired screen coordinates for the form. DWORD bkcol, txtcol; - These are the colors used for the text and background display of the form. TEXT *title; - This is the displayed title of the form. It will be automatically center justified. A null string causes no title to be displayed. BITS options; - This is the set of bits defining different window options. Possible bit settings are: SINGLE_BORDER_BIT - Single line border. -No border is also DOUBLE_BORDER_BIT - Double line border. -possible by setting MOUSE_ENABLE_BIT - Enable the mouse. -no bit. Outputs: WORD status; - This is the result of the function. Possible values are: FORM_ERR_NO_ERR Success. FORM_ERR_BAD_HEAD Pointer received is not valid form header. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Form_TextAdd Purpose: This routine is define the text entry field of a form selection item. Calling Sequence: status = Form_TextAdd(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. UBYTE length; - This is the maximum length of the text entry. UBYTE row, col; - These are the desired screen coordinates for the prompt. DWORD bkcol, txtcol; - These are the colors used for the text and background display of items. DWORD highbkcol, highcol; - These are the colors used for the text and background display of highlighted items. TEXT *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: WORD status; - This is the result of the function. Return values are: FORM_ERR_NO_ERR Success FORM_ERR_BAD_FIELD Received field pointer is invalid. Functions called: None. /*------------------------------------------------------------------------*/ 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. FORM_USER_ABORT -1 User aborted out of a form. FORM_ERR_NO_ERR 0 Success. FORM_ERR_ALLOC_FORM -400 No heap available for form definition. FORM_ERR_ALLOC_FIELD -401 No heap available for field definition. FORM_ERR_BAD_HEAD -402 Pointer received was not a form head. FORM_ERR_BAD_FIELD -403 Pointer received was not a form field. FORM_ERR_BAD_TEXT -404 Illegal character rec'vd as data entry. FORM_ERR_INVALID_ENTRY -405 Field contents not legal as modified.