Alert()
 Display a simple modal dialog box.
-------------------------------------------------------------------------------

 Syntax:

     Alert( <cMessage>[, <aOptions>][, <cColors>][, <lAlarm>][, <lShadow>] )
     --> <nChoice>

 Arguments:

     <cMessage> defines a message shown centered in the alert box.
     If the message contains one or more semicolons, the text after the
     semicolons is centered on succeeding lines in the dialog box.

     <aOptions> defines a list of possible responses to the dialog
     box.  Default is {"OK"}.

     <cColors> is a five color (foreground/background) string which is used
     to define the colors of the Alert() window.  The first color is used
     to draw the box and messages.  The second color is used for the menu
     choices, the third is the highlight bar for the menu, the fourth is the
     hot key color on normal display and the fifth is the hot key color for
     the highlighted button.  If not supplied the colors default to
     "W+/R, W+/B, W+/BG, R/BG, R/B".

     <lAlarm> is a logical indicating whether the ALERT is to sound an
     alarm when envoked.  The default is .F.

     <lShadow> is a logical indicating if the ALERT BOX is to be shadowed.
     Default is the current SetShadow() value.

 Returns:

     ALERT() returns a numeric value indicating which option was
     chosen.  If the Esc key is pressed, the value returned is zero.

 Description:

     The ALERT() function creates a simple modal dialog.  It is useful in
     error handlers and other "pause" functions.  The user can respond by
     moving a highlight bar and pressing the Return or Space keys, or by
     pressing the key corresponding to the first letter of the option.  If
     <aOptions> is not supplied, a single "OK" option is presented.

 Examples:

     This example demonstrates how an alert dialog box is used.  First,
     the array of options is defined, the ALERT() function is then
     called to get the user's selection, and finally the user's choice
     is handled with a DO CASE...ENDCASE control structure.

     #define AL_SAVE   1
     #define AL_CANCEL 2
     #define AL_CONT   3

     // Define an array of options
     aOptions := {"~Save", "~Don't Save", "~Continue"}

     // Display the dialog box and get the user's selection
     nChoice  := ALERT("File has changed...", aOptions)

     // Handle the user's request
     DO CASE
     CASE nChoice == AL_SAVE
        ? "Save"
     CASE nChoice == AL_CANCEL
        ? "Don't Save"
     CASE nChoice == AL_CONT
        ? "Continue"
     OTHERWISE
        ? "Escape"
     ENDCASE
     //
     RETURN


 Files:  Library is CUACLIP.LIB