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

Function:    SAYINBOX()

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

Syntax:      SAYINBOX( [color] 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)

             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:     A formatted character string where the first four bytes are
             the screen coordinates of the screen area underneath the
             SAYINBOX() box and message, plus the SAVESCREEN() string
             itself.  This is used as a parameter to the POPBOX() function
             to restore a screen to its state before a SAYINBOX() message
             was displayed.

Description: SAYINBOX() is a screen function very similar to BOXASK().
             However, it is different in two very distinct ways.  First,
             BOXASK() is intended to query the user for a keypress
             response to a message, and to return the key pressed.
             SAYINBOX() does not wait for key input from the user.
             Secondly, SAYINBOX() returns a character string which
             contains the coordinates of the screen region displaced by
             the SAYINBOX() image.  This character string can be used as a
             parameter to the companion function POPBOX() to restore the
             screen to the way it was before SAYINBOX() was called.  This
             feature is ideal for situations where you want to put up a
             message box, do some processing, then remove the message box
             and restore the screen to its previous state.

             This is a function that becomes addictive!  Once you start
             using it you'll never stop.  It's perfect for displaying all
             types of messages in a consistent manner.  SAYINBOX()
             displays up to nine lines of text messages, centered on the
             screen in a single line box, in a user definable color.  Each
             line may be up to 68 characters long.  All of the screen
             centering is done for you.

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

             If the first parameter is a color setting, SAYINBOX() will
             use that color combination instead of the default current
             color.

             If the optional <timeout> argument is supplied, SAYINBOX()
             will wait the specified number of seconds, then restore the
             screen and terminate.

Example:     *-- example of an INDEX message
             pbox = SAYINBOX( "BG+/B", "Indexing, please wait" )
             INDEX ON keyfield TO indexfile
             POPBOX(pbox)

Source:      RL_SAYIN.PRG

See also:    ABOXASK(), BOXASK(), POPBOX()