Dialog Primitive

Dialog is used to create form-fill screens that accept user input in several fields at once. Dialog is the workhorse primitive for console I/O. In fact, asknumber, asktext, askyesno, and say are all implemented as soft primitives using dialog.

The use of dialog is best illustrated by example. Suppose that you want to modify the mortgage payment model to display a single dialog box that allows a user to enter all input values simultaneously. The dialog box might look like this:

The complete model using this dialog box is shown below:

In this model, values for the input quantities Price, Down Payment, Interest, and Term are all picked off a single list named Data using the definitions:

Price:=Data#1
Down Payment:=Data#2
Interest:=Data#3
Term:=Data#4

The node named Data contains all information entered by the user in the dialog box. Data is defined as follows:

Data:=dialog(Template,0,IF(Data!=null,Data,Default))

This node simply calls the dialog primitive, passing it information about the format of the dialog box.

The dialog primitive has the format

dialog( template, buttons, values, title, fill )

Template is a block of text describing the format of the input screen. Buttons is a code indicating the type of buttons displayed: 0 = OK/Cancel (default), 1 = Yes/No/Cancel. Values is a list of default values for each input field. Title is the text displayed on the window title bar. And, fill is the character used to define input fields.

The node named Template specifies the layout of the dialog box by including all text that is to appear in the dialog box plus a series of fill characters (^^^) wherever an input field is to appear.

Template:="\
House purchase price: ^(real)^^^
Down payment:         ^(real)^^^
Annual interest rate: ^(real)^^^
Loan term in years:   ^(int)^^^^
"

An edit box can be placed on the dialog box by entering a series of fill characters in the location where the edit box is to appear. The length of the box is determined by the length of the string of fill characters.

The value a user enters in an edit box is normally returned as a text string. You can specify that the text entered is to be evaluated just like a DecisionPro command by using a data type code in the fill character string. To do this, follow the first fill character by the appropriate code string. For example, ^(real)^^^^^^^^. DecisionPro will verify that the result of the user's entry is a single real number. If not, an error message is displayed and the dialog box will remain open until the user enters an appropriate value. The data type code can be any of the following values:

(chr) Character string

(pas) Password (same as character string but displayed as *****)

(any) Single number or text string

(int) Single integer (e.g., -1, 0, 5, 3e89)

(real) Single real number (e.g., -3.14, 5, 3e-89)

(num) Single complex or real number (e.g., 3.1+2.3I, 5)

(text) Single text string in quotes (e.g., "A text string")

(node) Name of a node that exists (without quotation marks)

(new) Name of a node that does not necessarily exist

(exe) Executable command with proper syntax

(bool) True, false, or any number; zero is considered to be false and all other numbers are true

[any] List of any type of elements

[int] List of integers

[real] List of real numbers

[num] List of complex or real numbers

[text] List of text strings

[node] List of node names expressed as text strings

In this case there are four edit boxes. The user is required to enter real numbers in the first three fields (real) and an integer (int) in the last. The position of the fill characters defines the position of the input fields. Use tabs before input fields to align fields vertically.

The second argument in the dialog primitive specifies the type of buttons on the dialog box. In this case, OK/Cancel buttons are used.

The third argument in the dialog primitive contains the default values displayed in each input field. This argument is defined as

IF(Data!=null,Data,Default)

This expression causes the dialog box to use the values defined in Default the first time the model is calculated and then use the previous results for all subsequent recalculations. Default is defined as follows:

Default:=["","",8%,30]

The value of Data will always be a list of four numbers. For example, the following entries

will result in this value for Data:

[150000,20000,0.08,30]

Adding a Drop-Down List

Suppose you want to replace the Loan term field in the dialog box with a drop-down list that displays the options 10, 20, and 30 years. The resulting dialog box will look like this:

When you click on the Loan term field, a list of options is exposed:

Drop-down lists are defined in the template specifier exactly like an edit box (by a series of fill characters). The field is distinguished as a drop-down list by supplying a list of default values in the values argument. The value for this field must be in the format [SelectedItemIndex,SelectionList]. SelectedItemIndex is the number of the item that is to be initially selected (1=first item in SelectionList). SelectionList is a list of all possible values from which the user can select. This dialog box control returns a list in the form [SelectedItemIndex,SelectionList] where SelectedItemIndex is the number of the item the user selected. SelectionList remains unchanged.

To include a drop-down list, first change the template's Loan term field from ^(int)^^^^ to ^^^^^^^^^^.

Template:="\
House purchase price: ^(real)^^^
Down payment:         ^(real)^^^
Annual interest rate: ^(real)^^^
Loan term in years:   ^^^^^^^^^^
"

Field codes, such as (int), apply to edit boxes only.

Next, modify the definition of Default as follows:

Default:=[
"",
"",
8%,
[3,[10,20,30]]
]

Note how the loan term value is structured. It consists of a list of two elements. The first element is the index of the option that is initially selected. The second element is a list of all options.

Finally, you must modify the definition for Term. For drop-down list elements, dialog returns the same list that was supplied as a default except that the first element is changed to indicate which item was selected. If a user selects 10, the fourth element in Data (Data#4) becomes [1,[10,20,30]]. If 20 is selected, the fourth element becomes [2,[10,20,30]]. And finally, if 30 is selected, the element becomes [3,[10,20,30]].

The definition for Term

Term:=Data#4#2#(Data#4#1)

simply extracts the element (10, 20, or 30) that is selected. The list of choices is referenced as Data#4#2. The index of the item in the list that is actually selected is referenced as Data#4#1. So, the complete expression Data#4#2#(Data#4#1) extracts the choice that is selected. You can simplify this by using selecteditem as follows:

Term:=selecteditem(Data#4)

Adding a Check Box

Next, assume you want to add a check box that will add 3% to the loan principal if checked. The resulting dialog box looks like this:

Check boxes are created by placing a single fill character followed by the check box name enclosed in braces { }. For example, ^{Add 3 Points}. Check boxes always return either true or false where true indicates that the box is checked.

To add a check box, first modify the dialog box template to include the field ^{Add 3 Points}.

Template:="\
House purchase price: ^(real)^^^
Down payment:         ^(real)^^^
Annual interest rate: ^(real)^^^
Loan term in years:   ^^^^^^^^^^
^{Add 3 Points}

"

Next, modify Default as follows:

Default:=[
"",
"",
8%,
[3,[10,20,30]],
true
]

Finally, modify the definition of Principal to add 3% (multiply by 1.03) if the box is checked. The value in the Data node corresponding to this field (Data#5) is either true or false depending on whether or not the field is checked.

Principal:=(Price-Down Payment)*IF(Data#5,1.03,1)