Wait for

Can be used as function, e.g. variable=wait(...). The return value depends on event. If not specified, returns 1. If opt waitmsg is set, returns 0 if the thread receives WM_QUIT message.

Note: If the thread has windows/dialogs or uses COM events or some Windows API functions that use Windows messages, you should avoid wait commands in it. Or use small time (<0.1). By default, messages are not processed while waiting, and your thread may hang. To process messages while waiting, use opt waitmsg.

Note: Don't use Windows API wait functions, because then QM cannot properly end the thread on user request. QM then terminates thread, which causes a big memory leak and possibly more bad things. Also, opt waitmsg is not applied.

QM 2.4.0. wait uses alertable waiting. For example, QueueUserAPC can be used to run a function in the waiting thread.

Wait for window

[wait ]timeS event window

event:

WA	Wait until window is active, visible and not minimized. If window does not exist, at first waits until it is created. Returns window handle. WA is optional. See also: run.
-WA or WN	Wait until window is deactivated or destroyed. Does not wait if window is already inactive or does not exist. Returns handle of the active window.
WC	Wait until window is created. Does not wait if window already exists. Returns window handle.
-WC or WD	Wait until window is destroyed. Does not wait if window does not exist. Returns handle of the active window.
WP	Wait until window's program exits. Does not wait if window does not exist. Returns handle of the active window. See also: run.
WV	Wait until window is visible. If window does not exists, at first waits until it is created. Returns window handle.
-WV	Wait until window is hidden or destroyed. Does not wait if window does not exist. Returns window handle. If window does not exist, returns 1.
WE	Wait until window is enabled. If window does not exists, at first waits until it is created. Returns window handle.
-WE	Wait until window is disabled or destroyed. Does not wait if window does not exist. Returns window handle. If window does not exist, returns 1.
WAI	Wait until one of windows is active, visible and not minimized. window is list of windows, like "Notepad[]WordPad". Returns 1-based window index in the list.

window - window. Can be child window.

Examples

 Wait for window "Notepad" max. 5 seconds; on timeout error:
wait 5 WA "Notepad"
 or (WA can be omitted):
wait 5 "Notepad"
 or (wait can be omitted):
5 WA "Notepad"
 or (WA and wait can be omitted):
5 "Notepad"

 Wait for window "Notepad" max. 5 seconds; on timeout continue:
wait WA 5 "Notepad"; err

 Wait max 5 s for window "Notepad"; on timeout run macro "Open":
wait 5 WA "Notepad"
err
	mac- "Open"

 Wait until window "Notepad" is closed:
wait 0 -WC "Notepad"

 Wait until window with name "Calc" and class "SciCalc" is created:
wait 0 WC win("Calc" "SciCalc")

 Wait until control with id 1500 in window "Window" becomes enabled:
wait 0 WE id(1500 "Window")

 Wait for window "Notepad" max. 5 seconds; store window handle into variable:
int hwnd = wait(5 WA "Notepad"); err

 Wait until currently active window is deactivated (another window  becomes active); return handle of another window:
int hwnd = wait(5 -WA "")

 Wait for message "Error" or "Warning" that belongs to "APP" program:
int hwnd = wait(5 win("Error[]Warning" "#32770" "APP" 16))

Wait for window name

[wait ]timeS event handle name [flags]

event:

WT	Wait until window name is name.
-WT	Wait until window name is other than name.

handle - window handle.

name - name to wait for. Can be partial.

flags:

1	name is full or with wildcard characters (*?).
2	name is regular expression.
4	name case insensitive.

Added in QM 2.3.4.

Wait for key

[wait ]timeS event [keycode]

event:

Wait for key up event.

Wait for key down event.

Unlike K, it "eats" the keyboard event. The active window will not receive it.
Not available in exe.

keycode - single QM key code. Optional.

If keycode is omitted, waits for any key.
keycode also can be string variable in parentheses (QM key code), or numeric value in parentheses (virtual-key code).

Returns virtual-key code.

UAC: does not work if QM runs as standard user and the active window has higher integrity level.

Examples

 Wait for key F12:
wait 0 K F12

 Wait for any key, eat the key, and display virtual-key code:
int vk = wait(0 KF)
out vk

Wait for mouse

[wait ]timeS event

event:

ML	Wait for left mouse button up event. Returns 1.
MR	Wait for right mouse button up event. Returns 2.
MM	Wait for middle mouse button up event. Returns 4.
M	Wait for any mouse button up event. Returns mouse button code: 1 left, 2 right, 4 middle, 5 X1, 6 X2.

Does not "eat" the mouse event. The active window will receive it.

UAC: does not work if QM runs as standard user and the active window has higher integrity level.

Wait for CPU

[wait ]timeS event [threshold]

event:

Wait until CPU usage is less than threshold.

threshold must be 1 to 100.

-P

Wait until CPU usage is more than threshold.

threshold must be 0 to 99.

threshold - % CPU usage. Default: 20 % or as set with RtOptions.

Use carefully. Some programs constantly use CPU, even when they are ready for input.

See also: GetCPU.

Example

 Run program and max. 15 seconds wait until CPU usage is less than 20%:
run "app.exe"; wait 15 P 20

Wait for handle

[wait ]timeS H handle

handle - synchronization object handle.

Waits until the object becomes signaled. For example, can wait until another thread exits (see examples).

Returns 1.

Returns -1 if a handle is invalid.

wait H/HM/HMA uses Windows API wait functions ([Msg]WaitForMultipleObjectsEx) that modify object's state on success. For example, on successful wait for an auto-reset event, wait resets it; on successful wait for a mutex, the thread owns the mutex; if the mutex was abandoned, wait calls SetLastError(128). Don't use Windows API wait functions directly (unless with 0 or very small timeout) because then QM cannot properly end the thread on user request, and also cannot apply opt waitmsg.

Tip: Use variables of type __Handle to store handles to be automatically closed with CloseHandle when the variable dies. Don't close QM thread handles.

Tip: To wait for a mutex, see also lock.

Examples

 Run notepad and wait until it exits (just example of wait 0 H; use run with flag 0x400 instead):
__Handle hProcess=run("notepad.exe") ;;the __Handle variable will close the handle
wait 0 H hProcess

 Run function "Function" in separate thread and wait until it exits:
int hThread=mac("Function") ;;note: don't use  __Handle variables with QM thread handles
wait 0 H hThread

 Create event and wait until another thread sets it (SetEvent):
 ______Thread1_______
__Handle+ g_hevent; if(!g_hevent) g_hevent=CreateEvent(0 0 0 0)
wait 60 H g_hevent
 ______Thread2_______
SetEvent(g_hevent)

Wait for multiple handles (QM 2.2.0)

[wait ]timeS HM ha

[wait ]timeS HM h1 h2 [h3] [h4]

ha - variable of type ARRAY(int), containing up to 60 handles of synchronization objects.

QM 2.4.0. Also can be ARRAY(__Handle).

h1-h4 - handles of synchronization objects. Can be of type int or __Handle.

If HM used, waits until one of the objects becomes signaled. Returns 1-based index of the first signaled handle.

If HMA used (added in QM 2.4.0), waits until ALL the objects are signaled. Returns 1.

Returns -1 if a handle is invalid.

Tip: Use variables of type __Handle or ARRAY(__Handle) to store handles to be automatically closed with CloseHandle when the variable dies. Don't close QM thread handles.

Examples

 Create two event objects and wait until one of them is set (SetEvent)
__Handle+ g_e1 g_e2
if(!g_e1) g_e1=CreateEvent(0 0 0 0)
if(!g_e2) g_e2=CreateEvent(0 0 0 0)
int i=wait(0 HM g_e1 g_e2)
out i

 Start three notepad processes and wait until all closed
ARRAY(__Handle) a
rep 3
	a[]=run("notepad.exe")
wait 0 HMA a

Wait for variable

[wait ]timeS event variable

event:

V	Wait until the variable becomes nonzero.
-V	Wait until the variable becomes 0.

variable - variable of type int.

Returns the final value of the variable.

Wait for web page

[wait ]timeS I [url]

url - wait for this URL. If omitted, waits while browser is busy.

Waits until web page is finished loading and web browser isn't busy.

Works only in Internet Explorer and IE-based web browsers.

Note: Waits only in single window. If, while waiting, the page is opened in a new window, ignores the new window.

See also: web.

Wait for cursor (mouse pointer)

[wait ]timeS event cursor

event:

CU	Wait for the cursor.
-CU	Wait until the cursor disappears.

cursor - one of:

Standard cursor identifier, such as IDC_ARROW.
QM 2.3.2. Custom cursor identifier, recorded in the Wait dialog.

Wait for color

[wait ]timeS event color x y [window] [flags]

event:

C	Wait for the specified pixel color in the specified point in window or screen (if window is 0 or omitted).
-C	Wait until pixel color will change from the specified color.

x y - coordinates.

window - top-level or child window. If omitted or literal 0, x and y are screen coordinates.

flags:

1	x y are relative to the top-left corner of window's client area or of the work area.
2	Activate window. Restore if minimized. Error if point x y does not belong to window or its top-level parent window. No error with flag 0x1000.
0x1000	QM 2.4.3. Get pixel color directly from window, not from screen. The same as scan flag 0x1000. This flag is ignored if window not used or if Windows Aero theme is not enabled or window is DPI-scaled.

See also: pixel, scan.

Wait for image on screen

[wait ]timeS event file [window] [rect] [flags] [colorDiff] [matchIndex]

event:

S	Wait for image.
-S	Wait until image disappears

file, window, rect, flags, colorDiff, matchIndex - same as with scan.

QM 2.3.2. Added more features.

Tips

Waiting for image (S, -S) in large region (whole screen or window) consumes significant amount of CPU time. If during that time other application performs some processing, QM may slow down it. If processing speed is important, you can view CPU usage of qm.exe, and, if it is too high, minimize it by minimizing the search region (read more). While waiting, QM periodically searches for the image. If speed (spe) is 0, the rate is much higher.

To see CPU usage, use Windows Task Manager or perfmon.exe. You can also use GetCPU function.

Wait for other events

Wait for user input: mes (message box), inp (input box), ShowDialog (custom dialog), ListDialog and other dialogs.

Wait for accessible object (text, link, button, etc): acc. Specify the wait time in the 'Find Accessible Object' dialog.

Wait for html element (web page objects in Internet Explorer): htm. Specify the wait time in the 'Find Html Element' dialog.

Wait for image: scan. Select 'Wait for' in the 'Find Image' dialog.

Run program and wait for: run. Use the 'Run Program' dialog.

Open web page and wait for: web. Use the 'Open Web Page' dialog.

Waiting for other events can be implemented with rep. To create new "wait for" user-defined functions, you can use WaitFor template (menu File -> New -> Templates).

Examples


 Wait for some condition that is not supported by wait:
rep() if(condition) break; else 0.1

 Wait for mouse left button down:
rep() 0.01; ifk((1)) break

 wait for one of two files
str file1="$personal$\file1.txt"
str file2="$personal$\file2.txt"
rep
	if(FileExists(file1)) break
	if(FileExists(file2)) break
	0.5