_prompt
(Windows only) (As of 3.1.002.06)
Ask the user for input. Prompt user for OK/Cancel, Yes/No, Text, Date.
Syntax
_prompt(type, message[, default|choicelist])
Parameters
type is the type of popup Windows dialog to display.
- OKCancel - user can press OK or Cancel button.
- YesNo - user can press Yes or No button.
- YesNoCancel - user can press Yes, No, or Cancel button.
- String - user is prompted to enter a line of text.
- Password - same as String but text with echo stars instead a actual text entered.
- Choice - user can choose from a dropdown list of responses.
- ChoiceID - as above, but a tag associated with the selection is returned.
- Date - user can enter a calendar date.
The type parameter is case-insensitive, so 'YesNo', 'yesno' are both accepted.
message is a prompting message to be displayed at the top of the popup dialog. You can also set the dialog title with this, by preceding the message text with the dialog title followed by a vertical bar, for example: "OK to Continue|Do you wish to continue this operation:" will set both the dialog title and the message text.
default is the default value of the input. For YesNo, OKCancel, and YesNoCancel the default value can be set to the same values as are returned by these calls. A value of 1 makes the "Yes" or "OK" button the default, a value of 0 makes the "No" button the default, and a value of -1 makes the "Cancel" button the default. For type String the default parameter will be displayed as the initial value of the input edit box. For Date the default parameter is an initial date string in YYYYMMDD format. For the Choice and ChoiceID types, the default parameter is not used, but a default choice can be set in the choicelist (see below).
choicelist is a JavaScript structure or array listing the choices the user will select from. It can be a simple array of strings, such as:
['choice 1', 'choice 2', 'choice 3']
or a JavaScript structure such as
{ first:'choice 1', second:'choice 2', ...}
The Choice type option will always return the displayed string, so "choice 2" for instance. The ChoiceID type option will instead return the index or attribute, so in the second case above it would return "second" if the 'choice 2' option is selected. (If you use the simple array choices with the ChoiceID option, you'll get 0, 1, 2 etc. as the returned values.)
If you wish to specify a choice other than the first one as the default displayed choice, put an asterisk in front of the choice value.
{ first:'choice 1', second:'*choice 2', ...}
Returned Value
The returned value depends on the type of the prompt call.
YesNo, OKCancel, and YesNoCancel return a value of 1 is returned for the "Yes" or "OK" option, a value of 0 for the "No" option, and a value of -1 for the "Cancel" option.
Date returns the selected date as a string formatted as YYYYMMDD.
String and Choice return the entered or selected string.
ChoiceID returns the JavaScript associated property name or array index of the selected item, rather than the item itself.
Examples
if (!_prompt('yesno', 'Continue?|Do you wish to continue?)) return;
name = _prompt('string', 'Enter your name:');
date = _prompt('date', 'Select a new date:');
date = _prompt('date', 'Select a new date:', '20181225'); // default to xmas 2018
