Creates a blocking or nonblocking dialog box.

parent — The widget ID of the parent widget.

label — (optional) A string containing the label for the input field. If the label parameter is either not defined or is defined as a null string, the function looks for the dialog label in a resource specification (see Discussion).

OKCallback — A string containing the name of the callback that is executed when the OK button is selected.

CancelCallback — A string containing the name of the callback that is executed when the Cancel button is selected.

HelpCallback — A string containing the name of the callback that is executed when the Help button is selected.

wid — The ID of the dialog widget.

Block — If this keyword is present and nonzero, the dialog box is blocking (the default).

Cols — Specifies the number of columns in the text input field.

Help — Use this keyword to specify a help topic when the HelpCallback parameter is not specified. This keyword can specify a two-element or one-element string array. If it is a two-element array, the first element is the name of a help topic and the second is the filename of the help file containing the topic. A one-element array specifies only the name of a help topic. In this case the default help file is used. For information on the location of the default help file, refer to the HELP command. The specified help topic is displayed in the online help viewer when the Help button is pressed.

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.

Name — A string specifying the name of the PromptDialog widget. The keyword Name can be used in place of the label parameter, although label (if other than a null string) will take precedence if both are given. (Default: dialog.)

Nonblock — If this keyword is present an nonzero, the dialog box is not blocking. (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.

Text — Specifies a string containing the initial text in the text input field.

Title — Specifies a string containing the dialog box title.

Background — Specifies the background color name.

Font — Specifies the name of the font used for text.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

getvalue — Gets a string containing the text entered in the text input field.

setvalue — Sets a string in the text input field.

Any dialog box callback procedure must have the following two parameters:

wid — Command widget ID.

text — Text input field widget ID.

A dialog box is a popup window. This means that it cannot be the child of the top-level shell or the layout widget. Usually, a dialog box widget is activated by a pushbutton or menu button, as in the example below.

Part of the dialog label resource can be specified using the Name keyword, otherwise the default is the *.dialog.selectionLabelString resource (where selectionLabelString is the attribute).

This example creates a button labeled Dialog Box. When the user selects this button, a dialog box appears. When the user enters text in the dialog box and presses <Return>, DialogOK is executed. When the user cancels the dialog box, the second callback routine, DialogCancel, is executed.

Enter the callback procedure into a file, and compile the procedure with the .RUN command. Then, enter the widget commands at the WAVE> prompt. To dismiss both widgets, select the appropriate function (such as Close) from the window manager menu of the Dialog Box button (the parent widget).

PRO DbuttonCB, wid, data

   select=WwDialog(wid,'Type something:', $

      'DialogOK','DialogCancel', Title='Type')

END

PRO DialogOK, wid, text

   PRINT,'Dialog OK'

   value = WwGetValue(text)

   PRINT, value

END

PRO DialogCancel, wid, data

   PRINT,'Dialog Cancel'

END

PRO ww_ex23

   top=WwInit('ww_ex23', 'Examples', layout)

   button=WwButtonBox(layout, 'Dialog Box', 'DbuttonCB')

   status=WwSetValue(top, /Display)

   WwLoop

END

A typical resource specification for the dialog prompt used in WwDialog is:

myapp.dialog.selectionLabelString: Enter some text:

WoGenericDialog, WwGenericDialog

For detailed information on GUI development, refer to the PV‑WAVE Application Developer’s Guide.

For more information about how to write an application program based on PV‑WAVE Widgets, refer to Using Wave Widgets in the PV‑WAVE Application Developer’s Guide.

For additional information on the color and font keywords, see "Setting Colors and Fonts" in the PV‑WAVE Application Developer’s Guide.

For information on Get and Set values, see "Setting and Getting Widget Values" in the PV‑WAVE Application Developer’s Guide.