WoGenericDialog Function

Reference Guide > W Routines > WoGenericDialog Function

Creates a generic dialog box for use in VDA Tools.

Usage

container = WoGenericDialog(parent, topLayout[,callback])

Input Parameters

parent — Specifies the parent widget ID of the dialog (long).

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

Output Parameters

topLayout — The widget ID of the top-level layout widget (long).

Returned Value

container — The widget ID of the dialog box (long).

Keywords

Apply — Inserts an action button with the label Apply in the dialog box.

Block — If nonzero, the dialog is blocking. (Default: nonblocking)

Board — If nonzero, a bulletin board layout is created for the topLayout. A form widget is the default.

Form widgets are “attached” to one another inside the layout. Bulletin board widgets are positioned in the layout with x, y coordinates.

Buttons — Returns the button widget IDs from WwButtonBox.

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.

Cancel — Inserts an action button with the label Cancel in the dialog box. Unmanages the dialog when pressed.

Dialog_Name — Specifies a string containing a name for the generic dialog widget.

Dismiss — Inserts an action button with the label Dismiss in the dialog box.

Help — Specifies either a scalar string or a two-element string array. and inserts an action button with the label Help in the dialog box. This button is always inserted in the rightmost position in the action button area. If a scalar string, the button brings up help on the topic specified by the string. A two-element string array can be used to specify a topic name and the name of a help file.

Next — Inserts an action button with the label Next in the dialog box.

No — Inserts an action button with the label No in the dialog box. Unmanages the dialog when pressed.

NoDestroy — If nonzero, the dialog box widget is hidden instead of destroyed when any button that closes the dialog box (e.g., the Cancel button) is selected.

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.

Ok — (The default) Inserts an action button with the label OK in the dialog box. Unmanages the dialog when pressed.

Previous — Inserts an action button with the label Previous in the dialog box.

Reset — Inserts an action button with the label Reset in the dialog box.

Title — Specifies a string containing the title of the dialog box.

Yes — (Overrides Ok) Inserts an action button with the label Yes in the dialog box. Unmanages the dialog when pressed.

Callback Parameters

wid — The widget ID of the action area button.

index — The index of the action area button that was pressed. The first button is 1; the second, 2; and so on.

Discussion

The purpose of this function is to provide an easy method for you to add a dialog box to a VDA Tool. This dialog is generic in that you can add widgets of your choice to it.

The dialog is returned unmanaged; it is assumed that the calling routine will fill the upper layout and then manage the dialog.

Buttons that will appear at the bottom of the dialog are controlled with keyword parameters. The buttons will be positioned properly for compliance with the Motif style guide.

This function assumes that most dialog attributes will be controlled via resources rather than a parameter list. Use the Resource keyword on WwInit, or the WtResource function, to set the resource values.

The behavior of the dialog box is as follows:

The second parameter returns the widget ID of the layout widget, which can be filled in by the caller. This layout widget will always be a form widget.

The optional “callback” (third) parameter supplies a callback that will be called when a button is selected. This callback behaves the same as a callback from the WwGenericDialog function.

The callback should be a function that returns 0 (accept default dismiss behavior) or 1 (veto dismiss).

If the Help keyword is used, the rightmost (last) button is assumed to be the Help button (no matter what its name or label), and it will bring up the online Help system. You can specify a help file other than the standard one for PV‑WAVE by passing a 2-element string array ['help_topic_name', 'filename'] with the Help keyword.

Example

This example creates an entry point from which you can bring up a dialog box created with WoGenericDialog. The dialog box contains three action buttons and a text field.

FUNCTION Wogenericdialog_btn_cb, wid, data

   ; This function is called when any button in the generic

   ; dialog is pressed. If the function returns 0, the default

   ; button action (close for OK and Cancel, don’t close for

   ; Apply) happens. If a 1 is returned for the OK or Cancel

   ; button presses, the dialog will not be closed. This

   ; allows the programmer to keep the dialog up if an error

   ; condition needs to be corrected.

   PRINT, 'wogenericdialog_btn_cb', wid, data

   RETURN, 0

END

; This procedure prints what the user typed into the text field.

PRO Text_cb, wid, data

   value = WwGetValue (wid)

   print, 'Value: ', value

END

PRO wogenericdialog_button_cb, wid, data

   ; This procedure creates a generic dialog containing three

   ; buttons: "OK", "Apply", and "Cancel". The dialog contains a

   ; text widget to type into.

   COMMON wogenericdialog_common, topshell, $

      wogenericdialog_shell

   CASE data OF

   1: BEGIN ; Simple

   dialog_wid = WoGenericDialog (topshell, layout, $

      /OK, /Apply, /Cancel)

   text_wid = WwText (layout, 'Text_CB', Label = $

      'Type something here: ', /Top, /Left)

   status = WwSetValue (dialog_wid, /Show)

END

   2: BEGIN ; Quit

   status = WwSetValue (topshell, /Close)

END

   ENDCASE

END

; This is the main entry point. It creates a window with two

; buttons; one button is used to create a dialog with

; WoGenericDialog(), and the other is used to quit the sample

; application.

PRO wogenericdialog_test

   COMMON wogenericdialog_common, topshell, $

      wogenericdialog_shell

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

      workarea)

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

      'wogenericdialog_button_cb', /horizontal)

   status = WwSetValue(topshell, /display)

   WwLoop

END