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

  Name:     timeout() - specify function to execute during wait state
  Usage:    timeout(<ticks>,<function>,[<key>])
  Params:   integer <ticks> - the number of clock ticks to wait
            before executing <function>. 1 tick is approx 1/18th of
            a second. If this parameter is set to zero and a function
            to execute is defined, then that function will be executed
            constantly as many times as possible when there are no keys
            being input. specifying 0 as the timeout value causes the
            function to be executed around 100 times per second.

            string <function> - the function name to execute enclosed
            in quotes. You must include the parenthesis in the name.

            integer <key> - the inkey() value of the key to stuff
            into the buffer if the function returns .F., optional, if
            left off, then the default is the last key you defined, or
            if on the first call, then it is the ESCape key (27)

            To turn timeout() off, specify a null as the second parameter
            and a zero as the first parameter. You can tell timeout()
            to not stuff any key at all by using the key value of 0. It
            will still execute your function after <nn> clock ticks, but
            it will not stuff any keys regardless of the return value
            of the function or expression.

  Returns:  nothing

            Be careful if your timeout() functions execute wait states
            that call other timeout() functions. Clipper has a limit on
            how many levels and parameters you can pass. Timeout() will
            work on any Clipper and FUNCky function that reads the
            keyboard, including inkey() and the mouse button functions.
            If you need to check for key values in the timeout() function
            you should use lastkey(), and not inkey() so you don't
            interfere with keyboard input in the foreground process.

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

            This example sets up a read. It sets the timeout factor
            to 5 minutes. If no keyboard activity takes place for
            5 minutes, the program branches to the function defined
            by the second parameter. The function returns .F. so
            the key defined in the timeout() setup is stuffed into
            the buffer, causing the read to terminate.

                 * setup up the timeout()
                 * there are about 1080 ticks in a minute
                 timeout(5*1080,"TERMPROC()",27)

                 * do the read
                 memvar = space(30)
                 @ 10,0 say "Enter data: " get memvar
                 read

                 if (lastkey() = 27)
                      return
                 endif

                 FUNCTION TERMPROC

                      print(24,0,strcenter("Closing Files",80),33)
                      close databases

                 return(.F.)

            Since the function that was branched to returns .F.
            the key defined by the last parameter is stuffed into
            the keyboard buffer. If the function returns .T., then
            no key is stuffed and the wait state continues.

  Example2: This example branches out to a function on every keyboard
            poll. If a key is pressed, it is processed. If on the keyboard
            check there is no key waiting, timeout() goes and executes
            your function. This example uses that to display context
            sensitive messages while in a GET, it updates the display
            depending on the current variable the user is getting at the
            moment. This function uses the timeout(0) option to execute
            the function constantly if there is no keyboard input.

                 * initialize variables
                 Fname = space(15)
                 Lname = space(20)
                 Mcode = space(4)
                 Lastvar = ""   && use as a flag in the timeout

                 * setup the timeout() using 0 as the wait. That
                 * tells timeout() to execute the function constantly.
                 timeout(0,"disphelp()",0)

                 * setup the read
                 set color to W/B,B/W,W/B,W/B
                 box(5,10,12,51,"",23)
                 @ 7,12 say "Enter Name     : " get Fname
                 @ 8,12 say "Enter Last Name: " get Lname
                 @ 9,12 say "Enter Code #   : " get Mcode
                 read

            * Here's the function that timeout calls constantly.
            * Note that we use print() and box() for their speed
            * and the fact that they don't move the cursor all
            * over the screen. The lastvar flag assures that the
            * box doesn't flicker because of constant updating.

            FUNCTION disphelp

            do case
                 case readvar() = "FNAME"
                      if lastvar = "FNAME"
                           return(.T.)
                      endif
                      lastvar = readvar()
                      box(15,10,20,51,"",23)
                      print(17,17,"Enter the first name of the",23)
                      print(18,17,"client affiliated with the",23)
                      print(19,17,"project",23)

                 case readvar() = "LNAME"
                      if lastvar = "LNAME"
                           return(.T.)
                      endif
                      lastvar = readvar()
                      box(15,10,20,51,"",23)
                      print(17,17,"Enter the last name of the",23)
                      print(18,17,"client",23)

                 case readvar() = "MCODE"
                      if lastvar = "MCODE"
                           return(.T.)
                      endif
                      lastvar = readvar()
                      box(15,10,20,51,"",23)
                      print(17,17,"Enter the project code",23)
                      print(18,17,"based on the pink sheet",23)

            endcase

            return(.T.)

  Note:     The possibilities for misuse of this function are
            tremendous. Keep your timeout functions as short
            as possible so that your function does not interfere
            too greatly with the foreground process. Also, if you
            use the ?, @ .. say, @ .. box stuff, keep in mind that
            the cursor is going to be flying all over the place
            while the user is entering the data. FUNCky saves
            and restores the cursor position when it executes your
            timeout function so that the cursor is always where the
            user expects it. Using the FUNCky screen handling
            functions do not cause this problem since they do not
            move the cursor as they write to the screen. Do not modify
            the variable the user is entering data into while in a
            function during a timeout(). The variable contents will not
            be re-displayed to the user and will cause erroneous result.

            When timeout() executes your function, it automatically
            turns itself off. When your function finishes, timeout()
            turns itself back on. This prevents timeout() from
            calling itself if you go into a wait state in your
            timeout function. You can however re-start timeout() by
            simply calling it in your timeout function. You can
            redefine the function to be called on the next timeout
            so that you could issue a 5 minute warning or something
            similar before you actually exit the read. This would
            require 2 timeouts, 1 to display the message, and 1
            to stuff the ESCape key into the buffer. The first timeout
            function sets up the second timeout function.

            The function expression that you pass to timeout() can
            be any valid expression that results in a logical return
            value. The entire expression has to be enclosed in quotes,
            and any constants inside the quotes must be enclosed in
            brackets ([]) or single quotes (''). As an example, you can
            specify to timeout() to stuff the ESCape key after waiting
            30 seconds for input only if it past 3:00 pm.

                 * setup the timeout using a complex expression.
                 * this timeout only occurs when the time string
                 * returned by time() is greater than "15:00:00"

                 timeout(30*18,"(! val(time()) > 15)", 27)

            Remember, if you want timeout() to stuff the key defined
            into the buffer, return .F.. If you want to continue
            processing without stuffing any keys, return .T.. Timeout()
            does not use any timer interrupts so it does not cause
            any of the types of timer vector problems associated with
            the clock() or keystat() type stuff.

            There are all kinds of possibilities for this function. You
            could specify a timeout() with the 0 timer tick value, and
            then you could continually display the current row() and
            col() position of the cursor while inside the get or
            memoedit(). One thing to note is you do not have access
            to the contents of the memory variable being entered as it
            is being entered. Clipper doesn't assign the text entered to
            the variable until the user presses return. You can however
            keep track of all keystrokes entered via the lastkey()
            function.