WwAlert Function

Creates a modal (blocking) or modeless (non-blocking) popup alert box containing a message and optional control buttons.

Important: On Microsoft Windows, if a WwAlert is created by a non-blocking application and the NoWait keyword is NOT used, dismissing it via the Delete ("X") button or the Close menu item causes PV-WAVE command line access to be blocked until the application exits. To prevent this, use the keyword NoSystemMenu in the call to WwAlert. The NoSystemMenu keyword causes the dialog to be displayed without the system menu and associated buttons (maximize, minimize, and delete) on its title bar. In this case a button must be provided to allow removal of the dialog.

Usage

wid = WwAlert(parent, label[, answers])

Input Parameters

parent — The widget ID of the parent widget.

label — A string containing the message text.

answers — (optional) A string or array of strings (0–3) containing the text to appear on the buttons. If this parameter is not specified, the following default text is used: OK, Cancel, and Help.

Returned Value

wid — The index number of the button that was clicked. If the Nowait keyword is specified, the alert box ID is returned.

Keywords

After — Specifies the number of seconds that the alert box appears. After the specified number of seconds, the alert box is automatically destroyed, and WwAlert returns the value –1.

Block — If nonzero, creates a modal (blocking) alert box.

Error — If nonzero, creates an error alert box.

Help — A string specifying the name of a topic in the online Help system For a list of valid Help topics, bring up the Search dialog box from the main online Help window.

Helpfile — Specifies a string containing the name of an online Help file.

Icon_file — A string containing either the full pathname or the filename of the icon file. If the icon file is not found, then the warning message, "Unable to find specified icon file: filename, using default icon file." appears.

Note:

The default icon definition is based on Windows vs. Motif as the window manager. On Windows, the default becomes the parent icon definition or the system icon if no parent has defined a unique window icon. On Motif, the default becomes the icon defined by !WIDGET_ICON.

Info — If nonzero, creates an information alert box.

Name — Specifies a string containing the name for the Warning, Question, Working, or Information dialog widget. (Default: Alert.)

NoConfirm — If nonzero, no buttons are displayed in the alert box.

NonBlock — If nonzero, creates a non-blocking alert box. (This keyword has no effect under Microsoft Windows.)

NoSystemMenu — (Windows only) Causes the dialog to be displayed without the system menu and associated buttons (maximize, minimize, and close) on it's title bar. This keyword has no effect under UNIX.

Nowait — If nonzero, WwAlert returns to the caller immediately after the alert box appears, and WwAlert returns the alert box ID.

Question — If nonzero, creates a question alert box.

Raise — If nonzero, the alert box always appears in front of other windows.

Title — Specifies a string containing the alert box title.

Warning — If nonzero, creates a warning alert box.

Working — If nonzero, creates a working alert box.

Color/Font Keywords

Background — Specifies the background color name.

Font — Specifies the font’s name for the text that appears in the alert box.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

Get/Set Value

None.

Callback Parameters

None.

Discussion

The alert box can be used to:

Halt execution of the program until the alert condition is satisfied.

Allow the calling routine to display an alert with a specified number of buttons (0–3) and button labels.

The alert box supports the following features:

Multiline labels. (Use the ASCII code \012 at the end of each line to indicate a <Return>, or you can use an array of strings, where each array element is taken to be a separate line.)

Context sensitive help.

Note:

If the Nowait keyword is specified, control is returned to the calling routine immediately after the alert becomes visible. After that point, it is up to the calling routine to destroy the alert box with the WwAlertPopdown function.

Example

This example creates a button box containing seven buttons that test the features of the WwAlert function. The callback ButtonCB is executed when one of the buttons in the button box is selected.

Enter the callback procedure and the main procedure into a file, and compile it with the .RUN command. To run the example, enter testalert at the WAVE> prompt. To dismiss the button box, select the appropriate function (such as Close) from the window manager menu.

PRO ButtonCB, wid, idx

   message = ['This is an example', $

      'of the Alert Box','Wave Widget']

   CASE idx OF

      1:button=WwAlert(wid, message)

      2:button=WwAlert(wid, message, After = 5)

      3:button=WwAlert(wid, message,/Noconfirm, /Raise)

      4:button=WwAlert(wid, message, "Done")

      5:button=WwAlert(wid, message,["Done","Dismiss"])

      6:button=WwAlert(wid,message,["Done","Dismiss","Bye"])

      7:button=WwAlert(wid, message, /Noconfirm, /Nowait)

   ENDCASE

   PRINT, 'Button selected: ', button

   CASE button OF

      1: PRINT, 'Selected OK'

      2: PRINT, 'Selected Cancel'

      3: PRINT, 'Selected Help'

      ELSE: PRINT, 'None selected'

   ENDCASE

   IF idx EQ 7 THEN BEGIN

      WAIT, 5

      PRINT,'Done waiting, popping it down...'

      WwAlertPopdown, button

   ENDIF

END

PRO testalert

   top = WwInit('testalert', 'Test', layout)

   buttons = ['Alert', 'Alert After', '0 button', '1 button', $

      '2 buttons', '3 buttons', 'Nowait']

   button = WwButtonBox(layout, buttons, "ButtonCB")

   status = WwSetValue(top, /Display)

   WwLoop

END