Dialog - Message Box

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>

See Also

Dialog - Browse for Folder | Dialog - Input Box | Dialog - Message Box | Dialog - Open File |  Dialog - Save File | Dialog - Selection Box | Close Window | Focus Window | Hide Window | Maximize Window | Minimize Window | Move Window | Resize Window | Restore Window | Unhide Window

Description

Displays a message box 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 provide informative feedback to the user during task execution.

Parameters

General Properties

Property

Type

Required

Default

Markup

Description

Message to Display

Text

Yes

(Empty)

MESSAGETEXT="Variable content is %VARNAME%"

The text message to be displayed in the message box during runtime. This can be feedback about the task that the user should be informed of.

Title of Message Box

Text

No

(Empty)

WINDOWTITLE="Message"

The title that the message box should display.

Bring message to front of all other windows

Text

No

Yes

WINDOWINFRONT="NO"

If set to YES (default value), specifies that the message box will appear in front of all other open windows.

Buttons Properties

Property

Type

Required

Default

Markup

Description

Buttons contained in the message box

Text (options)

No

Ok

BUTTONS="yes_no"

The button or array of buttons that should be displayed on the message box. Different parameters appear depending on the option chosen. 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 of the button (from left to right) that should be focused 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 Yes, No is selected from the Buttons contained in the message box parameter, first (1) specifies the Yes button and second (2) specifies the No button.

On first button click

Text

No

(Empty)

ONFIRSTBUTTONCLICK="stop"

The action that should take place when the first (from left to right) button is clicked. The available options are:

  • Continue: When the button is clicked, the step will allow the task to continue.

  • Stop: When the button is clicked, the step will stop the task.

  • Fail: When the button is clicked, the step will fail.

  • Start the task: When the button is clicked, another task will be started. The task to be started is specified in the Task to start parameter.

On First Button Click - Task to Start

Text

No

(Empty)

ONFIRSTBUTTONCLICKTASK=

"c:\folder\task.aml"

The task that should be run when the first button is clicked. Click the Folder icon to navigate to the desired task (.aml) file. Valid only if the Start task parameter is selected.

On Second Button Click

Text

No

(Empty)

ONSECONDBUTTONCLICK="stop"

The action that should take place when the second (from left to right) button is clicked. The available options are:

  • Continue: When the button is clicked, the step will allow the task to continue.

  • Stop: When the button is clicked, the step will stop the task.

  • Fail: When the button is clicked, the step will fail.

  • Start the task: When the button is clicked, another task will be started. The task to be started is specified in the Task to start parameter.

On Second Button Click - Task to Run

Text

No

(Empty)

ONSECONDBUTTONCLICKTASK=

"c:\folder\task.aml"

The task that should be run when the second button is clicked. Click the Folder icon to navigate to the desired task (.aml) file. Valid only if the Start task parameter is selected.

On Third Button Click

Text

No

(Empty)

ONTHIRDBUTTONCLICK="stop"

The action that should take place when the third (from left to right) button is clicked. The available options are:

  • Continue: When the button is clicked, the step will allow the task to continue.

  • Stop: When the button is clicked, the step will stop the task.

  • Fail: When the button is clicked, the step will fail.

  • Start the task: When the button is clicked, another task will be started. The task to be started is specified in the Task to start parameter.

On Third Button Click - Task to Run

Text

No

(Empty)

ONTHIRDBUTTONCLICKTASK=

"c:\foldername\taskname.aml"

The task that should be run when the third button is clicked. Click the Folder icon to navigate to the desired task (.aml) file. Valid only if the Start task parameter is selected.

Advanced Properties

Property

Type

Required

Default

Markup

Description

Position

Text

 (options)

No

Centered on screen

POSITION="upper_left"

The button or array of buttons that should be displayed on the message box. The available options are:

  • Upper left corner of the screen: The message box will be displayed at the upper left of the screen.

  • Centered on the screen (default): The message box will be displayed at the center of the screen (default).

  • Lower left corner of the screen: The message box will be displayed at the lower left of the screen.

  • Upper right corner of the screen: The message box will be displayed at the upper right of the screen.

  • Lower right corner of the screen: The message box will be displayed at the lower right of the screen.

  • Customized: The message box will be displayed at the pixel coordinates specified at X Pos and Y Pos parameters.

X Pos

 

Number

No

(Empty)

XPOS="55"

The X (horizontal) coordinates of the position that the upper left corner of the message box should be displayed on the screen. Move the mouse cursor to the desired location on the screen and press the INSERT key to capture the position. This option is available only if Custom is selected from the Position parameter.

Y Pos

 

Number

No

(Empty)

YPOS="55"

The Y (vertical) coordinates of the position that the upper left corner of the message box should be displayed on the screen. Move the mouse cursor to the desired location on the screen and press the INSERT key to capture the position. This option is available only if Custom is selected from the Position parameter.

Execution of the task will stop until a button on the box is clicked

Yes/No

No

Yes

MODAL="NO"

Specifies whether task execution should pause until a button is clicked (i.e. "modal") or the task moves on to the next step immediately (i.e. "modeless").

Populate variable with return code

Text

No

Disabled

RESULTVARIABLE="varname"

If enabled, indicates the name of an already created variable that should be populated with the number of the button (from left to right) that has been clicked. This option is valid only if MODAL=YES.

Display this icon in the message box

Text

No

(Empty)

ICON="exclamation"

If enabled, specifies the icon that should be displayed on the message box next to the icon. This helps to determine what type of message is being displayed. The available options are:

  • Exclamation point: An exclamation point icon is displayed.

  • Information: The standard Windows information icon is displayed.

  • Question mark: The standard Windows question icon is displayed.

  • Stop sign: The standard Windows stop icon is displayed.

Automatically press the default button after

Number/Options

No

Disabled

COUNTDOWNDELAY="10" MEASURE="minutes"

If enabled, specifies the amount of time that should elapse before the message box clears itself. If this option is disabled, the input box is displayed indefinitely. Measures include:

  • Milliseconds

  • Seconds (Default)

  • Minutes

  • Hours

Description Properties

The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab properties lets you instruct a task step to react only to specific errors or ignore certain errors that should cause it to fail.

More on Error Causes properties

On Error Properties

The On Error tab properties lets you determine what the task should do if a particular step encounters an error as defined in the Error Causes properties.

More about On Error properties

Additional Notes

Expressions, Variables & Functions

A percent sign is used as a special character in AutoMate to indicate the beginning and end of an expression. This allows variables, functions and other expressions to be entered in any text parameter of a task's properties. For example: %1+1% inside a task will resolve to 2 at runtime. A more elaborate example is %FileDateTime(myFile)% which results to the date/time of myFile. To help construct expressions, you can open Expression Builder by clicking the Insert Expression (%) button or by pressing F2.

More on expressions

More on variables

More on functions

More on extended functions
More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

 

Sample Task 1 - This sample task demonstrates use of the Input Box activity (step 2) by saving the text entered in the input box that appears and then displaying the text in a separate Message Box (step 3).

 

<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 - This sample task opens a message box that displays the version of your AutoMate installation.

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

 

Sample Task 3 - This sample task demonstrates the following:

  1. Use of the Input Box activity to ask the user a question and retrieve the answer

  2. Use of Custom BASIC Functions

  3. Use of the IF action

  4. Use of Expressions

  5. Use of Message Box activity to display the answer.

 

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