Note: The Dialog() function is deprecated and might not work at all in future versions of JMP. Use either New Window() with the Modal argument, or Column Dialog() for column selection.
Using New Window() instead of Dialog() means that you can use standard display box constructors, instead of the specialized constructors for Dialog().
When you submit a script with a modal window, JMP draws the window, waits for the user to make choices and click OK, and then stores a list of the variables with their values. Modal means that the user has no choice but to respond to the window. Any attempt to click outside the window produces an error sound, and script execution is suspended until the user clicks OK or Cancel.
The Column Dialog function is specifically intended to prompt users to choose columns from the current (topmost) data table. Windows created by Column Dialog are also modal windows.
Notice that the argument to Number Edit Box is the default value, 42. Also notice that a dialog box without at least one Button makes no sense, so JMP adds a button if you script a modal window without one.
If you click OK, the dialog box closes, it returns {Button(1)}, and the script continues. To reference the number set, use variablebox<<get.
If you click Cancel, the dialog box closes, it returns {Button(-1)}, and the script continues. See Throwing and Catching Exceptions in Programming Methods, for information about canceling a script.
Note: Modal windows require at least one button for dismissing the window. You can use OK, Yes, No, or Cancel to label modal window buttons. If you do not include at least one of these buttons in a modal window, JMP adds an OK button.
Dialog() is deprecated and has been replaced with New Window() and the << Modal message. Though old scripts based on Dialog() still run, we recommend that you use New Window() instead.
The sections below illustrate the differences between the Dialog() function and the New Window() function.
A major difference between Dialog() and New Window() controls is how you specify lists and strings as arguments. In New Window(), the items must be placed in a list. In Dialog(), items were generally comma-separated. For example, compare the following two instances of a combo box control.
Note: The script does not explicitly define the OK button. For modal windows, JMP automatically adds the OK button. Explicitly define each additional button.
Additionally, Dialog() could include " " to indicate empty text. New Window() requires that empty text appear in a Text Box (" ").
In New Window(), boxes are horizontally aligned with H List Box() and vertically aligned with V List Box(). In Dialog(), you used H List and V List instead.
In New Window(), use Line Up Box to arrange items in the number of columns that you specify. In Dialog(), you used Line Up.
Clicking OK returns the following result in the log window:
Clicking OK returns the following result in the log window:
Note: JMP does exert some control over OK and Cancel button positions to ensure that dialog boxes are consistent with what the operating system expects. In certain cases, JMP needs to override your H List, V List, and Line Up settings for Button("OK") and Button("Cancel"). Do not be alarmed if the result is slightly different from what you expect.
Another difference between the deprecated Dialog() and New Window() functions is the usage of Radio Box.
In New Window(), use Text Edit Box to create editable boxes that contain specified strings. In Dialog(), you use Edit Text.
Alternatively, use String Col Edit Box to create editable boxes within in a table structure that contains specified strings. For example, the following script creates a window named “String Col Box”. The window contains a column (labeled “Strings”) of editable boxes, each of which contains the specified string:
In New Window(), use Number Edit Box to create editable boxes that contains the specified numbers. In Dialog(), you used Edit Number. For example:
Another method for creating the same window uses Number Col Edit Box to create editable boxes within in a table structure that contains specified numbers. For example, the following script creates a window named “Number Col Edit Box”. The window contains a column (labeled “Random Numbers”) of editable boxes, each of which shows the specified type of random number:
One of the benefits of using New Window() is the ability to add optional scripts to display boxes. In Dialog(), the following Combo Box could not include an optional script. If you wanted an action associated with any of the display box controls, you had to place a script as the control’s last argument. For example:
The following two code examples produce identical windows using the deprecated Dialog() method and the preferred New Window() with the Modal option. New Window provides more display options and better control over the content and functions of the window.
Probably the greatest difference between Dialog() and New Window() is their difference in extracting values. Dialog() allows unloading values after the dialog is closed. For example:
dlg["rb"] = 3; // reports "c" selected
New Window() provides two methods for extracting variable values. By default, you must use individual <<Get expressions to retrieve the value for each variable in New Window() (see Extraction Method 2). To return the values within New Window() in the same manner as Dialog(), use the <<Return Results option (see Extraction Method 1).
To have a New Window script automatically return the results after clicking OK, include the <<Return Result option after <<Modal. For example:
If check boxes a and b are selected, the results for the Return Result option are:
To view the output results of the New Window() example, add a <<Get for each variable. To view the selection, add a Show line at the end of the script (without including the Return Result option):
See Modal and Non-Modal Windows for additional information on New Window() function and its objects. See the JSL Syntax Reference for syntax details.
Column Dialog, a variant of the deprecated Dialog function, lets you prompt for column selections from the current data table or contextual data table, which must already be open.
For each destination list, a Col List clause must be a direct argument of Column Dialog (not nested inside some other argument). An optional MaxCol(n) argument restricts the number of data columns that can be chosen to n. The resulting list contains the “name” list that is enclosed in parentheses. Lists are always returned, although they can sometimes be empty lists. You can include as many as twelve Col List clauses.
Other items permitted in the deprecated Dialog command are permitted in Column Dialog also, and have the same functionality. The OK, Cancel, and Remove buttons and the list of columns to choose from are both added automatically.
You can specify the minimum and maximum number of columns that are allowed in a column dialog box with the MinCol and MaxCol arguments. You can also specify the modeling type of the columns that are allowed to be selected (Ordinal, Nominal or Continuous). You can set the width of the list using Select List Width(pixels) argument. To set the width of the column list, use Width(pixels) inside the Col List() function.
In addition, use the Columns specification to pre-fill some column selections. For example:
Use EvalList to evaluate an entire list of assignments all at once:
Dialog and Column Dialog Constructors shows describes the display box constructors used in deprecated Dialog() and Column Dialog(). Note the following:
|
•
|
Both windows automatically include an OK button if no buttons are defined.
|
|
•
|
|
Dialog( contents of window )
|
Note: Deprecated in JMP 10.
|
|
|
Column Dialog( contents of window )
|
||
|
Available only for Column Dialog().
Creates a selection destination with a role button; the user’s choice are returned in a list item of the form var={choice 1, choice 2, …, choice n}.
You can specify the required data type of the column using Datatype(type). The choices for type are Numeric, Character, or Rowstate.
|
||
|
List Box in Dialog() allows only one argument (the list). To specify more arguments, include List Box in New Window().
|
||
|
Top-aligns and spaces the items in a horizontal row. Placing a pair of VLists within an HList produces a top-aligned, spaced pair of columns.
|
||
|
Left-aligns and spaces the items in a vertical column. Placing a pair of HLists within a VList produces a left-aligned, spaced pair of rows.
|
||
|
Draws an OK or a Cancel button. If OK is clicked, Button(1) is returned. If Cancel is clicked, Button(–1) is returned.
|
||
|
"string"
|
||
|
var=Edit Number( number )
var( Edit Number( number ) )
|
Produces an edit field for a number with number as the default value. When OK is clicked, the number entered in the field is assigned to the variable.
|
|
|
Produces an edit field for a string with string as the default value. You can also specify the minimum width of the box in pixels. The default width is 72 pixels. When OK is clicked, the text entered in the field is assigned to the variable.
|
||
|
Produces a vertical, left-justified list of radio buttons with the choices specified. The first choice is the default. When OK is clicked, the button that is selected is assigned to the variable. Choices must evaluate to quoted text strings.
|
||
|
When OK is clicked, a selected check box assigns 1 to the variable. A check box that is not selected assigns 0 to the variable.
|
||