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>

Related Topics   

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 (for example, a user clicks an OK button to continue execution).

Parameters

General

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 selected, specifies that the message box will appear in front of all other open windows. This parameter is selected by default.

Buttons

Property Type Required Default Markup Description
Buttons contained in the message box Text (options) No OK
  • BUTTONS="ok"
  • BUTTONS="ok_cancel"
  • BUTTONS="abort_retry_ignore"
  • BUTTONS="retry_cancel"
  • BUTTONS="yes_no"
  • BUTTONS="yes_no_cancel"
 Indicates the button or collection of buttons that should be displayed on the message box. The available options are:
  • OK (Default) - The message box will contain an OK button only.
  • OK, Cancel - The message box will contain an OK and Cancel button.

  • Abort, Retry, Ignore - The message box will contain Abort, Retry and Ignore buttons.

  • Retry, Cancel - The message box will contain a Retry and Cancel button.

  • Yes, No - The message box will contain a Yes and No button.

  • Yes, No, Cancel - The message box will contain Yes, No and Cancel buttons.
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 selected, task execution will suspend at the message dialog step until a button is selected. This parameter is selected by default.
On first button Text (Options) No Continue

  • ONFIRSTBUTTONCLICK="continue"

  • ONFIRSTBUTTONCLICK="stop"

  • ONFIRSTBUTTONCLICK="fail"

  • ONFIRSTBUTTONCLICK="start_task"

  • ONFIRSTBUTTONCLICK="set_variable"

 The action to perform when the first (from left to right) button is clicked. The available options are:

  • Continue (default) - The task will continue to the next step.

  • Stop - The task will stop. No error is generated.

  • Fail - The task will fail with an error.  

  • Start a task - Another task will start.

  • Set a variable - The specified variable will be set to a particular value.
On second button Text (Options) No Continue

  • ONSECONDBUTTONCLICK="continue"

  • ONSECONDBUTTONCLICK="stop"

  • ONSECONDBUTTONCLICK="fail"

  • ONSECONDBUTTONCLICK="start_task"

  • ONSECONDBUTTONCLICK="set_variable"

 The action to perform when the second (from left to right) button is clicked. The available options are:
  • Continue (default) - The task will continue to the next step.
  • Stop - The task will stop. No error is generated.
  • Fail - The task will fail with an error.
  • Start a task - Another task will start.
  • Set a variable - The specified variable will be set to a particular value.
On third button Text (Options) No Continue

  • ONTHIRDBUTTONCLICK="continue"

  • ONTHIRDBUTTONCLICK="stop"

  • ONTHIRDBUTTONCLICK="fail"

  • ONTHIRDBUTTONCLICK="start_task"

  • ONTHIRDBUTTONCLICK="set_variable"

 The action to perform when the third (from left to right) button is clicked. The available options are:

  • Continue (default) - The task will continue to the next step.

  • Stop - The task will stop. No error is generated.

  • Fail - The task will fail with an error.

  • Start a task - Another task will start.

  • Set a variable - The specified variable will be set to a particular value.
Task to Start Text Yes if Start a task option is selected (Empty)
  • ONFIRSTBUTTONCLICKTASK="c:\folder\task.aml"
  • ONSECONDBUTTONCLICKTASK="c:\folder\task.aml"
  • ONTHIRDBUTTONCLICKTASK="c:\folder\task.aml"
 If the first, second or third button is set to start a task if clicked, specifies the path and file name 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)
  • ONFIRSTBUTTONCLICKVARNAME="varName"
  • ONSECONDBUTTONCLICKVARNAME="varName"
  • ONTHIRDBUTTONCLICKVARNAME="varName"
 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)
  • ONFIRSTBUTTONCLICKVARVALUE="newValue"
  • ONSECONDBUTTONCLICKVARVALUE="newValue"
  • ONTHIRDBUTTONCLICKVARVALUE="newValue"
 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:
  • milliseconds - The time os measured in milliseconds.
  • seconds - The time os measured in seconds.
  • minutes - The time os measured in minutes.
  • hours - The time os measured in hours.

Advanced

Property Type Required Default Markup Description
Position Text (Options) No Center of screen
  • POSITION="center"
  • POSITION="upper_left"
  • POSITION="lower_left"
  • POSITION="upper_right"
  • POSITION="lower_left"
  • POSITION="custom"
 The screen position in which to display the message dialog. The available options are:
  • Center of screen (default) - The input dialog will be displayed at the center of the screen.
  • Upper left corner of screen - The input dialog will be displayed at the upper left of the screen.
  • Lower left corner of screen - The input dialog will be displayed at the lower left of the screen.
  • Upper right corner of screen - The input dialog will be displayed at the upper right of the screen.
  • Lower right corner of screen - The input dialog will be displayed at the lower right of the screen.
  • Custom location - The input dialog will be displayed at the specified X,Y coordinates.
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)

  • ICON="none"

  • ICON="information"

  • ICON="exclamation"

  • ICON="question"

  • ICON="stop"

 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:

  • None (default) - No icon is displayed.

  • Information - An information icon is displayed.

  • Exclamation point - An exclamation point icon is displayed.

  • Question - A question mark icon is displayed.

  • Stop - A stop sign icon is displayed.

Description

Error Causes

On Error

Examples

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Example 1

A simple task that saves the text entered in an input box to a variable and later displays it in a message box.

Copy 
<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>

Example 2

Opens a message dialog that displays the version of your Automate Desktop installation.

Copy 
<AMSHOWDIALOG WINDOWTITLE="Product Version" BUTTONS="yes_no_cancel" ONSECONDBUTTONCLICK="stop" ONTHIRDBUTTONCLICK="fail" COUNTDOWNDELAY="10" ICON="information">%GetAutoMateVersion()%</AMSHOWDIALOG>

Example 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.

Copy 
<AMVARIABLE NAME="theanswer" DESCRIPTION="" VALUE="" />
<AMSCRIPT>Function SquareNumber(thenum)SquareNumber = thenum * thenumEnd Function</AMSCRIPT>
<AMSHOWDIALOG ACTIVITY="input" RESULTVARIABLE="theanswer" MESSAGE="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>
<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 ACTIVITY="end" />