home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / window / visions / vis_form.txt < prev    next >
Encoding:
Text File  |  1990-05-20  |  12.8 KB  |  327 lines
  1. /*------------------------ VIS_FORM.TXT ------------------------*/
  2. /*                                                              */
  3. /*  This file contains the VISIONS Form Library Manual          */
  4. /*                                                              */
  5. /*         Copyright 1990 Dan Vogel & David Bernazzani          */
  6. /*                                                              */
  7. /*   Date        Initials        Comments                       */
  8. /*                                                              */
  9. /*  03/13/90       DCV       Initial Release 0.00.              */
  10. /*--------------------------------------------------------------*/
  11.  
  12.                         Overview
  13.  
  14.  
  15.    The VISIONS form library is a simple library, written in C, to 
  16. provide color or monochrome text forms on PC/XT/AT class machines.  The 
  17. library was originally written in Microsoft C 5.1, but an attempt to 
  18. separate compiler specific code into a separate source file was made, and 
  19. this file, COMPSPEC.C, is provided with the library.  The VISIONS Form  
  20. library uses the VISIONS Window and List librarys.
  21.    The features provided by the form library are:
  22.  
  23.      MGA, CGA, EGA, VGA, MCGA compatible color text forms.
  24.      Automatic color conversion for monochrome adaptors.
  25.      User selectable screen colors and highlights.
  26.      User selectable form sizes.
  27.      User specified text entry verification.
  28.      Text entry editing capability.
  29.      Optional form titles.
  30.      Optional form borders and border type.
  31.  
  32.  
  33.  
  34.  
  35.  
  36.                         Theory of Operation
  37.  
  38.  
  39.    The following is a brief overview of the operation of the form 
  40. library routines.  This is intended to help the user to understand 
  41. the library's operation better, so that it may be used more effectively.
  42.    The VISIONS form system is intended to execute a form structure which 
  43. defines a form.  This form structure consists of a header which defines 
  44. form-wide parameters, such as titles, colors, and position, as well as a 
  45. pointer to a separate list of actual form selections or itmes.  The 
  46. form selection corresponds to a single entry field in the form with its
  47. paired prompt field.  The information contained in the form selection 
  48. structure consists of separate substructures for the prompt field and the 
  49. text entry field, either of which may be NULL.  The prompt and text fields 
  50. each contain length and position information, as well as the character 
  51. string for that field.  The difference between the text and prompt 
  52. structures is in the handling of the text string.  The prompt string 
  53. is displayed only, while the text string is displayed as the default, and 
  54. may then be modified.  This flexibility allows a form selection to be as 
  55. simple as a name entry selection, with "Name:" for the prompt followed by 
  56. the entry field, or something more complicated like a multiple line set of 
  57. directions requiring on form selection per line, each with a prompt string, 
  58. but also each with a zero length text entry structure.  Examples of both 
  59. may be found in the demonstration program.  With this brief description of the internal data structures, we 
  60. can proceed to how the package works.
  61.    In order to use the VISIONS form library to execute a form, four steps 
  62. must be taken:
  63.  
  64.         1) Define the form structure.          - DefineForm.
  65.         2) Add the form selection items.       - AddToForm.
  66.         3) Define the form selection prompt.   - AddToPrompt.
  67.         4) Define the form selection text.     - AddToText.
  68.         5) Execute the form.                   - FormEntry.
  69.         6) Release the form storage.           - DeleteForm.
  70.  
  71. Note that while these steps must occur in this order, some variations are 
  72. possible.  For example, the same form may be needed over and over within a 
  73. program.  In this case the form may be created at the beginning of the 
  74. program and released at the end, but the execution, step five, may be 
  75. repeated several times within the program.  Another possibility is that a 
  76. form that has already been defined and executed is needed again, but with 
  77. more items from which to select.  This is possible by defining more form
  78. items on the same form structure and then executing it again.  Note however 
  79. that form items will be edited on the screen in the order in which they are 
  80. defined!
  81.  
  82.  
  83.  
  84.                         Routine Definitions
  85.  
  86.    In order to use the below routines you must include the file 
  87. "USERFORM.H" in your source code with the following statement.
  88.  
  89.                 #include "USERFORM.H"
  90.  
  91. This will automatically include the window and list definitions files 
  92. at the same time.  Examples of the use of these routines are available 
  93. in the VISIONS demonstration program, in the file DEMOFORM.C.
  94.  
  95.  
  96.  
  97. /*------------------------------------------------------------------------*/
  98.                         AddToForm
  99.  
  100. Purpose:  This routine is used to add a form selection to a defined form
  101.  base.  This selection will then appear and can be acted upon when the 
  102.  form is displayed.  The text and prompt fields within this selection 
  103.  must still be defined however by the routines AddToPrompt and AddToText.
  104.  
  105. Calling Sequence: 
  106.    status = AddToForm(form_ptr, form_valid, field_ptr);
  107.  
  108. Inputs:
  109.    FORM_HEAD *form_ptr;  - This is a pointer to the form structure to add to.
  110.  
  111.    char *form_valid();  - This is the field validation routine that 
  112.         determines whether an entry field contains a valid entry.
  113.  
  114. Outputs:
  115.    FORM_FIELD **field_ptr;  - This is a pointer to the field selection 
  116.         structure created.  It must still be filled in by calling 
  117.         AddToPromptField and AddToTextField, passing this pointer and 
  118.         appropriate parameters.
  119.  
  120.    int status;  - This is the value of the function.  Possible values are:
  121.         0                        Success
  122.         BAD_FORM_HEAD_PTR        Pointer received is not valid form header.
  123.         OUT_OF_FIELD_HEAP        Out of heap space for allocation.
  124.         <Others>                 As returned by called routines.
  125.  
  126. Functions called:
  127.    AppendToList, malloc.
  128.  
  129. /*------------------------------------------------------------------------*/
  130.  
  131.  
  132.  
  133.  
  134. /*------------------------------------------------------------------------*/
  135.                         AddToPrompt
  136.  
  137. Purpose:  This routine is define the prompt field of a form selection
  138.  item.
  139.  
  140. Calling Sequence: 
  141.   status = AddToPrompt(field_ptr,row,col,length,bkcol,txtcol,str_txt);
  142.  
  143. Inputs:
  144.    FORM_FIELD *field_ptr;  - This is a pointer to the form selection
  145.         structure to containing the prompt descriptor to be defined.
  146.  
  147.    BYTE length;  - This is the length of the prompt.
  148.  
  149.    BYTE row, col;  - These are the desired screen coordinates for the prompt.
  150.  
  151.    long int bkcol, txtcol; - These are the colors used for the text 
  152.         and background display of items.
  153.  
  154.    char *str_txt;  - This is the displayed prompt for the field.
  155.  
  156. Outputs:
  157.    int status;  - This is the result of the function.  Return values are:
  158.         0                        Success
  159.         BAD_FORM_FIELD_PTR       Received field pointer is invalid.
  160.  
  161. Functions called:
  162.    SetFieldType.
  163.  
  164. /*------------------------------------------------------------------------*/
  165.  
  166.  
  167.  
  168. /*------------------------------------------------------------------------*/
  169.                         AddToText
  170.  
  171. Purpose:  This routine is define the text entry field of a form selection
  172.  item.
  173.  
  174. Calling Sequence: 
  175.    status = AddToText(field_ptr,row,col,length,bkcol,txtcol,
  176.         highbkcol,highcol,str_txt);
  177.  
  178. Inputs:
  179.    FORM_FIELD *field_ptr;  - This is a pointer to the form selection
  180.         structure to containing the text descriptor to be defined.
  181.  
  182.    BYTE length;  - This is the maximum length of the text entry.
  183.  
  184.    BYTE row, col;  - These are the desired screen coordinates for the prompt.
  185.  
  186.    long int bkcol, txtcol; - These are the colors used for the text 
  187.         and background display of items.
  188.  
  189.    long int highbkcol, highcol; - These are the colors used for the text 
  190.         and background display of highlighted items.
  191.  
  192.    char *str_txt;  - This is the character string to be used for the 
  193.         text read into this field.  This string must be at least length+1 
  194.         bytes long, and it may contain a default value on entry.
  195.  
  196. Outputs:
  197.    status - int - This is the result of the function.  Return values are:
  198.         0                        Success
  199.         BAD_FORM_FIELD_PTR       Received field pointer is invalid.
  200.  
  201. Functions called:
  202.    SetFieldType.
  203.  
  204. /*------------------------------------------------------------------------*/
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211. /*------------------------------------------------------------------------*/
  212.                         DefineForm
  213.  
  214. Purpose:  This routine initializes a forms screen structure, 
  215.  consisting of a title, color definitions, position definitions, and a 
  216.  border type.  A structure containing these values is created and handed 
  217.  back to be added to, to define each field for forms entry.
  218.  
  219. Calling Sequence: 
  220.    status = DefineForm(new_form,topy,leftx,height,width,
  221.                 border,bkcol,txtcol,title);
  222.  
  223. Inputs:
  224.    BYTE topy, height, leftx, width;  - These are the desired screen 
  225.         coordinates for the form.
  226.  
  227.    BYTE border;  - This is the type of border desired for the form.  
  228.         Possibilities are NOBORDER, SINGLEBORDER, and DOUBLEBORDER.
  229.  
  230.    long int bkcol, txtcol;  - These are the colors used for the text 
  231.         and background display of the form.
  232.  
  233.    char *title;  - This is the displayed title of the form.  It will be 
  234.         automatically center justified.  A null or empty string causes 
  235.         no title to be displayed.
  236.  
  237. Outputs:
  238.    FORM_HEAD **new_form;  - This is a pointer to the form structure created.
  239.  
  240.    int status;  - This is the result of the function.  Possible values are:
  241.         0                Success.
  242.         <Others>         As returned by called routines.
  243.  
  244. Functions called:
  245.    DefineList,  AllocateForm.
  246.  
  247. /*------------------------------------------------------------------------*/
  248.  
  249.  
  250.  
  251. /*------------------------------------------------------------------------*/
  252.                         DeleteForm
  253.  
  254. Purpose:  This routine releases the form memory structure to the heap.
  255.  
  256. Calling Sequence: 
  257.    status = DeleteForm(new_form);
  258.  
  259. Inputs:
  260.    FORM_HEAD *new_form;  - This is a structure defining the form to 
  261.         be released.
  262.  
  263. Outputs:
  264.    int status;  - This is the result of the function.  Possible values are:
  265.         0                       Success.
  266.         BAD_FORM_HEAD_PTR       Pointer received is not valid form header.
  267.         <Others>                As returned by called routines.
  268.  
  269. Functions called:
  270.    DeleteList,  free.
  271.  
  272. /*------------------------------------------------------------------------*/
  273.  
  274.  
  275.  
  276.  
  277. /*------------------------------------------------------------------------*/
  278.                         FormEntry
  279.  
  280. Purpose:  This routine displays the passed form and handles user 
  281.  keystrokes to the form.  Special keys recognized include cursor keys,
  282.  delete, enter, escape, backspace, home, end, and all other keys as text.
  283.  
  284. Calling Sequence: 
  285.    status = FormEntry(new_form);
  286.  
  287. Inputs:
  288.    FORM_HEAD *new_form;  - This is a structure defining the form to 
  289.         be executed.
  290.  
  291. Outputs:
  292.    int status;  - This is the result of the function.  Possible values are:
  293.         0                       Success, user hit Enter.
  294.         USER_ABORT              User aborted by hitting Esc.
  295.         BAD_FORM_HEAD_PTR       Passed form pointer is invalid.
  296.         <Other>                 As returned by called routines.
  297.  
  298. Functions called:  (Mostly Forms internal..)
  299.    FormToggleCursor,  FormExitField,  FormDownCursor,  FormEndCursor,  
  300.    FormUpCursor,  FormDelete,  FormInsert,  FormLeftCursor,  FormRightCursor
  301.    FormHomeCursor,  FormText,  FormDisplay,  RemoveWindow,  DeleteWindow.
  302.  
  303. /*------------------------------------------------------------------------*/
  304.  
  305.  
  306.  
  307.  
  308.  
  309.                         Error Codes
  310.  
  311.    The following is the list of error codes that can be returned from the 
  312. VISIONS form library.  Errors from calls to the windows or list librarys 
  313. will be passed back unchanged.  These error values can be found in the 
  314. window and list manuals.
  315.  
  316. Error Name              Value       Description.
  317.  
  318. USER_ABORT                -1        User aborted out of a form.
  319.  
  320. OUT_OF_FORM_HEAP        -301        No heap available for form definition.
  321. OUT_OF_FIELD_HEAP       -302        No heap available for field definition.
  322. BAD_FORM_HEAD_PTR       -303        Pointer received was not a form head.
  323. BAD_FORM_FIELD_PTR      -304        Pointer received was not a form field.
  324. BAD_FORM_TEXT           -305        Illegal character rec'vd as data entry.
  325. INVALID_FIELD_ENTRY     -306        Field contents not legal as modified.
  326.  
  327.