Difference between revisions of "Dialog Functions"

m
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Category: Analytica User Guide]]
 
[[Category: Analytica User Guide]]
<breadcrumbs> Analytica User Guide > {{PAGENAME}}</breadcrumbs><br />
+
[[Category: Windows and dialogs]]
 +
[[Category: User-interface functions]]
 +
<breadcrumbs> Analytica User Guide > Procedural Programming > {{PAGENAME}}</breadcrumbs>
  
Dialog functions display dialog boxes to give special information, warnings, or error messages, or to request information from the user. Dialogs are '''''modal''''' — meaning that Analytica pauses evaluation while showing the dialog until the user closes the dialog ('''ShowProgressBar''' is an exception in that it continues evaluation while it displays the progress bar). If the user clicks the '''Cancel''' button, it stops further evaluation — as if the user pressed ''Control+.'' ('''Control+period''').
+
Dialog functions display dialog boxes to show special information, warnings, or error messages, or to request information from the user.  
 +
They include [[#MsgBox(message, ''buttons, title'')|MsgBox]] to display a message, [[#AskMsgNumber(question, ''title, default'')|AskMsgNumber]] to ask for a number, [[#AskMsgChoice(question, title, optionList, default, showAll, comboBox)|AskMsgChoice]] to ask the user to select an option from a menu, [[#AskMsgText(question, ''title, maxText, default, password'')|AskMsgText]] to ask the user to enter text, which could be a password, and [[#ShowProgressBar(title, text, p)|ShowProgressBar]] to show a progress bar during a long computation.
 +
 
 +
__TOC__
 +
 
 +
 
 +
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 <code>A</code> calls a dialog function, it will display the dialog when it evaluates <code>A</code>. If it evaluates <code>A</code> in mid and prob mode, it displays the dialog each time. It does not display the dialog again until it evaluates <code>A</code> again — for example, because one of its inputs changes.
 
Dialog functions display their dialog when evaluated. If the definition of a variable <code>A</code> calls a dialog function, it will display the dialog when it evaluates <code>A</code>. If it evaluates <code>A</code> in mid and prob mode, it displays the dialog each time. It does not display the dialog again until it evaluates <code>A</code> again — for example, because one of its inputs changes.
Line 8: Line 16:
 
==MsgBox(message, ''buttons, title'')==
 
==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).
+
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:
 
The optional buttons parameter is a number that controls which buttons to display, as follows:
  
:0 = OK only
+
:<code>0</code> = '''OK''' only
:1 = OK and Cancel (the default if the '''buttons''' parameter is omitted)
+
:<code>1</code> = '''OK''' and '''Cancel''' (the default if the «buttons» parameter is omitted)
:2 = Abort, Retry, and Ignore
+
:<code>2</code> = '''Abort''', '''Retry''', and '''Ignore'''
:3 = Yes, No, and Cancel
+
:<code>3</code> = '''Yes''', '''No''', and '''Cancel'''
:4 = Yes and No
+
:<code>4</code> = '''Yes''' and '''No'''
:5 = Retry and Cancel
+
:<code>5</code> = '''Retry''' and '''Cancel'''
  
To display an icon in the dialog, add one of these numbers to the '''buttons''' parameter:
+
To display an icon in the dialog, add one of these numbers to the «buttons» parameter:
  
:16 = Critical (white X on red circle)
+
:<code>16</code> = Critical (white X on red circle)
:32 = Question
+
:<code>32</code> = Question
:48 = Exclamation
+
:<code>48</code> = Exclamation
:64 = Information
+
:<code>64</code> = Information
  
'''MsgBox''' returns a number depending on which button the user presses:
+
[[MsgBox]]() returns a number depending on which button the user presses:
  
:1 = OK
+
:<code>1</code> = '''OK'''
:2 = Cancel (stops any further evaluation)
+
:<code>2</code> = '''Cancel''' (stops any further evaluation)
:3 = Abort
+
:<code>3</code> = '''Abort'''
:4 = Retry
+
:<code>4</code> = '''Retry'''
:5 = Ignore
+
:<code>5</code> = '''Ignore'''
:6 = Yes
+
:<code>6</code> = '''Yes'''
:7 = No
+
:<code>7</code> = '''No'''
  
 
Here are some examples.
 
Here are some examples.
  
:<code>Msgbox('OK, I''m done now.', 0+64,'Information') ''</code>
+
:<code>Msgbox('OK, I'm done now.', 0 + 64, 'Information') &rarr;''</code>
  
:::[[File:msgbox1.png|150px]]
+
:[[File:msgbox1.png|150px]]
  
:<code>Msgbox('Uh uh! Looks like trouble!', 5+16, 'Disaster') </code>
+
:<code>Msgbox('Uh uh! Looks like trouble!', 5 + 16, 'Disaster') &rarr;</code>
  
:::[[File:msgbox2.png|250px]]
+
:[[File:msgbox2.png|200px]]
  
:<code>Msgbox('Do you really mean that?', 3+32, 'Critical question') </code>
+
:<code>Msgbox('Do you really mean that?', 3 + 32, 'Critical question') &rarr;</code>
  
:::[[File:msgbox3.png|250px]]
+
:[[File:msgbox3.png|250px]]
  
:<code>Msgbox('This could be a real problem!', 2+48, 'Critical question') </code>
+
:<code>Msgbox('This could be a real problem!', 2 + 48, 'Critical question') &rarr;</code>
  
:::[[File:msgbox4.png|250px]]
+
:[[File:msgbox4.png|250px]]
  
 
==Error(message)==
 
==Error(message)==
  
Displays an evaluation error in a dialog mentioning the variable whose definition calls this function, showing the '''message''' text:
+
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')  
+
::<code>Variable Xyz := Error('There seems to be some kind of problem')</code>
::Xyz
+
::<code>Xyz &rarr;</code>
  
:::[[File:msgbox5.png|300px]]
+
:[[File:msgbox5.png|300px]]
  
If you click '''Yes''', it opens the definition of the variable or function whose definition (or Check attribute) calls [http://wiki.analytica.com/index.php?title=Error Error]() in edit mode (if the model is editable). If you click '''No''' or '''Cancel''', it stops evaluation.
+
If you click '''Yes''', it opens the definition of the variable or function whose definition (or <code>Check</code> attribute) calls [[Error]]() in edit mode (if the model is editable). If you click '''No''' or '''Cancel''', it stops evaluation.
  
 
===Error in check===
 
===Error in check===
  
If you call [http://wiki.analytica.com/index.php?title=Error Error]() in a [http://wiki.analytica.com/index.php?title=Check_Attribute check attribute], it shows the error message when the check fails ''instead'' of the default check error message, letting you tailor the message.
+
If you call [[Error]]() in a [[Check_Attribute|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'')==
 
==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.
+
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 <code>showAll</code> is <code>true</code>, then an «All» option is also included, and if selected then the entire '''optionList''' is returned. When '''comboBox''' is specified as <code>true</code>, 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.
 
  
===Example===
+
When «showAll» is <code>True</code>, then an «All» option is also included, and if selected then the entire «optionList» is returned. When «comboBox» is specified as <code>True</code>, 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]]().
  
<code>AskMsgChoice("Please rate","Survey",["Loved","Liked", "Neutral", "Disliked", "Hated"])</code>
+
'''Example:'''
 +
:<code>AskMsgChoice("Please rate", "Survey", ["Loved","Liked", "Neutral", "Disliked", "Hated"])</code>
  
 
==AskMsgNumber(question, ''title, default'')==
 
==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.
+
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'')==
 
==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.
+
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.
+
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 <code>True</code>, the characters typed are hidden as they are typed. See [[AskMsgText]]().
  
===Example===
+
'''Example:'''
 
+
:<code>AskMsgText("Enter your model access key", title: "License Entry", maxText: 15)</code>
<code>AskMsgText("Enter your model access key", title: "License Entry", maxText: 15)</code>
 
  
 
==ShowProgressBar(title, text, p)==
 
==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 <code>p < 1</code>. As long as <code>0 <= p < 1</code>, 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 <code>p = 1</code>, it shows the '''OK''' button and stops further computation. If you click '''OK''', it closes the dialog. The dialog also closes if called with <code>p > 1</code> or when the computation completes. See [[ShowProgressBar]]().
  
Displays a dialog with the '''title''' in title bar, a '''text''' message and a progress bar showing fraction <code>p</code> of progress along the bar. The dialog appears the first time you call it with <code>p<1</code>. As long as <code>0<=p<1</code>, 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 <code>p=1</code>, it shows the '''OK''' button and stops further computation. If you click '''OK''', it closes the dialog. The dialog also closes if called with <code>p>1</code> or when the computation completes.
+
:[[File:msgbox6.png|250px]]
 
 
:::[[File:msgbox6.png|200px]]
 
 
 
===Declaration===
 
  
<code>ShowProgressBar(title, text: Text atomic; p: number atomic)</code>
+
'''Declaration:'''
 +
:<code>ShowProgressBar(title, text: Text atomic; p: number atomic)</code>
  
===Example===
+
'''Example:'''
  
 
In this example:
 
In this example:
 +
<pre style="background:white; border:white; margin-left: 1em;">
 +
  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
 +
</pre>
  
<code>VAR xOrig := X;</code>
+
== See Also ==
 
+
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
<code>VAR result :=</code>
+
* [[MsgBox]]
 
+
* [[Error]]
<code>FOR n[] := @Scenario DO (</code>
+
* [[Button]]
 
+
* [[AskMsgChoice]]
<code>ShowProgressBar("Progress", "Computing Across All Scenarios", (n-1)/Size(Scenario)); </code>
+
* [[AskMsgNumber]]
 
+
* [[AskMsgText]]
<code>WhatIf(Y, X, xOrig[@Scenario=n]));</code>
+
* [[ShowProgressBar]]
 
+
* [[:Category: User-interface functions]]
<code>ShowProgressBar("Progress", "Done", 1);</code>
+
* [[User Interfaces for End Users]]
 +
* [[Windows and dialogs|Analytica windows and dialogs]]
 +
</div>
  
<code>result</code>
 
  
 
<footer>Handles to Objects / {{PAGENAME}} / Other Procedural Functions</footer>
 
<footer>Handles to Objects / {{PAGENAME}} / Other Procedural Functions</footer>

Latest revision as of 17:27, 19 March 2022

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') →
Msgbox1.png
Msgbox('Uh uh! Looks like trouble!', 5 + 16, 'Disaster') →
Msgbox2.png
Msgbox('Do you really mean that?', 3 + 32, 'Critical question') →
Msgbox3.png
Msgbox('This could be a real problem!', 2 + 48, 'Critical question') →
Msgbox4.png

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 →
Msgbox5.png

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().

Msgbox6.png

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


Comments


You are not allowed to post comments.