Dialog Functions

Analytica User GuideProcedural ProgrammingDialog Functions

Dialog functions display dialog boxes to show special information, warnings, or error messages, or to request information from the user. They include MsgBox to display a message, AskMsgNumber to ask for a number, AskMsgChoice to ask the user to select an option from a menu, AskMsgText to ask the user to enter text, which could be a password, and ShowProgressBar to show a progress bar during a long computation.

Dialogs are modal — meaning that Analytica pauses evaluation while showing the dialog until you close the dialog (except ShowProgressBar which continues evaluation while showing the progress bar). If you click the Cancel button, it stops further evaluation — as if you pressed Control+. (Control+period).

Dialog functions display their dialog when evaluated. If the definition of a variable A calls a dialog function, it will display the dialog when it evaluates A. If it evaluates A in mid and prob mode, it displays the dialog each time. It does not display the dialog again until it evaluates A again — for example, because one of its inputs changes.

MsgBox(message, buttons, title)

Displays a dialog with the text «message», a set of «buttons» and an icon (according to numerical codes below), with «title» in the dialog header bar. Analytica pauses until the user clicks a button. If the user clicks the Cancel button, it stops evaluation. Otherwise it returns a number, depending on which button the user presses (see below).

The optional buttons parameter is a number that controls which buttons to display, as follows:

0 = OK only

1 = OK and Cancel (the default if the «buttons» parameter is omitted)

2 = Abort, Retry, and Ignore

3 = Yes, No, and Cancel

4 = Yes and No

5 = Retry and Cancel

To display an icon in the dialog, add one of these numbers to the «buttons» parameter:

16 = Critical (white X on red circle)

32 = Question

48 = Exclamation

64 = Information

MsgBox() returns a number depending on which button the user presses:

1 = OK

2 = Cancel (stops any further evaluation)

3 = Abort

4 = Retry

5 = Ignore

6 = Yes

7 = No

Here are some examples.

Msgbox('OK, I'm done now.', 0 + 64, 'Information') →

Msgbox('Uh uh! Looks like trouble!', 5 + 16, 'Disaster') →

Msgbox('Do you really mean that?', 3 + 32, 'Critical question') →

Msgbox('This could be a real problem!', 2 + 48, 'Critical question') →

Error(message)

Displays an evaluation error in a dialog mentioning the variable whose definition calls this function, showing the «message» text:

Variable Xyz := Error('There seems to be some kind of problem')

Xyz →

If you click Yes, it opens the definition of the variable or function whose definition (or Check attribute) calls Error() in edit mode (if the model is editable). If you click No or Cancel, it stops evaluation.

Error in check

If you call Error() in a Check attribute, it shows the error message when the check fails instead of the default check error message, letting you tailor the message.

AskMsgChoice(question, title, optionList, default, showAll, comboBox)

Opens a dialog displaying «question» text with a choice drop down control where the user can select an answer from a list. The «optionList» parameter is a list or 1-D array of selections, and «default» is initial selection. The selected item is returned as the result.

When «showAll» is True, then an «All» option is also included, and if selected then the entire «optionList» is returned. When «comboBox» is specified as True, then a combo box control is displayed rather than a choice list. In a combo box, the user is free to enter his own text, but the «optionList» provides suggestions. See AskMsgChoice().

Example:

AskMsgChoice("Please rate", "Survey", ["Loved","Liked", "Neutral", "Disliked", "Hated"])

AskMsgNumber(question, title, default)

Displays a dialog showing «question» with «title», if given. It shows a field for user to enter a number, containing «default» number if given. When the user enters a number into the dialog, and clicks OK, it returns the number. See AskMsgNumber().

AskMsgText(question, title, maxText, default, password)

Opens a dialog displaying «question» text with a field for the user to provide an answer, which it returns as text.

If you specify «title» text it displays that in the title bar of the dialog. If you specify «maxText» as a number, it will accept only that many characters. If you specify «default» text, it displays that as the default answer. If you set «password» to True, the characters typed are hidden as they are typed. See AskMsgText().

Example:

AskMsgText("Enter your model access key", title: "License Entry", maxText: 15)

ShowProgressBar(title, text, p)

Displays a dialog with the «title» in title bar, a «text» message and a progress bar showing fraction «p» of progress along the bar. The dialog appears the first time you call it with p < 1. As long as 0 <= p < 1, it shows a Cancel button, and continues evaluation. If you click Cancel, it stops further computation, as if the user had pressed Control+. (Control+period). If p = 1, it shows the OK button and stops further computation. If you click OK, it closes the dialog. The dialog also closes if called with p > 1 or when the computation completes. See ShowProgressBar().

Declaration:

ShowProgressBar(title, text: Text atomic; p: number atomic)

Example:

In this example:

   VAR xOrig := X;
   VAR result :=
      FOR n[] := @Scenario DO (
         ShowProgressBar("Progress", "Computing Across All Scenarios", (n - 1)/Size(Scenario));
         WhatIf(Y, X, xOrig[@Scenario = n]))
      ;
   ShowProgressBar("Progress", "Done", 1);
   result

See Also

• MsgBox
• Error
• Button
• AskMsgChoice
• AskMsgNumber
• AskMsgText
• ShowProgressBar
• Category: User-interface functions
• User Interfaces for End Users
• Analytica windows and dialogs

Handles to ObjectsDialog FunctionsOther Procedural Functions