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 temporarily hang. To process messages while waiting, use opt waitmsg.

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.

Tips

To minimize CPU usage when waiting for a window, use window class name, because finding a window by class name is much faster. For example, to wait for Internet Explorer, instead of wait 0 "Internet Explorer" use wait 0 "+IEFrame" or wait 0 win("Internet Explorer" "IEFrame"). Also, don't use flag 0x800 with win.

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 key

[wait ]timeS event [keycode]

event:

Wait for key up event.

Wait for key down event, and filter (eat) 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.

On Vista, 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.

On Vista, 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: as specified in Options (default is 20 %).

Macro that contains "wait for CPU" commands, or opt waitcpu 1, sometimes may run very slowly or produce "wait timeout" errors. This is because some programs constantly or occasionally use 100% 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 the handle is invalid (before QM 2.2.0 was 0).

wait uses Windows wait functions ([Msg]WaitForMultipleObjects) that modify object's state on success. For example, on successful wait for an auto-reset event, wait resets it. Or, on successful wait for a mutex, the thread owns the mutex. You should not use these functions (unless with 0 or very small timeout) because then QM cannot properly end the thread on user request, and also cannot apply opt waitmsg.

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") ;;a __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") ;;don't use  __Handle variables with QM thread handles
wait 0 H hThread

 Create event and wait until other thread sets it:
 ______Thread1_______
int+ 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.

h1-h4 - handles of synchronization objects.

Waits until one of the objects becomes signaled.

Returns index of the first signaled handle + 1. Returns -1 if a handle is invalid.

Waiting for all handles is not supported.

Example

 Wait until one of two events is set:
int+ 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

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, window, flags - same as with pixel.

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), list (list box), ShowDialog (custom dialog).

Wait for accessible object: acc. Specify the wait time in the 'Find Accessible Object' dialog.

Wait for html element: 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).

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.

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(dir(file1)) break
	if(dir(file2)) break
	0.5