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

Function:    ABOXASK()

Purpose:     Pop up a centered message box using an array of messages.

Syntax:      ABOXASK( array [, color [, keys [, timeout ] ] ] )

Arguments:   array       - Array of character string messages to display
                           in a message box that is centered on the
                           screen.  Each message can be up to 65
                           characters in length.  Longer strings will be
                           truncated.

             color       - Optional Clipper color string used for the box
                           and message display.  If omitted or a non-
                           character value is given, the default is the
                           current color setting.

             keys        - Optional character string of keys that cause
                           ABOXASK() to terminate if pressed.  This string
                           may consist of letters or control characters.
                           If omitted or a non-character value is given,
                           the default is any keypress will cause
                           ABOXASK() to terminate.

             timeout     - Optional numeric value indicating the number of
                           seconds to wait before timing out and returning
                           a null string ("").  If omitted or a non-
                           numeric value is given, the default wait period
                           is forever (INKEY(0)).

Returns:     The single character pressed in response to the boxed message
             displayed.  If the character is lower case (a-z), it is
             converted to upper case before being returned.  If the
             optional timeout parameter is supplied and no key is pressed
             within the timeout period, a null character ("") is returned.

Description: ABOXASK() is a relative of the BOXASK() and SAYINBOX()
             functions.  It pops up a message box centered on the screen
             and displays the message strings that are contained in the
             message array argument.  If the optional keys argument is
             provided, these keys (expressed as a character string) will
             be the only keys that, when pressed, will cause ABOXASK() to
             terminate, all other keys pressed will be ignored.  If the
             optional timeout is given, ABOXASK() will wait the indicated
             number of seconds for a keypress by issuing the GETKEY()
             function with timeout as the argument.  If no timeout is
             given, ABOXASK() will wait forever for a keypress.

Notes:       ABOXASK() performs essentially the exact same task as
             BOXASK().  However, when a large number of message lines are
             being passed to BOXASK() as arguments, code can get wordy.
             ABOXASK() accepts a single array argument that contains the
             several messages to display.  If only one or two messages are
             being displayed you may want to use BOXASK() since it removes
             the need for declaring an extra array.  ABOXASK() simplifies
             box messages and allows you to maintain pre-defined arrays of
             standard messages and frees you of having to clutter your
             code with the message text strings.

             ABOXASK() will force all letters entered in response to the
             message prompt to upper case.  All other keys are returned as
             their CHR() values.

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

             *-- present message, wait 30 seconds, default to ENTER
             IF ABOXASK( msg, "W+/R", CHR(13)+CHR(27), 30 ) = CHR(27)
                *-- ESCAPE key was explicitly pressed
                EXIT
             ENDIF

Source:      RL_ABOXA.PRG

See also:    BOXASK(), SAYINBOX()