--- GetField Utility ---

This utility is used to read in a "field" of information at one time.  The
action is similar to a "read" command, except you have the following options:

  1. Conversion to uppercase.
  2. Field attribute is user specified (what color you do want?)
  3. Auto-exit if field is filled
  4. Control-Backspace to erase field and start over
  5. Field can be placed anywhere on screen without needing
     to use an addtional:  GotoXY(Row,Col)
  6. Automatic check for only certain "Legal" characters, or no checking at
     all!
  7. Return of scan code for last key read in...

==============================================================================

To use the utility:

  1. Include the GETFIELD.INC module into your program: either using the
     ^K^R Turbo editor option, or the {$IGETFIELD.INC} compiler option.
     The actual code included is:

            type
              Option_Type = set of 0..7;

            procedure GetField(var KeyVal       : integer;
                               var Legal        : str255;
                               var Ibuf         : str255;
                                   Atrib,
                                   Row,Col,Size : integer;
                                   Options      : Option_Type);

              external 'GETFIELD.BIN';

  2. Define, somewhere prior to the above procedure, the string type:
       type
         str255 = string[255];

  3. Set up variables for each of the following parameters:
        Legal   : This variable contains those characters you want to check for
                  in the input field.  If the string is not a "null" string,
                  then those characters you specify will be the only ones that
                  will be recognized by the input field.  If the string IS
                  a "null" or empty string, then no checking on input will
                  be performed!

        Ibuf    : This is where the data will be read into.  If it is not
                  empty, you can specify that the procedure is to display
                  the "old" value - for editing, etc - or if that option
                  is not chosen, this string will automatically be emptied
                  for you!

        Atrib   : This INTEGER is where you specify what background and
                  foreground you wish to use.  When setting this number,
                  I find the following formula useful:
                    Atrib := (Background_Color shl 4) + Foreground_Color;
                    { add 128 ($80) if you want to have the field "blink"}
                  Background_Color can be any of the "Dark colors" listed
                  on Page 161 of the Turbo Manual (3.01A version), and
                  Foreground_Color can be any of the colors listed in
                  the same table (either "Dark" or "Light" colors).  For
                  an example, the normal screen would be: $000F, and a
                  "reverse" video field would be: $00070.

        Row,Col : These two INTEGER values are the Row (Y position), and
                  Column (X position) of where to start the field.

        Size    : This INTEGER value is the maximum size of the field.  This
                  number determines the size of the colored field.

        Options : This set contains all of the option switches used by this
                  routine. At the present time, the switches are:

                     []  : No options chosen.

                     [1] : Convert all alphabetic values to uppercase.

                     [2] : No use defined yet (more later...)

                     [3] : No use defined yet (more later...)

                     [4] : No use defined yet (more later...)

                     [5] : Exit from field if field is "full".

                     [6] : No use defined yet (more later...)

                     [7] : Use initial value of Input Buffer (Ibuf), otherwise
                           blank Ibuf, and start clean.

                **Note: The options that are not filled in now, will be filled
                        on later versions of this utility!

        KeyVal  : No initial value is needed for this!  This variable will
                  contain the scan code for the last key pressed.  For the
                  scan codes, I use the tables on pages 339 through 343 of
                  the Turbo Manual (3.01A).  However, instead of returning
                  2 characters, I return one integer.  For those keys which
                  are actually an escape-code pair, I take the 2nd byte and
                  add 256.  For example, the manual states that the F1 function
                  key is: 27 59.  I return this as 315. (59+256)

  4. Run your program!  (Try the sample: GETFIELD.PAS   first!?)
==============================================================================

  The routine will exit for a key code of less than 32 ($20), or greater than
127 ($7F) is found, except for the following keys:

       [Home]   = Move cursor to start of field
        [End]   = Move cursor just to the right of the last character
  [LeftArrow]   = Move cursor left one position
 [RightArrow]   = Move cursor right one position
 [^BackSpace]   = Clear entire field and start over
  [BackSpace]   = Erase character to left of cursor, and move cursor left
        [Del]   = Erase charcter at current position.  If not at end of line,
                  move rest of line left one position.