GETINPUT()
 Keyboard input function similar to a GET field
------------------------------------------------------------------------------
 Syntax

     GETINPUT(<cDefault>,[<nRow>],[<nColumn>],[<lSAY>],
        [<cPrompt>]) --> cInput

 Arguments

     <cDefault>  Designates the content and length of the input field.

     <nRow>  Designates the row in which the input occurs.  The default
     is the current cursor position.

     <nColumn>  Designates the column in which the input occurs.  The
     default is the current cursor position.

     <lSAY>  When you specify .T. and close GETINPUT(), the actual data
     input is displayed with the standard color attribute.

     <cPrompt>  Designates text to display in front of the input field at
     the selected coordinates.  The default is no prompt text.

 Returns

     GETINPUT() returns the input string.

 Description

     If you call this function, a simple input field is made available.  All
     control keys are interpreted exactly as in a CA-Clipper GET mask.  The
     length and default for the string are specified in the <cDefault>
     parameter.  This allows you to portray a normal input field with VAR=
     SPACE(length).  The input field starts at the current cursor position or
     at the designated row and column.  Similar to @ ... SAY...GET,  you can
     also display text just before the input text.  The field starting
     position is moved accordingly.

     In the CA-Clipper SET COLOR TO command, the first color you designate
     stands for screen output; the second for input fields. GETINPUT() uses
     these color designators exactly like CA-Clipper.  If you designate the
     <lSAY> parameter as .T., you can determine (as with a SAY), whether to
     redisplay the data in its amended form at the point of input.  After
     data input is complete, the data displayed on the screen is the same as
     the values returned by the function.  This is useful when an input
     breaks off due to an ESC.  For example, the data is "the quick brown
     fox" and you change it to "the slow brown fox".  If <lSAY> is .T. and
     you press escape, the original data (the quick brown fox) is restored.
     The affected area also contains the default color attribute.

 Notes

     .  GETINPUT() uses the CA-Clipper console input internal routines
        and supports the INS display in SCOREBOARD.  In addition, the SET
        ESCAPE, SET BELL, SET INTENSITY, SET DELIMITERS, and SET CONFIRM
        switches are acknowledged.

     .  Key traps may occur within GETINPUT() when the cursor position
        within a field is saved.  GETINPUT() is then called recursively, as
        long as sufficient stack memory is available.

 Examples

     .  Input at the current cursor position:

        cVar := SPACE(20)           // 20 position input field
        cVar := GETINPUT(cVar)      // Retain input attribute

     .  Input a 10 space field, row 10, column 20:

        cVar := GETINPUT(SPACE(10), 10, 20)

     .  After input is finished, the actual data input is redisplayed
        on the screen.  This area contains the standard color attribute.  The
        input is moved by the text preceding the input field:

        SET CONFIRM ON              //  Close with RETURN
        cVAR := "Default text"
        GETINPUT(cVar, 10, 20, .T., "Please input: ")