Find window (get handle); compare properties

Syntax1 - specified window

int win(name [class] [exename] [flags] [propCSV] [matchindex|array])
int wintest(hwnd name [class] [exename] [flags] [propCSV])

 

Before QM 2.3.4 used this instead.

Instead of propCSV used two parameters x y and several additional flags.

 

int win(name [class] [exename] [flags] [x y] [matchindex|array])
int wintest(hwnd name [class] [exename] [flags] [x y])

 

x y - used for multiple purposes, depending on flags. Default: the window must contain this point in screen.

 

These flags can be used to change x y meaning:

64 x is handle of owner window.
128 x is style.
0x100 y is extended style.
0x8000 x and y used to specify a callback function and a value to pass to it.

 

 

Syntax2 - window from point

int win(x y [workarea])
int wintest(x y [workarea])

 

Syntax3 - window from mouse position

int win(mouse)
int wintest(hwnd mouse)

 

Syntax4 - the active window

int win

 

Parameters

name - window title.

class - window class name.

exename - program. Default: "" (any). Can be:

flags:

1

name is full or with wildcard characters (*?).

  • For example, if window name must end with " - Notepad", use "* - Notepad" and flag 1. If it must be exactly "Notepad", use "Notepad" and flag 1.
  • String "*" matches windows with no name.
2 name is case insensitive.
4 Window must not be popup.
8 Window must be popup.
16 name is list of names.
32 exename is owner window. Can be handle, name or +classname.
0x200 name is regular expression.
0x400

Must be visible. It is default if class is not specified, unless used opt hidden 1 before. It isn't default for wintest.

propCSV - list of other properties in format "name1=value1[]name2=value2[]...". It is CSV string with separator =. Default: "".

name value
owner

Owner window handle. Example:

F"owner={hwndOwner}"
xy

x and y coordinates of a point in screen that the window must contain. Examples:

"xy=100 50"
"xy=0.9 0.1" ;;near top-right
style

Style, optionally followed by a mask. Examples:

"style=0x54032000" ;;must have exactly this style
F"style=-1 {WS_DISABLED}" ;;must be disabled
F"style=0 {WS_DISABLED}" ;;must not be disabled
exStyle Extended style, optionally followed by a mask.
cClass, cText, cId, cFlags

The window must have the specified control. Parameters are as with child, all optional. Example:

"cClass=Static[]cText=Example*[]cFlags=1"
GetProp

The window must have the specified window property. Property name, optionally followed by value. If only name, value can be any nonzero. Read more.

Window properties is a Windows feature that allows applications to assign named values to windows. A macro also can set window properties. Use function SetProp. Name can be any string without spaces. Value - any nonzero number. Use SetProp carefully, don't use many names, or applications may stop working. Property names are used by many applications, and the number of names is limited. Remove with RemoveProp when don't need.
callback

Address of a callback function, optionally followed by a value to pass to it. Example:

F"callback={&Function} {aValue}"

threadId

(QM 2.4.2)

Thread id.

Some functions to get it: GetCurrentThreadId, GetWindowThreadProcessId, GetQmThreadInfo.
processHandle (QM 2.4.2)

Process handle. Example:

__Handle hp=run("notepad.exe")
int w=wait(30 WC win("" "Notepad" "" 0 F"processHandle={hp}"))

Note: it is not the same as process id. If you have id, pass it as the exename argument instead.

matchindex (QM 2.2.0) - 1-based index of matched window. Use when there are several windows that match other properties (name, class, etc).

array (QM 2.2.1) - variable of type ARRAY(int) that will receive handles of all matching windows. See also GetMainWindows.

 

x, y (syntax2) - a point in screen.

workarea (syntax2) - if nonzero, coordinates are relative to the work area (the screen area used for a maximized window).

mouse (syntax3) - literal mouse.

hwnd (wintest) - handle of window to test.

 

Remarks

win returns top-level window handle. If window not found, returns 0.

 

The handle then can be passed to any function that has a window parameter.

 

To test window visibility, the function calls IsWindowVisible, and does not call IsWindowCloaked. For example, it can find inactive Windows 8 app windows and windows on inactive Windows 10/11 virtual desktops.

 

wintest compares window (hwnd) properties with the specified properties, and returns 1 if they match, or 0 if not. WIth flag 16 returns 1-based index in the list. Error if hwnd is 0 or invalid. See also WinTest.

 

Tips

To create code for win, use dialog "Find window or control". Or press Ctrl+Shift+Alt+W, it shows a menu that creates code for some window functions. Recording and various other dialogs also create code with win.

You can see window class, name and exename in QM status bar. Also you can use dialog "Explore windows", it shows more window properties.

 

Examples

int h = win ;;active window
h = win("Notepad") ;;name "Notepad"
h = win("Find" "#32770" "NOTEPAD" 1|0x400) ;;name "Find", class "#32770", program "notepad", name must match exactly, must be visible
h = win("" "Notepad" "" 0 "xy=100 100") ;;class "Notepad", must be at 100x100 pixels in screen
h = win(200 0.5) ;;window that is at 200 pixels horizontally and half of screen height vertically
act win(mouse) ;;activate window that is at the mouse position
 
int h=win
sel wintest(h "Visual[]Quick" "" "" 16)
	case 1 out "Visual"
	case 2 out "Quick"
	case 0 out "other"

out
ARRAY(int) a; int i; str sc sn
out "[][9]ALL VISIBLE WINDOWS"
win("" "" "" 0 0 0 a)
for(i 0 a.len)
	sc.getwinclass(a[i])
	sn.getwintext(a[i])
	out "%i '%s' '%s'" a[i] sc sn

out "[][9]ALL INVISIBLE WINDOWS"
opt hidden 1
win("" "" "" 0 0 0 a)
for(i 0 a.len)
	if(!hid(a[i])) continue ;;this window is visible
	sc.getwinclass(a[i])
	sn.getwintext(a[i])
	out "%i '%s' '%s'" a[i] sc sn

out "[][9]ALL WINDOWS OF EXPLORER"
opt hidden 1
win("" "" "explorer" 0 0 0 a)
for(i 0 a.len)
	sc.getwinclass(a[i])
	sn.getwintext(a[i])
	out "%i '%s' '%s'" a[i] sc sn