/*
 * $Id: sleep.txt 15102 2010-07-14 12:48:39Z vszakats $
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_SLEEP
 *  $CATEGORY$
 *     Menus/Prompts
 *  $ONELINER$
 *     Wait for a specified amount of time
 *  $SYNTAX$
 *     FT_SLEEP( <nSeconds>, [<nInitial>] ) -> nil
 *  $ARGUMENTS$
 *    <nSeconds> is the number of seconds to pause
 * 
 *    <nInitial> is an optional clock value (from a call to SECONDS())
 *               from which the <nSeconds> seconds are to elapse. Useful
 *               for setting a minimum time between the start of events
 *               which could take a variable amount of time due to the
 *               execution of intervening code.
 *  $RETURNS$
 *     NIL
 *  $DESCRIPTION$
 *     This routine will wait a specified period of time. It provides
 *     resolution based upon the execution of the SECONDS() function.
 *     It does not use an input state such as INKEY(). The specified time
 *     is the minimum time sleeping and will usually be slightly longer.
 * 
 *     The second optional argument allows one to begin timing an event
 *     prior to executing some operation. This is useful when, for example,
 *     you input a key or mouse click and wish to do something but still want
 *     to note if the user double entered (mouse or key) within a certain time
 *     which in turn may have meaning within your program's context.
 * 
 *     The routine correctly handles passing through midnight but will not
 *     work for more than 24 hours.
 *  $EXAMPLES$
 *     Example 1:
 *         FT_SLEEP(10.0)    // Sleep for 10.0 seconds
 *     Example 2:
 *         nTime := SECONDS()   // usually after some interupt from mouse or
 *                              // keyboard
 * 
 *         ... intervening code ...
 * 
 *         FT_SLEEP(0.5, nTime) // Sleep until the sytem clock is
 *                              // nTime+0.5 seconds.
 * 
 *  $END$
 */
