Dialog - Message
Declaration
<AMSHOWDIALOG WINDOWTITLE="text" BUTTONS="text (options)" ONFIRSTBUTTONCLICK="text (options)" ONFIRSTBUTTONCLICKTASK="text" ONSECONDBUTTONCLICK="text (options)" ONTHIRDBUTTONCLICK="text (options)" RESULTVARIABLE="text" COUNTDOWNDELAY="number" XPOS="number" YPOS="number" ICON="text (options)">text (message to display) </AMSHOWDIALOG>
Description: Displays a message box during task execution using the settings specified. A message box is useful when notification and/or user input is required in a task.
Practical Usage
Commonly used to alert the user or provide informative feedback about the task during runtime. Can also be used to pause task execution until interactivity occurs (e.g., user selects the OK button to continue execution).
General Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Message to display |
Text |
Yes |
(Empty) |
MESSAGETEXT="Variable content is %VARNAME%" |
The message to be displayed during runtime. This can be instructions, feedback, process results or any important information that should be expressed to the use. |
Title of the message box |
Text |
No |
(Empty) |
WINDOWTITLE="Message" |
The title that should appear in the title bar of the message box. |
Bring message to front of all other windows |
Yes/No |
No |
Yes |
WINDOWINFRONT="NO" |
If set to YES, specifies that the message box will appear in front of all other open windows. This parameter is set to YES by default. |
Buttons Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Buttons contained in the message box |
Text (options) |
No |
OK |
|
Indicates the button or collection of buttons that should be displayed on the message box. The available options are:
|
Button selected by default |
Number |
No |
0 |
DEFAULTBUTTON=2 |
The number associated to the button (from left to right) that should be selected by default. The number specified must be the same as or lower than the total number of buttons on the message box. For example, if the button configuration selected is Abort, Retry, Ignore, the corresponding number would be Abort = first button (1), Retry = second button (2) and Ignore = third button (3). |
Pause task execution until a button is clicked |
Yes/No |
No |
Yes |
MODAL="NO" |
If set to YES, task execution will suspend at the message dialog step until a button is selected. This parameter is set to YES by default. |
On first button |
Text (Options) |
No |
Continue |
|
The action to perform when the first (from left to right) button is clicked. The available options are:
|
On second button |
Text (Options) |
No |
Continue |
|
The action to perform when the second (from left to right) button is clicked. The available options are:
|
Task to Start |
Text |
Yes if Start a task option is selected |
(Empty) |
|
If the first, second or third button is set to start a task if clicked, specifies the path and filename of the task that should start. Click the folder icon to navigate to the desired task (.aml) file. |
Variable name |
Text |
Yes if Set a variable option is selected |
(Empty) |
|
If the first, second or third button is supposed to set a variable if clicked, specifies the name of an existing variable to set. |
Variable value |
Text |
Yes if Set a variable option is selected |
(Empty) |
|
If the first, second or third button is supposed to set a variable if clicked, specifies the value to set the variable to. |
Populate variable with return code |
Text |
No |
(Empty) |
RESULTVARIABLE="theVarName" |
The name of an existing variable to populate with the return code. |
Automatically select the default button |
Number |
No |
(Empty) |
COUNTDOWNDELAY="10" |
The amount of time that should elapse before the default button should be selected. |
Measure |
Text (options) |
No |
minutes |
MEASURE="minutes" |
The time measure that corresponds to the number entered in the Automatically select the default button parameter. The available options are:
|
Advanced Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Position |
Text (Options) |
No |
Center of screen |
|
The screen position in which to display the message dialog. The available options are:
|
Window coordinates (X) |
Number |
Yes if position is set to custom location |
(Empty) |
XPOS="55" |
The X (horizontal) coordinates of the position that the upper left corner of the message dialog should be displayed on the screen. To capture X coordinates using your mouse, enable the Capture mouse position (press Space to capture) option, move the mouse cursor to the desired location on the screen and press Space on your keyboard to capture the position. This parameter is available only if the Position parameter is set to Custom location. |
Window coordinates (Y) |
Number |
Yes if position is set to custom location |
(Empty) |
YPOS="55" |
The Y (vertical) coordinates of the position that the upper left corner of the message dialog should be displayed on the screen. To capture Y coordinates using your mouse, enable the Capture mouse position (press Space to capture) option, move the mouse cursor to the desired location on the screen and press Space on your keyboard to capture the position. This parameter is available only if the Position parameter is set to Custom location. |
Dialog title icon |
Text (Options) |
No |
(Empty) |
|
Specifies the icon that should be displayed next to the title. This helps to determine what type of message is being displayed. The available options are:
|
Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.
Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)
On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)
Examples
The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.
Sample Task 1
A simple task that saves the text entered in an input box to a variable and later displays it in a message box.
<AMVARIABLE NAME="textEntered"></AMVARIABLE> <AMSHOWDIALOG ACTIVITY="input" RESULTVARIABLE="textEntered" WINDOWTITLE="ENTER TEXT">Please enter some text here.</AMSHOWDIALOG> <AMSHOWDIALOG WINDOWTITLE="TEXT ENTERED"> The text that was entered: %textEntered%</AMSHOWDIALOG> |
Sample Task 2
Opens a message dialog that displays the version of your installation.
<AMSHOWDIALOG WINDOWTITLE="Version" BUTTONS="yes_no_cancel" ONSECONDBUTTONCLICK="stop" ONTHIRDBUTTONCLICK="fail" COUNTDOWNDELAY="10" ICON="information"> %GetAutoMateVersion()%</AMSHOWDIALOG> |
Sample Task 3
A more complex task that demonstrates use of the Input Dialog and Message Dialog. Also demonstrates use of variables, BASIC Script, IF/End if activities and expressions.
<AMVARIABLE NAME="theanswer" DESCRIPTION=""></AMVARIABLE> <AMSCRIPT>Function SquareNumber(thenum) SquareNumber = thenum * thenum End Function</AMSCRIPT> <AMSHOWDIALOG ACTIVITY="input" RESULTVARIABLE="theanswer"> What number would you like to square?</AMSHOWDIALOG> <AMIF EXPRESSION="IsNumeric(theanswer) = true"> <AMSHOWDIALOG>The number %theanswer% squared is %SquareNumber(theanswer)%</AMSHOWDIALOG> <AMELSE /> <AMSHOWDIALOG>The text "%theanswer%" is not a valid number. Please re-run and enter a valid number.</AMSHOWDIALOG> </AMIF> |