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

  Name:     onkey() - execute a function on every keypress
  Usage:    onkey(<function>)
  Params:   string <function> - the function to execute every time the
            user presses a key while in a wait state. The function has
            to include the parenthesis as part of the function name. To
            turn onkey() processing off, send a null ("") string.

  Returns:  nothing

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

            This function intercepts the key 'A', and replaces it with the
            key 'B'. The function that gets executed returns .T. to
            'eat' the key whenever the next key is going to be an 'A'
            otherwise it returns .F. which processes the key normally.

                 * setup the main procedure
                 memvar = space(50)

                 * setup the onkey() call
                 onkey("eatit()")

                 * set up the read
                 @ 10,0 say "Enter data: " get memvar
                 read

                 * here's the function that eats the key, notice that
                 * it uses nextkey() to check for keys since the key
                 * hasn't been entered yet, so it can't be checked
                 * with lastkey()

                 FUNCTION EATIT

                      if (nextkey() = asc("A"))
                           strstuff("B")
                           return(.T.)
                      endif

                 return(.F.)

  Example2: This example executes a procedure depending on the value of
            the next key that is being entered. It leaves the key alone, so
            the read processes all keys normally.

                 * setup the main procedure
                 memvar = space(50)

                 * setup the onkey() call
                 onkey("doprocs()")

                 * set up the read
                 @ 10,0 say "Enter data: " get memvar
                 read

                 FUNCTION DOPROCS

                      if (nextkey() = asc("F"))
                           do FINDproc
                      elseif (nextkey() = asc("S"))
                           do SEEKproc
                      elseif(nextkey() = asc("P"))
                           do PRINTproc
                      endif

                 return(.F.)

  Note:     Remember that the onkey() function is executing as the user
            is entering keystrokes so keep your onkey functions as small
            and fast as possible. Also keep in mind that if you are
            updating the screen using @ ... say or ? the cursor will be
            moving all over the screen which could be annoying to the
            user. You might be better off using FUNCky print routines
            since they can be faster, and they don't move the cursor. The
            return value of the function affects the next keypress coming
            down the pipe, if the onkey() function returns .F., the next key
            is left alone. If it returns .T., the next key is eaten. Once
            in the onkey() function, you do not have access to the text
            that is being entered into the memvar because the text is not
            entered until the user press return. Do not modify the contents
            of the memvar the user is currently entering.