Wait Action


 Pauses execution of the script, and continues when a certain condition is met.

One of the design requirements for the Wait command was the ability to function properly even when compiled into an EXE, which means that it was important for it to function without separate modules or external system dependencies.

*Tip:  The Wait Action provides scheduling capabilities for vTask. A script or compiled EXE can be launched, and run as long as needed in the background, and will not degrade the computer's performance.


The Wait action has a the lowest possible processing priority, which means it can be active continuously while a script or EXE is running. It will not slow down the PC, and does not constantly poll the computer. It uses almost no CPU time (usually around 0%). It functions more on an "interrupt" or notification architecture, which means that the Wait command is signaled by the computer when the appropriate event or time occurs. Because of this capability, an EXE can run with an active or pending Wait command for as long as needed (hours, days, or even longer).

Due to this design, most Wait actions will sense completion within a few seconds, but not always instantly. For example, if a new window appears that completes the "Wait for Window" action, the script may wait for a few additional seconds until it sees the window. This is due to the low CPU-processing design of this action. The "Wait for Date/Time" may take longer, and is only guaranteed to happen within the specified minute. For example, if you wish to wait until 1:23, it may be completed at 1:23 and 2 seconds, or 1:23 and 25 seconds (depending on various factors at the moment). In other words, the time resolution of the Wait action ranges depending on the action.

The Stop Key will terminate the wait action (and the whole script). In certain circumstances, this key is not available - for example, if the "Wait for Keypress" action has that key listed as the wait key. Because of these reasons, for many of the Wait actions, pressing the Stop Key is not sufficient; it is much more effective to press the "Stop Run" toolbar button.

*Tip:  It is highly recommended to use the Tray Icon action while running the Wait command. It allows you to control the script while it is running, which is especially important when running this action inside of a compiled EXE - it may be the only way to stop the running program.


If you simply want to slow down execution for all steps, use the System - Set Run Speed command instead of Wait.

The available commands are:

  Delay
  Wait for Date/Time
  Wait for Keypress
  Wait for Typed Text
  Wait for Mouse
  Wait for Window
  Wait for File
  Wait for Folder
  Wait for Pixel
  Wait for Image to Appear
  Wait for Clipboard
  Wait for Screen Saver
  Wait for Idle
  Wait for Restart



  Delay
 

This is the standard pause that should be used in normal situations. It simply pauses the execution of the script for the indicated duration. It permits user interaction with vTask and other programs for the duration of the pause.

This can be useful for waiting for a process to complete, to avoid going too fast for the operating system, or to give the user time to react. The duration can include fractions of a second, such as "2.5" or "0.5".


  Wait For Date/Time
 

Pauses execution of the script until a certain Date and/or Time is reached. If the specified Date/Time is in the past, the step will always succeed. The [Date] field uses the format of your PC. To determine the correct date format, use the calendar lookup button above the field. User Variables may be used for either the date or the time values.

The "Persist if Reboot" allows the step to continue waiting even if the computer is rebooted. Once the computer starts again, the script restarts at the same step, and keeps waiting until the specified time arrives. This feature will allow it to continue waiting regardless of the number of computer reboots that happen before the specified time arrives.


  Wait For Keypress
 

With this option, execution of the script will stay at the current line until the user presses a single specified key on the keyboard. The keypress will be the first key pressed if the "Any Key" checkbox is selected, otherwise it will wait for the specific key that you enter. Use the System Variables button to look up the key codes, such as {Esc} and {F1}.

The internal methods used for "Wait For Keypress" and "Wait For Typed Text" are different to provide alternatives. IF you have difficulty with one (due to another program's interference), try the alternative action.

This action works even if another application has the keyboard focus at the time. If the key is not pressed within the timeout period, the step will fail.


  Wait For Typed Text
 

This action pauses execution of the script until the user types the exact string on the keyboard. Only alphanumeric characters can be used (A-Z, 0-9, "!@#$", etc.), and not system keys such as {F1}.

This action works even if another application has the keyboard focus at the time. If the text is not typed within the timeout period, the step will fail.


  Wait For Mouse
 

Pauses execution of the script until the user performs an action with the mouse. The available options are Wait for: Left Click, Right Click, Middle Click, Any Click, or Move.

The "Any Click" option will be completed when any mouse button is pressed. The "Move" option will be completed when the mouse cursor experiences any movement whatsoever (including programmatically).

This action works even if another application has the keyboard focus at the time. If the specified mouse action is not pressed within the timeout period, the step will fail.


  Wait for Window
 

Pauses execution until a certain window state is achieved. The following window options are available:

Match ConditionDescription
Appear when the window exists anywhere on the system, even hidden or minimized
Activate when the window is on top or contains the focus (such as the typing cursor)
Close when the window no longer exists (not just when it is minimized)


If the window option is successful when this step is first encountered, processing immediately continues with the next step, without additional delays.

If no "Use Window" command is run after this step, the "Wait for Window" command will use the located handle for any window commands that follow (unless "Wait for Close" is desired). In effect, the "Wait for Window" command includes a subset of the matching features of "Use Window".

For further information concerning window identification, please refer to the Identifying Windows and Controls.

Sample Script:
Below is a sample script that illustrates how to use the Wait for Window command. Notice how in the sample script below, an extra check was added to see if the window is valid first.



(Copy and paste into vTask)
<step>
	<action>Comment</action>
	<comment>PURPOSE: A sample script to demonstrate basic Wait for Window functionality</comment>
</step>
<step>
	<action>Start</action>
	<text>calc.exe</text>
	<options>Single</options>
	<comment>This script starts Calculator</comment>
</step>
<step>
	<action>Delay</action>
	<timeout>1</timeout>
</step>
<step>
	<action>Comment</action>
	<comment>Confirm the window is visible</comment>
</step>
<step>
	<action>IF Window Exists</action>
	<text>Calculator</text>
	<options>IF NOT,Exact Title</options>
</step>
<step>
	<action>Display Warning</action>
	<text>Window not found!</text>
	<indents>1</indents>
</step>
<step>
	<action>Exit Run</action>
	<indents>1</indents>
</step>
<step>
	<action>END IF</action>
</step>
<step>
	<action>Comment</action>
	<comment>Wait for the window to close...  (manually close calculator)</comment>
</step>
<step>
	<action>Wait for Window</action>
	<text>Calculator</text>
	<options>Exact Title</options>
	<value1>Close</value1>
	<timeout>10</timeout>
	<comment>Now, close Calculator (within 10 seconds)</comment>
</step>
<step>
	<action>Display Message</action>
	<text>Calculator is closed!</text>
	<comment>When closed, this will show</comment>
</step>



  Wait for File
 

Pauses execution until a specified file state exists. The following file match options are available:

Match ConditionDescription
Exist The file can be any size, 0 bytes or larger.
If the file already exists when this step is first encountered, processing immediately continues with the next step.
Not Exist Passes if the file does not exist
Change Passes if the file size or checksum (file contents) changes.

Any change in exist/not exist status also causes this check to pass (ie, if it is created or deleted while waiting).



  Wait for Folder
 

Pauses execution until a specified folder state exists. The following folder match options are available:

Match ConditionDescription
Exist A folder simply needs to exist to pass, and may be empty of files.
If the folder already exists when this step is first encountered, processing immediately continues with the next step.
Not Exist Passes if the folder does not exist
Change Passes if anything in the folder (or any sub-folders) changes. This also includes any files under the main folder that are added, deleted, or changed.

Any change in exist/not exist status also causes this check to pass (ie, if it is created or deleted while waiting).



  Wait for Pixel
 

Pauses execution until a pixel color appears on the screen. The pixel can appear anywhere on the screen. Searching for pixel colors is much faster than searching for entire images.

This pause is useful for images that have distinct colors that are not common. The color white, for example, would be a poor choice since it is very common on the screen.


  Wait for Image to Appear
 

Searches the entire screen for an image. Only the visible screen will be checked - if an image is hidden beneath a window, it will not be found. The maximum size of the search bitmap is 1024 x 1024 pixels.

For more information concerning bitmaps and images, see the Using Images section.


  Wait for Clipboard
 

Pauses execution until data in the clipboard conforms to a specified format. The following clipboard match options are available:

Match ConditionDescription
Exact Text The provided text must match in length and case
Partial Text The provided text must exist somewhere inside of the clipboard, and is case insensitive
Any Text Passes as soon as the clipboard is not empty
When Empty Passes as soon as the clipboard does not contain any data



  Wait for Screen Saver
 

Pauses execution until the screen saver becomes active.
Screen saver activation is configured in the Windows Control Panel.


  Wait For Idle
 

Pauses execution of the script until no user interaction occurs for the mouse, keyboard, or window placement.

For maximum efficiency and portability, this action does not internally utilize various "polling" methods to check user idle time, such as Windows system-level notifications. Unlike most other programs, vTask does not rely on separate modules or external system dependencies to complete the "Wait for Idle" action. As a result, it is able to focus on the mouse and keyboard alone for user idle time.

*Tip:  Be sure to have the Timeout value greater than the Interval time value, so that the Wait for Idle command executes properly. If you have a timeout value that is shorter than the Idle Interval value, this wait command will never be idle long enough to actually complete. By design, vTask will not override your timeout settings so the appropriate value is larger.



  Wait For Restart
 

Pauses execution of the script until the computer is restarted. When this action is run, the script terminates at this step, and will resume execution at the next step after the computer is restarted.

Restart OptionDescription
Temporary (single) The script is paused until the next restart.
No future restarts will run the script, unless the script is manually started again.
Permanent (every restart) The script is run on every restart of the computer.
It does not need to be manually restarted again.
To remove this setting, either change the option and run the script, or choose the "Remove Pending Restarts" option.
Never (remove pending) Performs no action other than removing any pending restart requests by vTask (either temporary or permanent)


Only a single file of the same base name can be a pending restart script. For example, it is not possible to run both "C:\Folder1\MyScript.vxm" and "C:\Folder2\MyScript.vxm" at the same time.