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

Function:    BOXASK()

Purpose:     Pop up a centered message box using multiple message strings.

Syntax:      BOXASK( [color] [keys] message1 [...message9] [timeout] )

Arguments:   color       - If the FIRST parameter has a slash "/"
                           character in the 2nd, 3rd, or 4th position,
                           this parameter will be interpreted as the color
                           setting for the message box.  (All color
                           strings look like: R/W, or R+/W, or R+*/W)

             keys        - If the FIRST or SECOND parameter begins with a
                           dollar sign character "$", the parameter will
                           be interpreted as a string of valid keys that
                           can be pressed to terminate BOXASK().  The "$"
                           character is easily remembered because it is
                           the Clipper substring "contained in" operator.

             message1,9  - Any other character parameters, including the
                           first and or second parameters if they don't
                           meet the above conditions, will be displayed as
                           BOXASK() messages.  Up to nine message lines
                           may be passed and displayed.

             timeout     - If the LAST parameter is a numeric value, it
                           will be used as a timeout value for the message
                           box.  This timeout is the number of seconds
                           BOXASK() will wait for a keypress.  If no key
                           is pressed before the timeout is reached,
                           BOXASK() will exit and return a null string.
                           If no timeout is supplied, BOXASK() will wait
                           forever for a keypress.

Returns:     The single character pressed in response to the message box
             displayed on the screen.  If the key pressed is an alphabetic
             character BOXASK will return the character normalized to
             upper case.  As a consequence, character comparisons need
             only compare against upper case characters.  See examples.

Description: BOXASK() is a function that becomes addictive!  Once you
             start using it you'll never stop.  It's perfect for
             displaying all sorts of messages in a consistent manner.
             BOXASK() displays up to nine lines of text messages, centered
             on the screen in a single line box, in a defined color.  Each
             line may be up to 68 characters long.  All of the screen
             centering is done automatically.  After the message box is
             displayed BOXASK() waits for a user keypress (in response to
             the message).  If no time out parameter is given, BOXASK will
             wait forever for a response.  If the optional keys parameter
             is supplied, the characters that appear in the keys string
             will be the only character accepted as valid keypresses to
             terminate BOXASK().

Notes:       BOXASK() accepts a variable number of parameters and will act
             differently on the parameters depending on their format.  All
             parameters (except the timeout, which must be the last
             parameter) are expected to be character type.

             If the first parameter is a color setting, BOXASK() will use
             that color combination instead of the default current color
             SETCOLOR().  If either the first or second parameters begin
             with the "$" character, the string following the dollar sign
             will be used as a list of valid keypresses from which to
             exit.

             Ideally, all functions should be as BLACK BOX as possible.
             This means that if a function alters a system state such as
             the screen color, it should restore the system to the way it
             was on entry.  Since BOXASK() will query a user for a
             keypress, ideally the cursor should be on.  However, since
             Clipper Summer '87 has no native way of querying the state of
             the cursor, BOXASK() has no way of knowing whether or not the
             cursor was on, and can not set cursor on and expect to
             restore the system to the way it was.  To get around this
             limitation, and still allow BOXASK to turn the cursor on, an
             RLIB function named SETCURSOR() is provided.  (See the
             documentation SETCURSOR)  If you utilize the SETCURSOR()
             function, BOXASK() will know and will be able to restore the
             state of the cursor on exit.  The Clipper 5.0 version uses
             the internal SETCURSOR function instead.

             If the key that is pressed in response to BOXASK() is a lower
             case letter (a - z), BOXASK() will return the response as an
             upper case letter.  In other words, BOXASK() will uppercase
             letters between a-z, so you do not have to use the UPPER()
             function to test if the user pressed a "Y" for instance.  All
             other keys are returned as their CHR() values.  BOXASK() will
             wait forever for a keypress unless a timeout value is given.

             In the Clipper 5.0 version of BOXASK(), the PARAMETERS have
             remained as PRIVATE variables since they are referenced via
             macro substitution, and this will not work with local
             variables.

Example:     *-- example of a SEEK or LOCATE failure notification
             msg1 = "No record was found with the name you selected!"
             msg2 = "This name may have been misspelled"
             msg3 = "Press [ENTER] to try again, or [ESCAPE] to abort"

             color = "W+/R"
             keys  = "$" + CHR(13) + CHR(27)
             *-- present message, wait 30 seconds, default to ENTER
             IF BOXASK( color, keys, msg1, msg2, msg3, 30 ) = CHR(27)
                *-- ESCAPE key was explicitly pressed
                EXIT
             ENDIF
             *-- will fall through if timed out, result = CHR(13) or NULL

Source:      RL_BOXAS.PRG

See also:    ABOXASK(), SAYINBOX()