WwDialog Function

Creates a blocking or nonblocking dialog box.

Usage

wid = WwDialog(parent, [label,] OKCallback, CancelCallback, HelpCallback)

Input Parameters

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.

Returned Value

wid — The ID of the dialog widget.

Keywords

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.

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.

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.

Color/Font Keywords

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.

Get/Set Value

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

setvalue — Sets a string in the text input field.

Callback Parameters

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

wid — Command widget ID.

text — Text input field widget ID.

Discussion

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).

Note:

The label parameter provides a method for “hard-coding” the input field label in the application. For greater flexibility, create your resource file using a text editor, and load the resource containing the dialog label string using WtResource. The Name keyword can then be used in the WwDialog calling sequence to specify the dialog widget name in the resource specification.

Example 1

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

Example 2

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

myapp.dialog.selectionLabelString: Enter some text: