Forecasting & Planning Solutions

Home

Products

Solutions

Services

Customers

Partners

Company

Applying science to business management

dialog

Format: dialog( template, buttons, values, title, fill, envelope )
_dialog( template, buttons, values, title, fill, envelope )

Arguments: (text) template Optional block of text describing the format of the input screen; default = contents of the node's Form window (dialogtemplate)

(int) buttons Optional code indicating the type of buttons displayed:
BTN_DEFAULT = OK/Cancel or
Back/Next/Cancel (default)
BTN_YESNOCANCEL = Yes/No/Cancel or
Back/Yes/No/Cancel
BTN_NONE = No buttons
other = see below

[any] values Optional list of default values for each input field; default = null

(text) title Optional window title; default = ""

(text) fill Optional character used to define input fields; default = "^"

(text) envelope Optional name of the file containing the HTML form envelope (Include only the file name, not the full path. The file must reside in the same directory as the application file or in the Envelopes directory.)

Returns: [any] List of values for each input field in the order specified by the template argument

Description: Dialog provides for user input and output using a local dialog box or remote HTML form. This is the base function used by all other user input and output functions such as say, asknumber, asktext, etc. That is, all of these functions are soft primitives defined using dialog. Look in the file Default IO.dsb to see the exact definitions used by these functions.

There are two versions of this primitive, dialog and _dialog. Both versions behave in the same manner except that dialog records activity in a history file while _dialog does not. You should use dialog in all cases except those where you explicitly write your own data to the history file.

The layout of your input form is defined in the template argument. This argument contains all text that will appear in the form plus a string of fill characters (e.g., ^^^^) wherever an input field should appear.

The values argument is a list of default values for each input field in template when read from left to right and top to bottom.

If Yes/No/Cancel buttons are used, dialog will return only true if Yes is chosen, false if No is chosen, and will terminate the script if Cancel is chosen. Of OK/Cancel buttons are used (the default) a list of values corresponding to each input field is returned. You can pick particular values out of this list using the List Element operator x[y].

When Logical Look-Ahead is active, this function is gated to prevent unnecessary user input in expressions using Logical And/Logical Or.

Forms can contain eight input field types: single-line text boxes, scrolling text boxes, check boxes, radio buttons, drop-down menus, list boxes, push buttons, and file requests. You also can include tables, screen images, hidden fields, and custom submit buttons. Each of these form elements is described below.

Single-Line Text Boxes:

^code=value;^^^^^^^^^^^

A text box is created by entering a series of fill characters (e.g., ^^^^^^^) in the template where the text box is to appear. The length of the box is determined by the length of the string of fill characters.

By default, a text box returns exactly the same text that the user entered. However, you can validate the user's entry and convert this text to a different type by using a type code after the first fill character. For example, ^(int)^^^^^^^^ will cause the user’s entry to be verified and converted to an integer. If the user's entry is not valid, an error message is displayed and the form 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 exists

(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

If you capitalize the first letter in a type code (e.g., (Chr) rather than (chr)), the user will be required to enter a value in the field before proceeding.

The initial text placed in the text box can be specified using the values argument or by placing =value; after the type code. Value must be constructed as a valid DScript command and must be terminated by a semicolon.

Example:

N1: ^(Real)=2+3;^^^
N2: ^(Real)^^^^^^^^
C1: ^(Chr)="Text";^^^^^^

Scrolling Text Boxes:

^EDIT width height=value;

A scrolling text box is created by entering a single fill character followed by EDIT and the box size.

The width and height arguments should each be followed by a c, r, or p unit of measure character. Use c to represent columns, r to represent rows, and p to represent pixels. For example, ^EDIT 40c 3r will create a scrolling text box that is 40 columns wide and 3 rows tall.

The initial text placed in the text box can be specified using the values argument or by placing =value; after the height argument.

Example:

Notes: ^EDIT 10c 3r
Notes: ^EDIT 10c 3r="Text";

Check Boxes:

^{option name}=value;

A check box is created by placing a single fill character followed by the check box name enclosed in braces { }. The initial check box state can be set using the values argument or by placing =1; or =0; after the trailing brace. Check boxes always return either true for false where true indicates that the box is checked.

Example:

^{Option 1}
^{Option 2}=1;
^{Option 3}

Radio Buttons:

^*option name*=value;

A radio button is created by placing a single fill character followed by the radio button name enclosed in stars * *. A series of radio buttons is considered to be in a single group (i.e., only one button in the group can be chosen at a time) if there are no other fields separating the buttons. The initial radio button state can be set using the values argument or by placing =1; or =0; after the trailing star. Radio buttons return either true for false where true indicates that the option is chosen.

Example:

^*Option 1*
^*Option 2*=1;
^*Option 3*

Drop-Down Menus:

^MENU=[index,selectionlist];

To create a drop-down menu, enter a single fill character followed by MENU and an optional list of input values. For example, ^MENU=[1,["Option1","Option2","Option3"]]; will display a menu with three items (Option 1, Option 2, and Option 3) where the first item is initially selected.

Drop-down menus return a list in the form [Index,SelectionList] where Index is the number of the item the user selected. SelectionList remains unchanged. Use the function selecteditem to extract the user's selection from the result list.

Example:

^MENU=[1,[
  "Option1",
  "Option2",
  "Option3"
]];

List Boxes:

^SELECT height=[index,selectionlist];

A list box behaves just like a drop-down menu except that the box is taller than one row so that several items can be displayed at a time. You create a list box by entering a single fill character followed by SELECT and an optional list of input values. For example, ^SELECT 5r=[3,1..10]; will display a box that is five rows high and contain 10 items (the number from 1 to 10) where the third item is initially selected.

List boxes return a list in the form [Index,SelectionList] where Index is the number of the item the user selected. SelectionList remains unchanged. Use the function selecteditem to extract the user's selection from the result list.

Example:

^SELECT 5r=[3,1..10];

Push Buttons:

^/ button name /

A push button looks and behaves just like one of the standard submit buttons with one exception. If a user submits a form using a push button, the button name is appended to the result list. You can determine which button a user used to submit a form simply by looking at the last entry in the result list. Push buttons are created by placing a single fill character followed by the button name enclosed in forward slash characters.

Example:

^/Help/

File Requests:

^GETFILE^^^^^^^^^^

This input filed is used to upload the contents of a file on the user's computer. The field is displayed as a single-line text box followed by a Browse button. The user is prompted to enter the name of a file in the text box or use the Browse button to choose. This element returns the contents of the chosen file.

If you use this input field in an HTML form, you must change the envelope to send data using multipart encoding. You do this by replacing the line

with

Example:

^GETFILE^^^^^^^^^^

Tables:

^tcolumn 1 text ^tcolumn 2 text ...^T

Tables are useful for vertically aligning input fields and data items. A table is created simply by placing a ^t in front of each item in the table. For example,

^tCell1 ^tCell2
^tCell3 ^tCell4^T

Note that ^t is not the same as a tab in that a ^t code must be placed in front of the first item in each row as well as between items in each column.

To end a table, insert a blank line or place an upper case ^T after the last table item. There is no special code required to begin a table. The table simply begins with the first occurrence of ^t.

Example:

^tName: ^t^(Chr)^^^^^^^^^^
^tAddress: ^t^(Chr)^^^^^^^^^^
^tPhone: ^t^(chr)^^^^^^^^^^ ^T

Screen Images:

^SHOW sheetname width height

In addition to the standard input controls, a form can contain images of any tree, graph, or table in your script. Sheetname is the name of the sheet you wish to display. Width and height define the size of the image.

Example:

^SHOW Graph1 40c 10r

Hidden Fields:

A hidden field is used to insert a dummy value in the output list. This allows you to space values in the result list to facilitate processing of the result. A hidden field acts just like an input field except that it does not show up in the output form. Hidden fields return an empty string "" in the result list.

Custom Submit Buttons:

In addition to the four style codes used in the buttons argument to specify which submit buttons are displayed, you can create a custom style code that individually specifies the buttons you want to include. Create this code by adding together code values for each button you want to include. For example, use the code BTN_BACK+BTN_DONE to include Back and Done buttons.

Button Code Value

OK BTN_OK 16

Cancel BTN_CANCEL 32

Yes BTN_YES 64

No BTN_NO 128

Help BTN_HELP 256

Finish BTN_FINISH 512

Back BTN_BACK 1024

Next BTN_NEXT 2048

Done BTN_DONE 4096

Special Characters:

Use the following codes in template to represent special characters:

Character Code

& &

< <

> >

fill &fill;

Include Fields:

<%command%>

If you use the Form window to contain the template (dialogtemplate), then you can enter fields in the template that are evaluated and replaced at runtime. For example, <%date%> will insert the current date.