User Prompts


 Allows interaction with user. This can be used for displaying informational messages or prompting the user for input. This input can be used during the execution of the commands, such as asking for a number of loops, for a file name, or to take alternative action based on their response.

For all User Prompts, there are the following options:

To set a default value (what the user sees before entering a new value), use the System - Set Variable action and set the variable to a value in a step before the prompt:



*Tip:  For all input types that have buttons, the button that the user pressed is available in the system variables {command} and {command_id}. If the user presses Cancel on any input prompt, the default value is returned unchanged, even if the user modified the value before pressing Cancel.


The available commands are:

  Display Message
  Display Warning
  Ask Yes/No Question
  Input Value
  Screen Message
  Status Popup
  Progress Bar Popup
  Balloon Popup
  Tray Icon
  Display Image
  Login Prompt
  Select from List
  Select File
  Select Folder
  Select Drive
  Select Date
  Custom Message
  Custom Dialog


*Tip:  Be sure to make use of the System Variables which allows you to include useful system items in your messages such as {windir}, {clipboard}, and {year}.



  Display Message
 

Shows a message box and waits the user to press the OK button.



  Display Warning
 

Shows an error message box and waits the user to press the OK button.




  Ask Yes/No Question
 

Displays a message box with Yes/No buttons. A "Yes" response is returned as 1, and a "No" response is returned as a value of 0.
If the message is dismissed because the timeout elapsed, the "No" response is chosen.
The {command} system variable will contain the text of the button that was pressed by the user.




  Input Value
 

Displays a message box which allows the user to input a typed response. Multiple lines can be used for a message.
If the message is dismissed because the timeout elapsed, the "Cancel" response is chosen.
The {command} and {command_id} system variables will contain the value of the button that was pressed by the user.



Additional Input Options:



The user may resize the dialog for the "Multiple Lines" option:




  Screen Message
 

Displays a "popup tip", which is a small information box (sometimes called a "tooltip"). Multiple lines can be used for a message.

Be sure to use a timeout value to dismiss the tip, otherwise the tip will stay on the screen. The user cannot close a popup tool tip - it disappears by itself.





The message can appear centered in the screen (default), or you may place the message anywhere on the screen. Screen Messages are very helpful for displaying the status of a process or for troubleshooting a script. Place it in a corner of the screen to display unobtrusive messages.



Only a single screen message per script can appear at once. This is necessary for situations such as displaying a message inside a loop.


  Status Popup
 

Shows a "status popup", which is a rectangular window with no title bar or controls. Multiple lines can be used for a message. The user can dismiss this popup by clicking on it with the mouse, unless the "Always on Top" option is chosen.

This message can be closed in the script by showing no text (an empty "Message"). If this status popup is the last step in a script, it will be dismissed after 1 second (otherwise it would appear to be a frozen program).




  Progress Bar Popup
 

Displays a status popup window that includes a progress bar ("fillbar"). The user can dismiss this popup by clicking on it with the mouse, unless the "Always on Top" option is chosen.

This message can be closed in the script by showing no text (an empty "Message").

The amount to fill the progress bar is taken from the text of the message. A variable also works: "Currently %foo%% Done..." The allowable range is between 0 and 100. Numbers outside of this range will display as 0% or 100%. To fill the bar half way, the following messages would all work:

"Working: 50% done"
"% 50 Remaining"
"50% Complete..."




You can update the text of the message in a loop, which will continue to fill the progress bar during a lengthy process and provide feedback to the user.


  Balloon Popup
 

Displays a "balloon message", which is a small popup message that usually appears near the Windows tray. Multiple lines can be used for a message. There are two types of Balloon popups: Tray and Floating. The "Tray" option appears in the system tray (usually in the lower right corner), while "Floating" can appear anywhere on the screen. The "Tray" option appears as:



The "Floating" option appears as:



The "Floating Track" option allows you to precisely position the balloon stem at an X, Y coordinate. It appears as:



The user can close a popup balloon by clicking on it.



*Tip:  If Balloon Popups do not appear for you, be sure that you have not disabled tray balloons/notifications.


  Tray Icon
 

The Tray Icon action allows you to display a small icon in the Windows system taskbar. This provides a method to control a running script. This is especially important when running this action inside of a compiled EXE - it may be the only way to stop the running program.

It is not necessary to use the "Remove" option at the end of a script - the tray icon will be automatically removed when the script terminates. If a custom icon is available (chosen when the Compile EXE is performed), it will be used, otherwise the default vTask icon will be used.

Double-click or right-click the tray icon to access the menu. The first line helps to identify which Script or EXE is running, which is important if more than one are running. The other commands provide the same stop/pause access as inside of vTask itself:




  Display Image
 

Shows an image, without any borders or windows frames. The pure image is shown on the screen. The user can dismiss the image by clicking on it with the mouse (the cursor changes to a hand), unless the "Always on Top" option is chosen. The image can be in any of the following formats:

The image placement can be adjust to display anywhere on the screen. Additionally, you can Zoom the image (also called "scaling") to any percentage. You can show the image larger (such as "200" for double-size), or smaller (such as "50" for half-size).



If no coordinates are provided, the graphic is placed in the center of the screen. If no Zoom percentage is provided, the graphic is displayed actual size.


  Login Prompt
 

Displays a standard login message box. The password is shown in masked characters. The values from this dialog are stored in the output destination in the format "username;password"

You can set the default username and password by using the Set Variable action prior to showing the dialog. The format for the variable is "username;password" (the same format that it is returned).

If the message is dismissed because the timeout elapsed, the "Cancel" response is chosen.
The {command} system variable will contain the value of the button that was pressed by the user.




  Select from List
 

Displays a message box with a list to choose from. The list options come after the prompt, and are separated with a semicolon (;) or a line return. The first option must also be preceded by a semicolon or newline. The user can double click on a list item to select it.
The {command} system variable will contain the value of the button that was pressed by the user.

      Please choose your favorite sushi:
      Hamachi
      Tempura
      California Roll
      Tuna Roll
      Nigiri



If you include the "Multiple Selection" option, the user will be able to select more than one item from the list. The user's selections are returned separated by a semicolon ";", such as "One;Two;Three;". Use the Get Sub String text fuction to retrieve each result.




  Select File
 

Displays the standard Windows file selection box. To set the file type filter in the "Files of type" drop down, enter a string similar to the format of "Text Files (*.txt)".
The timeout value is required by vTask to be at least 5 seconds. This is for additional compatibility on Windows Vista.

The "Allow Multiple Files" option lets the user choose more than one file, which can be selected by holding down the Control key and clicking a filename.



To set the default file name (the file the user first sees when this window appears), use the Set Variable action in an earlier step.


  Select Folder
 

Displays the standard Windows folder selection box.
The timeout value is required by vTask to be at least 2 seconds. This is for additional compatibility on Windows Vista.




  Select Drive
 

Displays a list of all connected (and accessible) disk drives. The selection is returned in "C:" format.

The Only Fixed Drives option restricts the list of available drives to fixed disks. With this option selected, CD-ROMs and removable storage drives (such as memory cards) are not shown.




  Select Date
 

Displays a month calendar that can be used to select a date.



The user may use the keyboard to navigate inside of the calendar.
If the user resizes the calendar window, additional months will become visible:



The calendar will be displayed using the current language setting of the computer:



The "Calendar Display" setting determines how many months will be visible in the initial display of the calendar. The user can resize the window to display more or fewer months.
The following example shows a 2x2 option, which displays a 4-month calendar:




  Custom Message
 

If the different types of user messages provided by vTask do not fit your needs, you can create custom messages by using this action. For example, can can create a message with "Abort/Retry/Ignore" buttons:




The return values are available in the {command} and {command_id} system variables. The common return values are listed below. You can also use the constants IDYES, IDNO, IDRETRY, etc directly in your script, such as with IF Expression. 

#   Button    {command_id}            {command}  
            
1   OK        IDOK, ID_OK             "OK"
2   CANCEL    IDCANCEL, ID_CANCEL     "Cancel"
3   ABORT     IDABORT, ID_ABORT       "Abort"
4   RETRY     IDRETRY, ID_RETRY       "Retry"
5   IGNORE    IDIGNORE, ID_IGNORE     "Ignore"
6   YES       IDYES, ID_YES           "Yes"
7   NO        IDNO, ID_NO             "No"



  Custom Dialog
 

The Custom Dialog action provides the most control over user interaction. You can create a dialog with multiple controls of various types (button, edit, list, etc), and also control script flow when buttons are pressed. The following control types are provided:



A total of 5 separate items can be placed on the dialog, and are arranged vertically. Each item has a control type and text. The Text property for each control depends on the control type, for example, for BUTTONS, it is used as the button's text, and for EDIT types, it is used as the label to the right of the edit field.



The control items do not have to be sequential, for example, you may use item #1 and #4, or only item #3 if you wish.



You can make buttons wider than normal by using spaces around the button text:



OK and Cancel buttons are automatically included in the dialog. To determine which button was pressed by the user, use the {command} or {command_id} System Variables:





To set the default values, use a Save Output option of "Variable", and set the variable to contain all the values of the controls, separated by semicolons. This works for EDIT, FILE, PASSWORD, LIST, and CHECKBOX controls. To check a checkbox, use the word "checked":

  +  




The data from each field is returned to the "Save Output To" location, with each field separated by a semicolon. For example, the following input:



...would generate the following output:
(NOTE: Checkboxes return "checked" when selected, and "false" when not selected. This is done to conform closely to Javascript, also, the alternatives such as "unchecked" or "not checked" could cause confusion for during parsing as they contain the word "check").



You can then use the "Get Sub String" action to retrieve the appropriate data result:



The following table describes each of the possible control types:

Control TypeDescriptionSample
LABEL A simple text label (static control) that takes no input. Labels are always centered in the middle of the dialog box.


EDIT A data field which the user can type into.

Multiple-line fields are not currently supported in Custom Dialogs, however they can be used with the Input Value action


CHECKBOX Displays a on/off checkbox. A single dialog can contain multiple, independent checkboxes.


BUTTON Moves program flow (next step) to the Label that has the same name as the button.

It also sets the {command} and {command_id} system variables to the value of the pressed button. Therefore, alternative functionality is to check the value of {command} after the dialog is finished, instead of including a matching label.

See images below for more examples of each scenario.


LIST Displays a list of options, with each item separated by a semicolon ";" or a line return. The first option is used as the text label. This is the same functionality as the "Select from List" command.

There is no maximum length for the number of options in a list.


FILE Same as an EDIT field, but also includes a file lookup button.

When the lookup button is pressed, a standard File Open dialog is displayed, and the user's selection is placed into the edit field. The file name is not required to exist.


FOLDER Same as an EDIT field, but also includes a folder lookup button.

When the lookup button is pressed, a standard File Selection dialog is displayed, and the user's selection is placed into the edit field. The folder name is not required to exist.


PASSWORD Same as an EDIT field, however the input is masked.


LINK Creates a blue text URL hotlink. When the mouse cursor is over the link, the hand selection cursor will appear. Links are always centered in the middle of the dialog box.

Links do not save any result data. They only link to the web page URL provided. The "url" text can be in any of the following formats:

  • Normal HREF:   <a href="http://www.vtaskstudio.com">Vista Software</a>
  • URL-only:   www.vtaskstudio.com
  • Local File:   C:\Documents\SALES.XLS








Here are more examples of the "BUTTON" functionality.
The first example is using the "Jump to Label" feature of BUTTONS, to control script flow:




The second example is using the "{command}" System Variable feature of BUTTONS, by doing a comparison with IF and taking action: