Prompt message, [detail], [defaultButton], [otherButton]

Displays a message to the user. This instruction returns either the string value of defaultButton or otherButton, depending on which the user clicked. If otherButton is omitted, then the user has only one button to click.

Prompt Input message, [detail], [button], [defaultText]

Displays a message to the user and allows them to type in some free-form text. This instruction returns the text that the user has entered.

Prompt Options message, detail, button, optionsArray, [selectedOption] v3.0

Displays a message and has the user choose a single value from a list. The return value is the selected option, eg:

$message = 'What is your favorite color?'

$colors = Array.new('Red', 'Green', 'Blue')

$color = Prompt Options $message, '', 'Okay', $colors

The first option in the array will be selected by default, unless you provide a selectedOption argument.

This command will split a very long list of options that cannot be shown on screen at once into multiple pages, allowing the user to cycle through the pages.

Legacy Documentation:

This command is available as far back as v1.1, but does not recognize the optional selectedOption argument.

An even earlier form of this command is available as far back as v1.0, but it does not accept an array of options. The options must be passed directly as a variable length argument list, eg:

$message = 'What is your favorite color?'

$color = Prompt Options $message, '', 'Okay', 'Red', 'Green', 'Blue'

Prompt Checkboxes message, detail, button, optionsArray, [selectedOptions] v3.0

Displays a message and has the user choose values from a list of checkboxes. The returned value is an array of all checkmarked options, in the order in which they were given. An example:

$message = 'Which colors do you like?'

$allColors = Array.new('Red', 'Green', 'Blue', 'Purple', 'Orange')

$defaultColors = Array.new('Red', 'Purple')

$userColors = Prompt Checkboxes $message, '', 'Okay', $allColors, $defaultColors

By default none of the displayed options will be checkmarked, unless you provide a selectedOptions array.

This command will split a very long list of options that cannot be shown on screen at once into multiple pages, allowing the user to cycle through the pages.

Legacy Documentation:

This command is available as far back as v1.3, but does not recognize the optional selectedOptions argument. This legacy mode also has a form that foregoes the use of an options array argument. The options can instead be passed directly as a variable length argument list, eg:

$message = 'What are your favorite colors?'

$color = Prompt Checkboxes $message, '', 'Okay', 'Red', 'Green', 'Blue'

Prompts the user to choose a single file and returns the path to that file. If the user cancels the @undefined value is returned. If a default file path is given and not an empty string, then that file will be selected initially.

Choose Files [defaultFilePath], [openButtonCaption] v1.2

Prompts the user to choose one or more files and returns an array of file paths. If the user cancels the @undefined value is returned. If a default file path is given and not an empty string, then that file will be selected initially.

Choose Folder [defaultFolderPath], [openButtonCaption] v1.2

Prompts the user to choose a single folder and returns the path to that folder. If the user cancels the @undefined value is returned. If a default folder path is given and not an empty string, then that folder will be selected initially.

Prompts the user to choose a save name and location for a file. Returns the path to the chosen location, or the @undefined value if the user cancels. The chosen file may or may not already exist, but this command will warn the user about replacing any file.

NOTE: this command does not actually save any data. The macro itself should write the data to the chosen location as necessary.