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   

Overview

Displays a message box during task execution using the specified settings. 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 OK 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 display during runtime. This can be instructions, feedback, process results, or any important information expressed to the user.
Title of the message box Text No (Empty) WINDOWTITLE="Message" The title that appears 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 appears 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 displayed on the message box. The available options are:
  • OK (Default) - The message box contains an OK button only.
  • OK, Cancel - The message box contains an OK and Cancel button.

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

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

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

  • Yes, No, Cancel - The message box contains Yes, No and Cancel buttons.
Button selected by default Number No 0 DEFAULTBUTTON=2 The number associated to the button (from left to right) selected by default. The number 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 is 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 suspends 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 continues to the next step.

  • Stop - Stops the task. No error is generated.

  • Fail - The task fails with an error.

  • Start a task - Starts another task.

  • Set a variable - The specified variable is 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 continues to the next step.
  • Stop - Stops the task. No error is generated.
  • Fail - The task fails with an error.
  • Start a task - Starts another task.
  • Set a variable - The specified variable is 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 continues to the next step.

  • Stop - Stops the task. No error is generated.

  • Fail - The task fails with an error.

  • Start a task - Starts another task.

  • Set a variable - The specified variable is 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, specifies the path and file name of the task that starts. 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, 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 in the return code.
Automatically select the default button Number No (Empty) COUNTDOWNDELAY="10" The amount of time that elapses before the default button is 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 is measured in milliseconds.
  • seconds - The time is measured in seconds.
  • minutes - The time is measured in minutes.
  • hours - The time is 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 is displayed at the center of the screen.
  • Upper left corner of screen - The input dialog is displayed at the upper left of the screen.
  • Lower left corner of screen - The input dialog is displayed at the lower left of the screen.
  • Upper right corner of screen - The input dialog is displayed at the upper right of the screen.
  • Lower right corner of screen - The input dialog isdisplayed at the lower right of the screen.
  • Custom location - The input dialog is 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 is 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 is 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 is 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

The following 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

The following task 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

The following is 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" />