Dialog - Selection Box

Declaration

<AMSHOWDIALOG ACTIVITY="select" MESSAGETEXT="text" RESULTVARIABLE="text" ITEMS="text (caption1),text (caption2),text (caption3)" VALUES="text (value1),text (value2),text (value3)" INDEXSELECTED="1" WINDOWTITLE="text" ONCANCEL="continue" COUNTDOWNDELAY="number" />

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 auto-generated multiple choice dialog box based the options you specify. Choice is useful when a multiple-choice selection is needed or the user must make a decision that will affect which subsequent actions should be executed by the task. The value associated with the item that the user selects is placed into a variable where it can be evaluated and acted on.

Practical Usage

Similar to the Input Box action except this action allows the user to select a value in response to a question. The text value is populated into a variable which can be used later in the task.

Parameters

General Properties

Property

Type

Required

Default

Markup

Description

Dialog Title

Text

No

(Empty)

WINDOWTITLE="the_title"

The text that should appear on the title bar of this dialog box.

Populate variable with result

Text

Yes

(Empty)

RESULTVARIABLE="varname"

Specifies the name of an already created variable that should be populated with the value parameter of the item selected. If the user has selected multiple items the values are returned as a comma-delimited list.

Message to display

Text

No

(Empty)

MESSAGETEXT="The message"

The text to be displayed in the selection dialog box. Usually this is a question that the user should select the answer to.

List Type

Text (options)

Yes

Dropdown

LISTTYPE="checkbox"

Specifies the manner by which the list will be displayed on the auto-generated form at runtime. This selection is relevant not only for aesthetics but will also affect the ability of the user to make a multiple choice selection (see below). The available options are:

  • Dropdown: The items in the list will be placed into a drop-down box (this option does not allow multiple selections).

  • Checkbox: The items in the list will be represented as a collection of checkboxes (this option allows multiple selections).

  • Option: The items in the list will be represented as a collection of option buttons - also known as radio buttons. (this option does not allow multiple selections).

  • List: The items in the list will be represented as a list box (this option allows multiple selections).

Item Source

Text (options)

No

List

ITEMS="item1, item2"

Specifies where the list items should derive from. Different parameters appear depending on which option is selected. The available options are:

  • List: Allows the option to manually enter a list by clicking the Add button.

  • Dataset: Allows the list to derive from an existing AutoMate dataset.

  • Array: Allows the list to derive from an existing array.

Caption

Text

Yes if items derive from a list

(Empty)

ITEMS="FTP,HTTP,Backup"

Specifies a comma-delimited list of items that appear at runtime during execution of this action. There must be an equivalent number of captions to value items. Each caption must have a corresponding item in the Value parameter. This parameter is valid only if List is selected from the Item Source parameter.

Value

Text

Yes if items derive from a list

(Empty)

VALUES="FTP Upload,HTTP Put,Backup Files"

Specifies a comma-delimited list of values. They represent value(s) that will be returned by the item if selected at runtime by the user. There must be an equivalent number of values to caption items. Each value must have a corresponding item in the Caption parameter. This parameter is valid only if List is selected from the Item Source  parameter.

Selected

Number

Yes if items derive from a list

(Empty)

SELECTED="3"

Specifies the index number of the item(s) that should be checked or selected by default. Depending on the option selected under the List Type parameter, the requirements for this parameter differ. In the case of a Dropdown or Options list type, one item must be selected. In the case of a List or Checkbox list type, no items or multiple items may be specified. To specify multiple options the numbers should be comma-delimited. This parameter is valid only if List is selected from the Item Source parameter.

Dataset

Text

Yes if list items are gathered from a dataset

(Empty)

DATASET="theDataset"

The name of the dataset that the list items should be gathered from. This parameter is valid only if Dataset is selected from the Item Source  parameter.

Caption Column

Text

Yes if list items are gathered from a dataset

(Empty)

COLUMN="Drive"

Specifies the dataset column that should be used as the caption (list of items that appear at runtime during execution of this action). This parameter is valid only if Dataset is selected from the Use items from parameter.

Index selected

Number

Yes if list items are gathered from a dataset or array

(Empty)

INDEXSELECTED="3"

Specifies the index number(s) of the items that should be checked or selected by default. Depending on the option selected under the List Type parameter, the requirements for this parameter differ. In the case of a Dropdown or Options list type, one item must be selected. In the case of a List or Checkbox list type, no items or multiple items may be specified. To specify multiple options the numbers should be comma-delimited. This parameter is valid only if Dataset or Array is selected from the Item Source  parameter.

Use column as value

Text

Yes if list items are gathered from a dataset

(Empty)

COLUMNVALUE="Drive"

If enabled, indicates that the value of a specific dataset column should be used as the value. The default option is Return index as value, which returns the index (row number) as the value.  

Array

Text

Yes if list items are gathered from an array

(Empty)

ARRAY="arrayName"

The name of the array that the list items should be gathered from.

NOTE: The first column of the array will be used as the caption.

This parameter is valid only if Array is selected from the Use items from parameter.

Bring message to front of all other windows

Yes/No

No

Yes

WINDOWINFRONT="NO"

If set to YES (default value), the message window will appear in front of all other windows during execution of this step.

Button Properties

Property

Type

Required

Default

Markup

Description

On Cancel

Text (options)

No

Stop

VALUEONCANCEL="cancelled"

Specifies the value that should be returned into the variable if the user presses the Cancel button. The available options are:

  • Continue - The task will continue  if the Cancel button is pressed by the user.

  • Stop (default) - The task will stop  if the Cancel button is pressed by the user.

  • Fail - The step will fail if the Cancel button is pressed by the user.

  • Start Task - The specified task will start if the Cancel button is pressed by the user.

  • Set Variable - The selected variable will be set to the specified value  if the Cancel button is pressed by the user.

Automatically press the OK button after

Number

No

Disabled

COUNTDOWNDELAY="1"

MEASURE="minutes"

The delay time for this activity.

Measure

Text (options)

No

Disabled

MEASURE="hour"

The numeric measure to use when

Advanced Properties

Property

Type

Required

Default

Markup

Description

Force selection

Yes/No

No

Yes

FORCESELECT="NO"

Specifies that the user must make a valid selection before continuing. This option is only valid if the List Type parameter is set to Checkbox or List. Other list types automatically force selection.

Allow multiple selections

Yes/No

No

No

MULTIPLE="YES"

Specifies that multiple selections are allowed. This option is only valid if the List Type parameter is set to Checkbox or List as only those controls support multiple-selection.

Automatically press the OK button after

Number/Options

No

Disabled

COUNTDOWNDELAY="1"

MEASURE="minutes"

If enabled, indicates that the OK button will be automatically pressed after the elapsed time specified. If this option is disabled, the choice dialog 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.

 

Description: This sample task shows how to use the Choice action and make decisions based on the answer.
 

 

<AMVARIABLE NAME="FoodofChoice"></AMVARIABLE>

<AMSELECTITEM MESSAGETEXT="What would you like to eat?" WINDOWTITLE="What's for lunch?" LISTTYPE="option" RESULTVARIABLE="FoodofChoice" ITEMS="Hamburger,Pizza,Chicken" VALUES="1,2,3" SELECTED="2" />

<AMIF EXPRESSION="%FoodofChoice% = &quot;1&quot;">

     <AMMESSAGEBOX>You chose hamburger.</AMMESSAGEBOX>

</AMIF>

<AMIF EXPRESSION="%FoodofChoice% = &quot;2&quot;">

     <AMMESSAGEBOX>You chose pizza.</AMMESSAGEBOX>

</AMIF>

<AMIF EXPRESSION="%FoodofChoice% = &quot;3&quot;">

     <AMMESSAGEBOX>You chose chicken.</AMMESSAGEBOX>

</AMIF>

 

↑ [Return to Top]