Difference between revisions of "MsgBox"
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[category:User-interface functions]]
 
[[category:User-interface functions]]
 
[[Category:Doc Status C]] <!-- For Lumina use, do not change -->
 
[[Category:Doc Status C]] <!-- For Lumina use, do not change -->
 +
{{ReleaseBar}}
 
   
 
   
 
__TOC__
 
__TOC__
  
−
==MsgBox(msg, ''buttons, title'')==
+
==MsgBox(msg, ''buttons, title{{Release|5.2||, url, urlText, checkboxText, checked, url2, url2Text}}'') ==
 
[[MsgBox]] displays a standard popup modal dialog box with a user-supplied message «msg» when it is evaluated.  It pauses evaluation until the user presses a button on the message box.  If the user presses '''Cancel''', it stops further computation.  
 
[[MsgBox]] displays a standard popup modal dialog box with a user-supplied message «msg» when it is evaluated.  It pauses evaluation until the user presses a button on the message box.  If the user presses '''Cancel''', it stops further computation.  
  
Line 11: Line 12:
 
You can use [[MsgBox]] to show the model user a message, warning, or error during evaluation. A common use is for model debugging to show intermediate values while a complex algorithm is in progress.
 
You can use [[MsgBox]] to show the model user a message, warning, or error during evaluation. A common use is for model debugging to show intermediate values while a complex algorithm is in progress.
  
−
===Declaration===
+
{{Release|5.2||(''New to [[Analytica 5.2]]'') Optionally, you can include one or two URL links in the lower-left corner, and a checkbox on the message dialog. }}
−
:MsgBox(message ; buttons: optional scalar; title: optional text)
 
  
 
===Example===
 
===Example===
Line 29: Line 29:
 
* <code>4</code> = '''Yes''' and '''No'''
 
* <code>4</code> = '''Yes''' and '''No'''
 
* <code>5</code> = '''Retry''' and '''Cancel'''
 
* <code>5</code> = '''Retry''' and '''Cancel'''
 +
* <code>6</code> = '''Yes''', '''No''' and '''No to all'''
 +
* <code>7</code> = '''Yes''', '''No''', '''No to all''' and '''Cancel'''
 +
  
 
The icon can also be changed by adding the following to the buttons parameter:
 
The icon can also be changed by adding the following to the buttons parameter:
Line 44: Line 47:
 
* <code>6</code> = '''Yes'''
 
* <code>6</code> = '''Yes'''
 
* <code>7</code> = '''No'''
 
* <code>7</code> = '''No'''
 +
* <code>10007</code> = '''No to all'''
  
 
In [[ADE]], [[MsgBox]] displays nothing and returns <code>0</code>.
 
In [[ADE]], [[MsgBox]] displays nothing and returns <code>0</code>.
Line 51: Line 55:
 
===Title===
 
===Title===
 
The optional «title» parameter can be used to provide a title for the message box . If no title is specified, the title defaults to the title of the calling variable or function.
 
The optional «title» parameter can be used to provide a title for the message box . If no title is specified, the title defaults to the title of the calling variable or function.
 +
 +
===Url and UrlText===
 +
{{Release|5.2||(''Requires [[Analytica 5.2]] or later)
 +
If «url» is specified, a hyperlink appears in the lower-left corner of the dialog, with the «urlText», or labeled as '''More Information''' if «urlText» is not specified.
 +
 +
You can show two links by also specifying «url2», and optionally «url2Text».
 +
 +
Your URLS should start with "https://" or "http://".
 +
 +
URL information is not currently passed to ADE, so the links won't appear if run on ACP.
 +
}}{{Release||5.1|This feature is not available in this release -- requires [[Analytica 5.2]].}}
 +
=== CheckboxText and checked ===
 +
{{Release|5.2||(''Requires [[Analytica 5.2]] or later)
 +
When you set «checkboxText», a checkbox appears at the bottom of the dialog. «checked» specifies whether it is checked initially or not. When you use a checkbox, the checkbox state is returned as a second return value, so you need to capture this using, e.g.,
 +
 +
<code>
 +
:[[Local]] ( button, checkState ) {{eq}} [[MsgBox]]( "Do you want to run the long simulation?", button: /*Y-N-Cancel*/ 3,
 +
:::::checkboxText:"Enable logging during simulation", checked: True );
 +
:...
 +
</code>
 +
}}{{Release||5.1|This feature is not available in this release -- requires [[Analytica 5.2]].}}
  
 
== Details and more examples ==
 
== Details and more examples ==
−
 
 
[[MsgBox]] does not [[Array abstraction|array abstract]] over its first parameter.  Instead, it attempts to display the entire parameter using the current [[tableType]] system variable format with the number format of the variable containing the call.  Atomic text strings or numbers appear as such, but arrays appear in a format such as:
 
[[MsgBox]] does not [[Array abstraction|array abstract]] over its first parameter.  Instead, it attempts to display the entire parameter using the current [[tableType]] system variable format with the number format of the variable containing the call.  Atomic text strings or numbers appear as such, but arrays appear in a format such as:
 
:<code>Array(Time, [-121.1M, -75.33M, -12.41M, 62.06M, 62.06M, 1.594M, -58.87M, -119.3M])</code>
 
:<code>Array(Time, [-121.1M, -75.33M, -12.41M, 62.06M, 62.06M, 1.594M, -58.87M, -119.3M])</code>
−
 
  
 
'''Example:''' This example provides a peek at the result before returning it.
 
'''Example:''' This example provides a peek at the result before returning it.
Line 62: Line 85:
 
:<code>MsgBox(v);</code>
 
:<code>MsgBox(v);</code>
 
:<code>v</code>
 
:<code>v</code>
 +
 +
== From ADE ==
 +
When evaluated from within the [[ADE|Analytica Decision Engine (ADE)]], it calls [[IAdeUICallbacks::MsgBox]]( ), and from within that callback the parent application has an opportunity to display a message box to the end-user and to provide the return value. The parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). When the parent application has not registered a callback object, it returns 0 without displaying any message box.
  
 
==See Also==
 
==See Also==
 +
* [[Media:DiagramOpenMsgBox.ana]]
 +
* [[Dialog Functions]]: Functions that create dialogs
 +
* [[AskMsgText]]
 +
* [[AskMsgNumber]]
 +
* [[AskMsgChoice]]
 +
* [[ShowProgressBar]]
 +
* [[Buttons]]
 
* [[Creating Interfaces for End Users]]
 
* [[Creating Interfaces for End Users]]
−
* [[Buttons]]
 

Latest revision as of 19:50, 11 March 2022



Release:

4.6  •  5.0  •  5.1  •  5.2  •  5.3  •  5.4  •  6.0  •  6.1  •  6.2  •  6.3  •  6.4  •  6.5


MsgBox(msg, buttons, title, url, urlText, checkboxText, checked, url2, url2Text)

MsgBox displays a standard popup modal dialog box with a user-supplied message «msg» when it is evaluated. It pauses evaluation until the user presses a button on the message box. If the user presses Cancel, it stops further computation.

By default, the message box will show buttons OK and Cancel, and title of the dialog is the identifier of the Variable (or Function) that calls MsgBox().

You can use MsgBox to show the model user a message, warning, or error during evaluation. A common use is for model debugging to show intermediate values while a complex algorithm is in progress.

(New to Analytica 5.2) Optionally, you can include one or two URL links in the lower-left corner, and a checkbox on the message dialog.

Example

Variable Profit := Array(Time, [-121.1M, -75.33M, -12.41M, 62.06M, 62.06M, 1.594M, -58.87M, -119.3M])
MsgBox(Profit) →
MsgBoxExample.jpg

Optional parameters

Buttons

The optional «buttons» parameter can be used to control which buttons are displayed, as follows:

  • 0 = OK only
  • 1 = OK and Cancel [Default]
  • 2 = Abort, Retry and Ignore
  • 3 = Yes, No and Cancel
  • 4 = Yes and No
  • 5 = Retry and Cancel
  • 6 = Yes, No and No to all
  • 7 = Yes, No, No to all and Cancel


The icon can also be changed by adding the following to the buttons parameter:

  • 16 = Critical
  • 32 = Question
  • 48 = Exclamation
  • 64 = Information

The return value indicates which button was pressed, as follows:

  • 1 = OK
  • 2 = Cancel
  • 3 = Abort
  • 4 = Retry
  • 5 = Ignore
  • 6 = Yes
  • 7 = No
  • 10007 = No to all

In ADE, MsgBox displays nothing and returns 0.

If a user presses Cancel, the current computation aborts.

Title

The optional «title» parameter can be used to provide a title for the message box . If no title is specified, the title defaults to the title of the calling variable or function.

Url and UrlText

(Requires Analytica 5.2 or later) If «url» is specified, a hyperlink appears in the lower-left corner of the dialog, with the «urlText», or labeled as More Information if «urlText» is not specified.

You can show two links by also specifying «url2», and optionally «url2Text».

Your URLS should start with "https://" or "http://".

URL information is not currently passed to ADE, so the links won't appear if run on ACP.

CheckboxText and checked

(Requires Analytica 5.2 or later) When you set «checkboxText», a checkbox appears at the bottom of the dialog. «checked» specifies whether it is checked initially or not. When you use a checkbox, the checkbox state is returned as a second return value, so you need to capture this using, e.g.,

Local ( button, checkState ) := MsgBox( "Do you want to run the long simulation?", button: /*Y-N-Cancel*/ 3,
checkboxText:"Enable logging during simulation", checked: True );
...

Details and more examples

MsgBox does not array abstract over its first parameter. Instead, it attempts to display the entire parameter using the current tableType system variable format with the number format of the variable containing the call. Atomic text strings or numbers appear as such, but arrays appear in a format such as:

Array(Time, [-121.1M, -75.33M, -12.41M, 62.06M, 62.06M, 1.594M, -58.87M, -119.3M])

Example: This example provides a peek at the result before returning it.

var v := Sales_revenue - Cost;
MsgBox(v);
v

From ADE

When evaluated from within the Analytica Decision Engine (ADE), it calls IAdeUICallbacks::MsgBox( ), and from within that callback the parent application has an opportunity to display a message box to the end-user and to provide the return value. The parent application must have previously registered the callback with ADE using CAEngine::SetCallbackObject( ). When the parent application has not registered a callback object, it returns 0 without displaying any message box.

See Also

Comments


You are not allowed to post comments.