Click above to get retro games delivered to your door ever month!

  Name:     reads() - get user input similar to a get
  Usage:    <lastkey> = reads(<r1>,<c1>,<var>,[<attr>],[<valid>])
  Params:   integer <r1> - row where to place read
            integer <c1> - column where to start read
            string <var> - the memvar to fill, must be character type
            integer <attr> - color for the read buffer (optional),
            string <valid> - a string defining a function call to use
            as the valid clause such as "(trim(var) != [])"

            The optional color may be left off. If none or -1, then
            the Clipper foreground color is used. The <valid>
            argument is a string that contains a valid Clipper
            expression to evaluate. This expression must return a
            logical value. if it returns .T., the user is allowed to
            exit the reads().   If it is .F., the user may not exit.
            This expression can contain any valid Clipper expression,
            including memory variable names and alias pointers. If you
            wish to pass a constant, the constant must be enclosed in
            quotes or brackets, and the entire expression must be
            enclosed in either single or double quotes, or brackets.

  Returns:  Optionally the lastkey pressed before exiting the reads().
            You can use the function exitkeys() to control which keys
            are allowed to exit a reads(). ESCape always exits reads().
            Reads() also sets the lastkey() value so the return value
            is not necessary, but sometimes convenient.

            Reads emulates a Clipper GET command. By passing a
            memory variable, you can have the user fill in the memory
            variable directly with reads(). Since reads() is not tied
            to Clipper's GET system, you can do a reads() inside a
            function called by a SET KEY even if your are in a GET at
            the time. With careful control of looping using if/endif,
            you can create entire pages of reads(). Reads() can only
            fill a character type memory variable. Sending reads() any
            other type of memory variable to fill will result in
            unpredictable results. The following example is a simple
            demonstration:

 ---------------------------------- Example ---------------------------------

                 set color to W/G
                 cls()

                 * limit the keys that are allowed to exit reads()
                 exitkeys(29,23,27,5,13,24)

                 fname = space(15)
                 lname = space(20)
                 address = space(35)

                 esc    = 0
                 level  = 1
                 c_rev  = 23
                 c_norm = 33

                 print(8,0,"First name....",c_norm)
                 print(9,0,"Last name.....",c_norm)

                 print(8,14,fname,c_norm)
                 print(9,14,lname,c_norm)

                 do whil .t.

                      do case
                      case level = 1
                           reads(8,14,fname,c_rev, ;
                                "([] != trim(fname))")
                           print(8,14,fname,c_norm)

                           if lastkey() = 29
                                level = 1
                                loop
                           endif
                           if lastkey() = 23
                                exit
                           endif
                           if lastkey() = 27
                                exit
                           endif
                           if lastkey() = 5
                                level = 2
                                loop
                           endif

                           level = 2

                 case level = 2
                           esc = reads(9,14,lname,c_rev, ;
                                "([] != trim(lname))")
                           print(9,14,lname,c_norm)

                           if esc = 5
                                level = 2
                                loop
                           endif
                           if esc = 29
                                level = 1
                                loop
                           endif
                           if esc = 23 .or. esc = 13
                                exit
                           endif
                           if esc = 27
                                exit
                           endif
                           if esc = 24
                                level = 1
                           loop
                           level = 2

                      otherwise
                           level = 1
                           loop

                 endcase
       enddo

  Keystrokes:    The following keys are normally active inside reads():

            HOME      - Goto beginning of field
            END       - Goto end of line/field
            CTRL/---> - Goto next word
            CTRL/<--- - Goto previous word
            CTRL/F    - Goto Next word
            CTRL/A    - Goto Previous word
            CTRL/T    - Delete the word to the right
            BACKSPACE - Delete character to the left of cursor
            DELETE    - Delete character under the cursor
            INSERT    - Insert characters at current location
            CTRL/Y    - Erase all characters starting at current
                         cursor location to the end of the field
            CTRL/U    - Undo any editing, restores field.
            ESC       - Exit the reads, restore memvar

  Note:     Reads() is a wait state so you can use set key to and
            help routines. You must not however call reads() a
            second time if you hot key out to a second routine. You
            must also not alter the memory variable that you are
            reading in your hot key procedure. If you do, then
            the original contents of the memory variable are lost
            and the memory variable will not contain the users input.
            In addition to reading user input into a memory variable
            you can also have reads() fill an array element with user
            input. Just specify the array element you want to read into
            in place of the memory variable. On return, that array
            element will be filled with the users input. When using
            the valid parameter, your string must contain the name
            of the UDF to execute including the parenthesis inside
            the quotes. See the file readtest.prg on the example diskette
            for an example on how to use reads().