int scan(file [window] [rect] [flags] [colorDiff] [matchIndex|array])
wait timeS [-]S file [window] [rect] [flags] [colorDiff] [matchIndex|array]
file - image to search for. It can be:
window - top-level or child window, in which to search. Can be omitted or 0 (literal) to search in whole screen. Use "" for active window.
rect - variable of type RECT. Can be used to limit the search region. When scan returns, rect contains location of the found image (in screen coordinates, unless flag 0x200 used). Default: 0.
| 1 | Move the mouse pointer to the image. This flag not used with flag 0x200 and -S. |
| 2 | Error if image not found. This flag not used with wait. |
| 4 | Use the top-left pixel color of the image as transparent color. |
| 16 | Search only in the client area. If rect specifies the search region, it must be relative to the client area. This flag is used only if window is used. |
| 32 | When file is icon file, use large icon (32x32). Default - small icon (16x16). |
| 64 | If file is handle or resource, use this flag to specify that it is icon. |
| 128 | QM 2.3.2. Use rect for results, but not to limit the search region. |
| 0x100 | QM 2.3.2. Search in background window. On Windows 2000 this feature is unavailble and this flag is ignored. |
| 0x200 | QM 2.3.2. Search in bitmap stored in memory. window must be bitmap handle. |
| 0x400 | QM 2.3.2. When found, wait until mouse buttons released. It is more useful with wait and flag 1 (move mouse). |
colorDiff (QM 2.3.2) - maximal allowed color/brightness difference of the on-screen image. Allows to find images that don't match exactly. Can be 0-255, but should be as small as possible.
matchIndex (QM 2.3.2) - 1-based index of matched image. 0 is same as 1. Use when there are several matching images in the search area and you need not the first one.
array (QM 2.3.3) - variable of type ARRAY(RECT) that will receive coordinates of all matching images.
timeS - max time (seconds) to wait. Error on timeout. If <=0, waits infinitely.
S - literal S.
scan searches for an image on the screen. Returns 1 if found, 0 if not (or throws error if flag 2 is set).
wait waits for an image on screen. Almost everything is the same as with scan, therefore in the following text "the function" means "scan and wait".
To insert the function, you can use the Find Image dialog. You can capture the image. When you click OK, the image is saved.
The function is time-consuming. You can minimize the search time by limiting the search region. To limit the search region, specify window. Even better if it is a control. Don't forget to specify window if you are working with multiple monitors, or the function will search in whole virtual screen (in all monitors). You can use perf to measure the search time.
To limit the search region you also can use rect (variable of type RECT). If window is used, the rectangle specified in rect must be relative to the window/control. To just compare (don't search), set rect to exactly mach the on-screen image.
If you use rect for results but don't want to limit the search region, it must be initially empty (all members 0). Or use flag 128. With flag 0x200 rect also is used only for results.
If flag 0x100 or 0x200 not used, the function can only find images that are visible on the screen. If window is used, make sure that the window is not obscured by other windows. The function does not test whether the image belongs to the window. You can use act to activate the window.
The function can only find images that exactly match the image in file. If you use colorDiff, it can find images with slightly different colors and brightness. It cannot find images with different shapes.
The function may fail after you apply new theme, color scheme, skin, etc, because the background color may change. To make the function independent from such changes, try flag 4. Then it does not evaluate pixels that have the same color as the top-left pixel of the captured image. Usually it is background color, so if background will change in the future, the function will not fail. Icons usually already have transparent areas, so this is only useful with bitmap files. The function also may fail after you change display color resolution. The function may not find icons in some controls because they slightly change icon colors. Also it will fail to find captured text after changing font smoothing.
QM 2.2.1: The function can find most alpha-blended icons.
With icons you should always use colorDiff. Recommended 8. Because icons often are displayed with slightly different colors than in the icon file.
QM 2.2.1: Icon index can be specified, e.g. "shell32.dll,5".
Instead of a file, can be used bitmap or icon handle, ie when the bitmap or icon is loaded in memory. These functions can be used to get handle: LoadImage, LoadPictureFile, GetFileIcon, GetWindowIcon, CaptureImageOnScreen, CaptureImageOrColor. Later use DeleteObject for bitmap or DestroyIcon for icon.
QM 2.3.2: If flag 0x100 used, the function can search in window that is obscured by other windows or offscreen. The speed depends on window, and with some windows can be several times slower or faster than without this flag. Does not find images in some windows, window parts and controls: transparent windows, window caption and other glass parts (Vista/7), thumbnail windows (Vista/7), windows of higher integrity level processes (Vista/7), hidden and minimized windows (but you can use wait until the window is visible), and some other.
QM 2.3.2: If flag 0x200 used, the function searches in bitmap whose handle is passed as argument 2 (window). The bitmap can be loaded using LoadPictureFile or other function (see above), and later must be deleted using DeleteObject. Must not be selected into a DC. Always searches in whole bitmap, regardless of rect. Searching in bitmap is much faster because the slowest part is getting pixels from screen or window.
Error if:
The RECT type is used to specify a rectangle.
type RECT left top right bottom
left and top - top-left corner coordinates.
right and bottom - bottom-right corner coordinates. This point actually is outside the rectangle. Rectangle width is right-left. Height is bottom-top.
See also: wait for image, id, child, acc, htm, pixel.
Find picture "test.bmp" in "Abc" window. If found, click, else generate error: scan "test.bmp" "Abc" 0 1|2 lef Find picture in window, and get its location: RECT r if(scan("test.bmp" "Abc" r)) out "x=%i y=%i width=%i height=%i" r.left r.top r.right-r.left r.bottom-r.top else out "not found" Find picture in specified rectangle region, and get its location: RECT r; r.left=100; r.top=100; r.right=300; r.bottom=300 if(scan("test.bmp" 0 r)) out "x=%i y=%i width=%i height=%i" r.left r.top r.right-r.left r.bottom-r.top else out "not found" Wait for picture max 10 s: wait 10 S "test.bmp" "Abc"