WwGenericDialog Function

Reference Guide > W Routines > WwGenericDialog Function

Creates a generic dialog box that can be filled with custom widgets.

Usage

widget = WwGenericDialog(parent, layout[, labels][, callback])

Input Parameters

parent — The parent widget’s ID.

labels — (optional) A string or an array of strings containing the text that is to appear on the buttons in the Action area of the dialog box. This parameter determines the number of buttons in the Action area, and the text for the buttons.

callback — (optional) A string containing the name of the callback routine.

Output Parameters

layout — The widget ID of the layout widget (i.e., the widget returned by WwLayout). The layout widget must be filled in by the calling program.

Keywords

Block — If nonzero, the dialog box is blocking.

Board — If nonzero, a “bulletin board” layout is created.

Buttons — If specified, returns the WwButtonBox button widget IDs. For more information, see the WwButtonBox Function description.

Default — The button index (0–n) of the button selected by default. A negative value results in no buttons being set by default and if no value is given, button 0 will be active.

note	A negative value is useful in situations where hitting a carriage return in a dialog should activate something else, such as acceptance of a value entered in a text field in that dialog.

Dialog_Name — A string containing the name of the generic dialog box.

Dismiss — An array of integers indicating which buttons in the Action area close the generic dialog box.

1 — Indicates the button closes the dialog box.

0 — Indicates the button doesn’t close the generic dialog box.

Form — If nonzero, a form layout is created.

Help — A string containing the name of an online Help Topic. If Help is specified, the right-most (last) Action area button is the Help button, regardless of its name or label. The Help keyword can also be specified as a two-element string array, whose first element is the help topic and whose second element is the Help file name.

Horizontal — If nonzero, child widgets are aligned horizontally within the layout widget. This keyword is only used for row/column layouts.

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.

Layout_Name — An array of strings containing the names of the top-level and Action area widgets.

Name — An array of strings containing the names of the Action area buttons. If the number of elements in Name is less than the number of buttons, or if the labels parameter was not specified, the remaining buttons are assigned default names of the form button_n, where n is the button index.

NoDestroy — If nonzero, the dialog box widget is hidden instead of destroyed when the Cancel button is selected.

NonBlock — If 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.

Scroll — If nonzero, places scroll bars on the layout widget. If this keyword is specified, you must also provide the following parameters:

w — Sets the width of the scrolled window.

h — Sets the height of the scrolled window.

Spacing — Specifies the amount of space in pixels between child widgets in the layout. This keyword is only used for row/column layouts. (Default: 0)

Title — A string containing the title to appear on border of the dialog box.

Vertical — If nonzero, child widgets are aligned vertically within the parent widget. This keyword is only used for row/column layouts.

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.

Callback Parameters and Returned Value

A generic dialog box callback must be a function containing the following two parameters:

wid — The widget ID of a button in the Action area.

index — The index of the Action area button pressed (1 – n).

Returned Values

0 — Indicates dialog box behaves according to Dismiss keyword.

1 — Indicates dialog box is not dismissed regardless of Dismiss keyword.

Discussion

The generic dialog box contains three major components:

Action area — Contains a set of horizontal buttons at the bottom of the dialog box.

Separator — Placed above the Action area.

Layout area — An area that holds custom widgets. This area’s widget ID is returned by the output parameter layout.

Example

This example creates a dialog box containing some simple slider controls. Callbacks perform some simple actions whenever a slider is moved by the user.

Enter the following code into a file, and compile it with the .RUN command. To run the example, enter WWGENERICDIALOG_TEST2 at the WAVE> prompt. Click the Create button in the main window to display the dialog box.

Button callback for the dialog created with WwGenericDialog.

This function always returns 0. If a 1 was returned instead of 0, the dialog would not be destroyed even if the Dismiss flag was set for the button pressed. This allows the callback to pop up an alert and avoid destroying the dialog if an error occurred.

FUNCTION SimpleDialogCB, wid, data

   PRINT, 'SimpleDialogCB', wid, data

   RETURN, 0

END

Now, create the slider callback for the sliders in the dialog created with the
WwGenericDialog function. This callback prints out the slider widget ID and the new value.

PRO Slidercallback, wid, data

   value = WwGetValue (wid)

   PRINT, 'slidercallback', wid, data, value

END

The next callback creates the dialog using the WwGenericDialog function. The dialog created contains three sliders (Red, Green, and Blue), and three buttons (OK, Apply, and Cancel).

PRO wwgenericdialog_button_cb, wid, which

   IF which EQ 2 THEN BEGIN

      topshell = WwGetValue (wid, /Userdata)

      status = WwSetValue (topshell, /Close)

      RETURN

   ENDIF

   ; Create the generic dialog.

   dialog_wid = WwGenericDialog (wid, layout, $

      ['OK', 'Apply', 'Cancel', 'Help'], 'SimpleDialogCB', $

      /Form, Dismiss = [1, 0, 1], Title = 'Simple Dialog', $

      Help = 'WwGenericDialog')

   ; Fill in the dialog layout.

   controls = WwControlsBox(layout, ['Red', 'Green', 'Blue'], $

      [0, 255, 0, 255, 0, 255], 'SliderCallback', /Left, $

      /Right, /Top, /Bottom, /Vertical)

   ; Manage the dialog.

   status = WwSetValue (dialog_wid, /Show)

END

This is the destroy callback for the top-level shell.

PRO wwgenericdialog_destroy_cb, wid, data

   PRINT, 'wwgenericdialog_destroy_cb', wid, data

END

This is the main entry point for the test program. It creates a window with a button that creates a new dialog with the WwGenericDialog function when the button is pressed.

PRO Wwgenericdialog_test2

   ; Create the top-level shell, and initialize WAVE Widgets.

   topshell = WwInit ('wwgenericdialog_test2', 'Appl', $

      workarea, 'Wwgenericdialog_destroy_cb', $

      background = background, foreground = foreground, $

      title=new_title, position=position)

   ; Create the buttons.

   buttonbox=WwButtonBox (workarea, ['Create...', 'Quit'], $

      'wwgenericdialog_button_cb', buttons = buttons)

   FOR i=0L, N_ELEMENTS(buttons)-1 DO BEGIN

      ; Keep the top-level shell in button user data so we can

      ; use it later.

      status = WwSetValue (buttons(i), Userdata = topshell)

   ENDFOR

   status = WwSetValue(topshell, /display)

   ; Manage the top-level shell, and start looping.

   WwLoop

END