Dialog - Input Box

Declaration

<AMSHOWDIALOG ACTIVITY="input" DEFAULTVALUE="text" RESULTVARIABLE="text" WINDOWTITLE="text" XPOS="number" YPOS="number" ICON="text (options)" ONCANCEL="text (options)" COUNTDOWNDELAY="number" MASKINPUT="YES/NO">text</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 an input box allowing the user to enter a value. The value entered is saved to the variable specified. Execution is paused while the task waits for a value to be entered.

Practical Usage

Useful for asking a question that requires a text response at runtime. This action is similar to the Message Box action except this action allows the user to enter a text value in response to a question. The text value is populated into a variable.

Parameters

General Properties

Property

Type

Required

Default

Markup

Description

Message to Display

Text

Yes

(Empty)

MESSAGETEXT="What's your answer to the question?"

The text message to be displayed in the input box during runtime. This is usually a question that the user should input an answer to.

Default Value

Text

No

(Empty)

DEFAULTVALUE="Question"

The default text that should appear in the input box. This parameter is optional.  

Populate variable with value entered

Text

No

(Empty)

RESULTVARIABLE="varname"

The name of an already created variable that should be populated with the text that the user has entered as a response to the question.

Title of Input Box

Text

No

(Empty)

WINDOWTITLE="QUESTION"

The title that the input 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 input box will appear in front of all other open windows.

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

Display this icon in the message box

Text

(Options)

No

(Empty)

ICON="exclamation"

If enabled, specifies the icon that should be displayed on the input box next to the title. 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.

Button selected by default

Number

No

0

DEFAULTBUTTON="2"

The number associated with the button that should be focused by default. 1 specifies the OK button and 2 specifies the Cancel button. This parameter can be used in conjunction with the Automatically press the default button after parameter.

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 input box clears itself. If this option is disabled, the input box is displayed indefinitely. Measures include:

  • Milliseconds

  • Seconds (Default)

  • Minutes

  • Hours

Mask Input

Yes/No

No

No

MASKINPUT="YES"

If set to YES, for security purpose, specifies that the information entered in the input box will be masked by the number sign (i.e. ######). This parameter is set to NO by default.

 

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