int scan(file [window] [rect] [flags])
file - bitmap (.bmp) or icon (.ico and other) file that contains the image to search for. It also can be handle (if numeric), or exe resource id (if begins with semicolon, e.g. ":1" or ":2 file.bmp").
window - top-level or child window, in which to search. Can be omitted or 0 (constant).
rect - variable of type RECT. Can be used to limit the search region. When scan returns, contains the location of the found image. Default: 0.
flags - combination of the following values. Default: 0.
| 1 | Move the mouse pointer to the image. |
| 2 | Generate error if image not found. |
| 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. |
Searches for an image on the screen. Returns 1 if found, 0 if not (or throws error if flag 2 is set). If flag 1 is used, moves the mouse pointer to the found image. If rect is used, populates the variable with the screen coordinates of the found image.
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. To limit more, use rect (variable of type RECT). If window is used, the rectangle specified in rect must be relative to the window. To perform just comparison, set rect to exactly mach the position and dimensions of the image. If you don't want to limit the search region, you can omit rect, or use 0, or use an empty RECT variable (all members are 0). Then the function will search whole screen or window. Or, only some members can be specified, and the function will automatically fill the remaining members. 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 the perf function to measure the search time.
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 captured image (image in file). It will not find images with different colors or shapes.
The function may fail after you apply new theme, color scheme, skin, etc. This is because the background color may change. To make the function independent from such changes, use flag 4. Then it does not evaluate pixels that have the same color as the top-left pixel of the captured image. Usually this 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.
QM 2.2.1: The function also finds most alpha-blended icons.
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. If used handle, scan does not destroy the bitmap or icon. QM 2.2.1: Fixed bug where the function fails if file is handle and flags not used.
The function generates error if:
- file not found, or picture cannot be extracted, or resource does not exist.
- window not found.
- object (picture) not found. Only if flag 2 is set.
- failed (an unexpected error, such as invalid handle or low memory).
The RECT type is used to specify a rectangle. Definition:
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, 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"