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

  1. BUTTONS="ok"

  2. BUTTONS="ok_cancel"

  3. BUTTONS="abort_retry_ignore"

  4. BUTTONS="retry_cancel"

  5. BUTTONS="yes_no"

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

  1. ONFIRSTBUTTONCLICK="continue"

  2. ONFIRSTBUTTONCLICK="stop"

  3. ONFIRSTBUTTONCLICK="fail"

  4. ONFIRSTBUTTONCLICK="start_task"

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

  1. ONSECONDBUTTONCLICK="continue"

  2. ONSECONDBUTTONCLICK="stop"

  3. ONSECONDBUTTONCLICK="fail"

  4. ONSECONDBUTTONCLICK="start_task"

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

Task to Start

Text

Yes if Start a task option is selected

(Empty)

  1. ONFIRSTBUTTONCLICKTASK="c:\folder\task.aml"

  2. ONSECONDBUTTONCLICKTASK="c:\folder\task.aml"

  3. ONTHIRDBUTTONCLICKTASK="c:\folder\task.aml"

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)

  1. ONFIRSTBUTTONCLICKVARNAME="varName"

  2. ONSECONDBUTTONCLICKVARNAME="varName"

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

  1. ONFIRSTBUTTONCLICKVARVALUE="newValue"

  2. ONSECONDBUTTONCLICKVARVALUE="newValue"

  3. 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 Parameters

Property

Type

Required

Default

Markup

Description

Position

Text

 (Options)

No

Center of screen

  1. POSITION="center"

  2. POSITION="upper_left"

  3. POSITION="lower_left"

  4. POSITION="upper_right"

  5. POSITION="lower_left"

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

  1. ICON="none"

  2. ICON="information"

  3. ICON="exclamation"

  4. ICON="question"

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

↑ [Return to Top]