Struct wnd

A variable of wnd type represents a window or control. It is a window handle, also known as HWND.

public struct wnd : IEquatable<wnd>, IComparable<wnd>

Remarks

wnd functions can be used with windows and controls of any process/thread. Also can be used with .NET form/control and WPF window class variables, like wnd w=form.Hwnd(); w.Method(...);.

There are two main types of windows - top-level windows and controls. Controls are child windows of top-level windows.

More window functions are in types named like WndX, in namespace Au.More. They are used mostly in programming, rarely in automation scripts.

What happens when a wnd member function fails:

Functions that get window properties don't throw exceptions. They return false/0/null/empty. Most of them support lastError, and it is mentioned in function documentation.
Many functions that change window properties throw exception. Exceptions are listed in function documentation. Almost all these functions throw only AuWndException.
Other functions that change window properties return false. They are more often used in programming than in automation scripts.
When a "find" function does not find the window or control, it returns default(wnd) (window handle 0). Then wnd.Is0 will return true.
If a function does not follow these rules, it is mentioned in function documentation.

Many functions fail if the window's process has a higher UAC integrity level (administrator, uiAccess) than this process, unless this process has uiAccess level. Especially the functions that change window properties. Some functions that still work: Activate, ActivateL, ShowMinimized, ShowNotMinimized, ShowNotMinMax, Close.

The wnd type can be used with native Windows API functions without casting. Use wnd for the parameter type in the declaration, like [DllImport(...)] static extern bool NativeFunction(wnd hWnd, ...).

Examples

wnd w = wnd.find("* - Notepad");
if(w.Is0) { print.it("window not found"); return; }
w.Activate();
wnd c = w.Child(cn: "Button");
print.it(c.Name);

Namespace: Au

Assembly: Au.dll

Constructors

Name	Description
wnd(nint)

Properties

Name	Description
ClassName	Gets window class name.
ClientRect	Gets client area rectangle (width and height).
ClientRectInScreen	Gets client area rectangle (width and height) in screen.
CommonControlType	If this control is (or is based on) a standard control provided by Windows, such as button or treeview, returns the control type. Else returns None.
ControlId	Gets or sets id of this control. The `get` function supports lastError.
ControlText	Gets control text.
Elm	Gets an elmFinder for finding UI elements in this window or control. Example: `var e = w.Elm["ROLE", "Name"].Find();`. Example: `var e = w.Elm["ROLE1", "Name1"]["ROLE2", "Name2"]["ROLE3", "Name3"].Find();`. Example: `print.it(w.Elm.FindAll());`.
ExStyle	Gets window extended style.
Get	Gets related windows and controls. Use like `wnd w2 = w1.Get.Owner;` (here w1 is a wnd variable).
Handle	Gets window handle as IntPtr. Code `w.Handle` is the same as `(IntPtr)w` .
Is0	Returns `true` if the window handle is 0 (this variable == `default(wnd)`).
Is32Bit	Returns `true` if the window is of a 32-bit process, `false` if of a 64-bit process. Also returns `false` if failed. Supports lastError.
IsActive	Returns `true` if this window is the active (foreground) window.
IsAlive	Returns `true` if the window exists (the window handle is valid). Returns `false` if the handle is 0 or invalid. Invalid non-0 handle usually means that the window is closed/destroyed.
IsChild	Returns `true` if this is a child window (control), `false` if top-level window.
IsCloaked	Returns `true` if the window is cloaked. Returns `false` if not cloaked or if failed. On Windows 7 returns `false` because there is no "cloaked window" feature. Windows 10 uses window cloaking mostly to hide windows on inactive desktops. Windows 8 - mostly to hide Windows Store app windows.
IsCloakedGetState	Gets the cloaked state.
IsConsole	Returns `true` if this is a console window (class name `"ConsoleWindowClass"`).
IsFocused	Returns `true` if this is the control or window that has the keyboard input focus.
IsFullScreen	Returns `true` if this is a full-screen window and not desktop.
IsHung	Returns `true` if thread of this window is considered hung (not responding). Calls API IsHungAppWindow.
IsHungGhost	Returns `true` if the window is a ghost window that the system creates over a hung (not responding) window to allow the user to minimally interact with it.
IsMaximized	Returns `true` if maximized, `false` if not. Also returns `false` when fails (probably window closed or 0 handle). Supports lastError. Calls API IsZoomed.
IsMessageOnly	Returns `true` if this is a message-only window.
IsMinimized	Returns `true` if minimized, `false` if not. Also returns `false` when fails (probably window closed or 0 handle). Supports lastError. Calls API IsIconic.
IsOfThisProcess	Returns `true` if this window belongs to the current process, `false` if to another process. Also returns `false` when fails (probably window closed or 0 handle). Supports lastError. Calls API GetWindowThreadProcessId.
IsOfThisThread	Returns `true` if this window belongs to the current thread, `false` if to another thread. Also returns `false` when fails (probably window closed or 0 handle). Supports lastError. Calls API GetWindowThreadProcessId.
IsPopupWindow	Returns `true` if has WS.POPUP style.
IsResizable	Returns `true` if has WS.THICKFRAME style.
IsToolWindow	Returns `true` if has WSE.TOOLWINDOW style.
IsTopmost	Returns `true` if this is a topmost (always-on-top) window.
IsUnicode	Returns `true` if the window is a Unicode window, `false` if ANSI. Also returns `false` when fails (probably window closed or 0 handle). Supports lastError. Calls API IsWindowUnicode.
IsUwpApp	On Windows 10 and later returns non-zero if this top-level window is a UWP app window: 1 if class name is `"ApplicationFrameWindow"`, 2 if `"Windows.UI.Core.CoreWindow"`.
IsVisible	Returns `true` if the window is visible. Returns `false` if is invisible or is a child of invisible parent. Also returns `false` when fails (probably window closed or 0 handle). Supports lastError.
IsVisibleAndNotCloaked	Returns `true` if wnd.IsVisible returns `true` and wnd.IsCloaked returns `false`.
IsWindows8MetroStyle	Returns `true` if this window has Metro style, ie is not a classic desktop window. On Windows 8/8.1 most Windows Store app windows and many shell windows have Metro style. On Windows 10 few windows have Metro style. On Windows 7 there are no Metro style windows.
MouseClientXY	Returns mouse pointer position relative to the client area of this window.
Name	Gets name.
NameElm	Gets elm.Name of the UI element (role WINDOW) of this window or control.
NameWinforms	Gets the Control.Name property value of a .NET Windows Forms control.
ProcessId	Gets native process id of this window. Calls API GetWindowThreadProcessId.
ProgramDescription	Gets description of process executable file.
ProgramName	Gets filename of process executable file, like `"notepad.exe"`.
ProgramPath	Gets full path of process executable file.
Prop	Returns an object that manages window properties using API SetProp and co.
Rect	Gets rectangle (position and size) in screen coordinates.
RectInDirectParent	Gets child window rectangle in the client area of the direct parent window.
RectInWindow	Gets child window rectangle in the client area of the top-level parent window.
Screen	Gets screen of the screen that contains this window (the biggest part of it) or is nearest to it. If this window handle is `default(wnd)` or invalid, gets the primary screen. Calls screen.of.
Style	Gets window style.
TaskbarButton	Returns an object that manages the taskbar button of this window: flash, progress, add/delete.
ThreadId	Gets native thread id of this window. Calls API GetWindowThreadProcessId.
Uac	Gets UAC info of the process.
UacAccessDenied	Returns `true` if UAC would not allow to automate the window. It happens when current process has lower UAC integrity level and is not uiAccess, unless UAC is turned off.
Window	Gets the top-level parent window of this control. If this is a top-level window, returns this.
active	Gets the active (foreground) window. Calls API GetForegroundWindow.
focused	Gets the control or window that has the keyboard input focus.

Methods

Name	Description
Activate()	Activates this window. Also makes it visible and not minimized. The active window is in the foreground and receives keyboard and mouse input.
ActivateL(bool)	Lightweight version of wnd.Activate. Does not throw exceptions.
ButtonClick(int)	Finds and clicks a button in this window. Does not use the mouse.
ButtonClick(string, bool, string)	Finds and clicks a button in this window. Does not use the mouse.
Child(Seconds, string, string, WCFlags, int?, Func<wnd, bool>, int)	Finds a child control and returns its handle as wnd. Can wait and throw NotFoundException.
Child(string, string, WCFlags, int?, Func<wnd, bool>, int)	Finds a child control and returns its handle as wnd.
ChildAll(string, string, WCFlags, int?, Func<wnd, bool>)	Finds all matching child controls.
ChildFast(int)	Finds a direct child control by its id and returns its handle as wnd.
ChildFast(string, string, wnd)	Finds a direct child control by name and/or class name and returns its handle as wnd.
ChildFromXY(Coord, Coord, WXYCFlags)	Gets descendant control from point.
ChildFromXY(POINT, WXYCFlags)	Gets descendant control from point.
ClassNameIs(params ReadOnlySpan<string>)	If window class name matches one of strings in classNames, returns 1-based string index. Else returns 0. Also returns 0 if fails to get class name (probably window closed or 0 handle). Supports lastError.
ClassNameIs(string)	Returns `true` if the class name of this window matches cn. Else returns `false`. Also returns `false` when fails (probably window closed or 0 handle). Supports lastError.
Close(bool, bool)	Closes the window.
CompareTo(wnd)	Implements IComparable. It allows to sort a collection.
ContainsScreenXY(Coord, Coord)	Returns `true` if this window (its rectangle) contains the specified point.
ContainsWindowXY(Coord, Coord)	This overload calls ContainsWindowXY(wnd, Coord, Coord) with wnd.Window, x and y.
ContainsWindowXY(wnd, Coord, Coord)	Returns `true` if this control (its rectangle) contains the specified point in parent window.
Enable(bool)	Enables or disables. Calls API EnableWindow.
EnsureInScreen(screen, bool)	Moves this window if need, to ensure that entire window is in that screen.
Equals(wnd)	Returns `true` if `other == this`.
Equals(wnd?)	Returns `true` if `w != null` and `w.Value == this`.
Equals(object)	Returns `true` if obj is wnd and contains the same window handle.
Focus()	Sets the keyboard input focus to this control. Also activates its top-level parent window (see wnd.Activate).
GetClientRect(out RECT, bool)	Gets client area rectangle.
GetHashCode()
GetRect(out RECT, bool)	Gets rectangle (position and size) in screen coordinates.
GetRectIn(wnd, out RECT)	Gets rectangle of this window (usually control) relative to the client area of another window (usually parent).
GetRectNotMinMax(out RECT)	Gets rectangle of normal (restored) window even if currently it is minimized or maximized.
GetText(bool?, bool)	Gets window/control name or control text. This is a low-level function. You can instead use wnd.Name and wnd.ControlText.
GetThreadProcessId(out int)	Gets native thread id and process id of this window. Calls API GetWindowThreadProcessId.
GetTransparency(out int?, out ColorInt?)	Gets window transparency attributes (opacity and transparency color).
GetWindowAndClientRectInScreen(out RECT, out RECT)	Gets window rectangle and client area rectangle, both in screen coordinates.
GetWindowLong(int)	Calls API GetWindowLongPtr.
HasChild(wndChildFinder)	Returns `true` if this window contains the specified control. Calls wndChildFinder.Exists.
HasElm(elmFinder)	Returns `true` if this window contains the specified UI element. Calls elmFinder.Exists.
HasExStyle(WSE, bool)	Returns `true` if the window has all specified extended style flags (see wnd.ExStyle).
HasStyle(WS, bool)	Returns `true` if the window has all specified style flags (see wnd.Style).
IsChildOf(wnd)	Returns `true` if this is a child or descendant of window w.
IsEnabled(bool)	Returns `true` if the window is enabled for mouse and keyboard input. Returns `false` if disabled. Also `false` if failed (probably window closed or 0 handle). Supports lastError.
IsMatch(ReadOnlySpan<wndFinder>)	Compares window name and other properties like wnd.find does. Can be specified multiple windows.
IsMatch(string, string, WOwner, WFlags, Func<wnd, bool>, WContains)	Compares window name and other properties like wnd.find does.
IsOwnedBy(wnd, int)	Returns `true` if this window is directly or indirectly owned by window w.
MapClientToClientOf(wnd, ref POINT)	Converts coordinates relative to the client area of this window to coordinates relative to the client area of window w.
MapClientToClientOf(wnd, ref RECT)	Converts coordinates relative to the client area of this window to coordinates relative to the client area of window w.
MapClientToScreen(ref POINT)	Converts coordinates relative to the client area of this window to coordinates relative to the screen.
MapClientToScreen(ref RECT)	Converts coordinates relative to the client area of this window to coordinates relative to the screen.
MapClientToWindow(ref POINT)	Converts coordinates relative to the client area of this window to coordinates relative to the top-left corner of this window.
MapClientToWindow(ref RECT)	Converts coordinates relative to the client area of this window to coordinates relative to the top-left corner of this window.
MapScreenToClient(ref POINT)	Converts coordinates relative to the screen to coordinates relative to the client area of this window.
MapScreenToClient(ref RECT)	Converts coordinates relative to the screen to coordinates relative to the client area of this window.
MapWindowToClient(ref POINT)	Converts coordinates relative to the top-left corner of this window to coordinates relative to the client area of this window.
MapWindowToClient(ref RECT)	Converts coordinates relative to the top-left corner of this window to coordinates relative to the client area of this window.
MapWindowToScreen(ref POINT)	Converts coordinates relative to the top-left corner of this window to screen coordinates.
MapWindowToScreen(ref RECT)	Converts coordinates relative to the top-left corner of this window to screen coordinates.
MenuClick(int, bool)	Posts a "menu item clicked" notification (WM_COMMAND) as if that menu item has been clicked. Does not use the mouse.
Move(Coord, Coord, Coord, Coord, bool, screen, bool)	Moves and/or resizes.
Move(Coord, Coord, bool, screen, bool)	Moves.
MoveInScreen(Coord, Coord, screen, bool, bool)	Moves this window to coordinates x y in specified screen, and ensures that entire window is in that screen.
MoveL(RECT, SWPFlags, bool)	Moves and resizes. Same as MoveL(int, int, int, int, SWPFlags).
MoveL(int, int)	Moves.
MoveL(int, int, int, int, SWPFlags)	Moves and resizes.
MoveToScreenCenter(screen)	Moves this window to the center of the screen. Ensures that entire window is in that screen.
NameIs(params ReadOnlySpan<string>)	If window name matches one of strings in names, returns 1-based string index. Else returns 0. Also returns 0 if fails to get name (probably window closed or 0 handle). Supports lastError.
Post(int, nint, nint)	Calls/returns API PostMessage.
ProgramNameIs(params ReadOnlySpan<string>)	If window program name matches one of strings in programNames, returns 1-based string index. Else returns 0. Also returns 0 if fails to get program name (probably window closed or 0 handle). Supports lastError.
Resize(Coord, Coord, bool, screen, bool)	Resizes.
ResizeClient(int?, int?)	Resizes this window to match the specified client area size. Calls wnd.ResizeL.
ResizeL(int, int)	Resizes.
Send(int, nint, nint)	Calls API SendMessage.
Send(int, nint, string)	Calls API SendMessage where lParam is string.
Send(int, nint, void*)	Calls API SendMessage where lParam is any pointer.
SendNotify(int, nint, nint)	Calls/returns API SendNotifyMessage.
SendTimeout(int, out nint, int, nint, nint, SMTFlags)	Calls/returns API SendMessageTimeout and gets the result of the message processing.
SendTimeout(int, out nint, int, nint, string, SMTFlags)	Calls/returns API SendMessageTimeout where lParam is string.
SendTimeout(int, out nint, int, nint, void*, SMTFlags)	Calls/returns API SendMessageTimeout and gets the result of the message processing.
SetExStyle(WSE, WSFlags)	Changes window extended style.
SetStyle(WS, WSFlags)	Changes window style.
SetText(string)	Sets window/control name or control text.
SetTransparency(bool, int?, ColorInt?, bool)	Sets window transparency attributes (opacity and/or transparent color).
SetWindowLong(int, nint, bool)	Calls API SetWindowLongPtr.
SetWindowPos(SWPFlags, int, int, int, int, wnd)	Calls API SetWindowPos.
Show(bool)	Shows (if hidden) or hides this window.
ShowL(bool)	Shows (if hidden) or hides this window.
ShowMaximized(int)	If not minimized, minimizes. Also unhides.
ShowMinimized(int)	If not minimized, minimizes. Also unhides.
ShowNotMinMax(int)	If maximized or minimized, makes normal (not min/max). Also unhides.
ShowNotMinimized(int)	If minimized, restores previous non-minimized state (maximized or normal). Also unhides.
ThrowIf0()	If wnd.Is0, throws AuWndException.
ThrowIfInvalid()	If wnd.Is0 or not wnd.IsAlive, throws AuWndException.
ThrowNoNative(string)	Throws AuWndException that uses mainMessage and does not use the last Windows API error. Also the message depends on whether the window handle is 0/invalid.
ThrowUseNative()	Throws AuWndException that uses the last Windows API error (code and message). Also the message depends on whether the window handle is 0/invalid.
ThrowUseNative(int)	Throws AuWndException that uses the specified Windows API error code and its message. Also the message depends on whether the window handle is 0/invalid.
ThrowUseNative(int, string)	Throws AuWndException that uses mainMessage and the specified Windows API error code. Also the message depends on whether the window handle is 0/invalid.
ThrowUseNative(string)	Throws AuWndException that uses mainMessage and the last Windows API error (code and message). Also the message depends on whether the window handle is 0/invalid.
ToString()	Formats string `$"{handle} {ClassName} \"{Name}\" {ProgramName} {Rect}"`.
WaitForClosed(Seconds, bool)	Waits until this window is closed/destroyed or until its process ends.
WaitForName(Seconds, string, bool)	Waits until this window has the specified name.
WaitFor<T>(Seconds, Func<wnd, T>, bool)	Waits for a user-defined state/condition of this window. For example active, visible, enabled, closed, contains something.
ZorderAbove(wnd, bool)	Places this window above window w in the Z order.
ZorderBelow(wnd, bool)	Places this window below window w in the Z order.
ZorderBottom()	Places this window or control at the bottom of the Z order.
ZorderIsAbove(wnd)	Returns `true` if this window is above window w in the Z order.
ZorderNoTopmost(bool)	Makes this window non-topmost.
ZorderTop(bool)	Places this window or control at the top of the Z order. Does not activate. If the window was topmost, it will be at the top of topmost windows, else at the top of other windows.
ZorderTopmost()	Makes this window topmost (always on top of non-topmost windows in the Z order). Does not activate.
find(Seconds, string, string, WOwner, WFlags, Func<wnd, bool>, WContains)	Finds a top-level window and returns its handle as wnd. Can wait and throw NotFoundException.
find(string, string, WOwner, WFlags, Func<wnd, bool>, WContains)	Finds a top-level window and returns its handle as wnd.
findAll(string, string, WOwner, WFlags, Func<wnd, bool>, WContains)	Finds all matching windows.
findFast(string, string, bool, wnd)	Finds a top-level window and returns its handle as wnd.
findOrRun(string, string, WOwner, WFlags, Func<wnd, bool>, WContains, Action, Seconds?, bool)	Finds a top-level window, like wnd.find. If found, activates (optionally), else calls callback function and waits for the window. The callback should open the window, for example call run.it.
fromMouse(WXYFlags)	Gets visible top-level window or control from mouse cursor position. More info: wnd.fromXY.
fromXY(POINT, WXYFlags)	Gets visible top-level window or control from point.
fromXY(int, int, WXYFlags)	Gets visible top-level window or control from point.
runAndFind(Action, Seconds, string, string, WOwner, WFlags, Func<wnd, bool>, WContains, bool)	Opens and finds new window. Ignores old windows. Activates.
switchActiveWindow()	Activates next non-minimized main window, like with `Alt+Tab`.
wait(Seconds, bool, string, string, WOwner, WFlags, Func<wnd, bool>, WContains)	Waits until window exists or is active.
waitAny(Seconds, bool, params wndFinder[])	Waits until any of specified windows exists or is active.

Operators

Name	Description
operator ==(wnd, wnd)	Compares window handles.
explicit operator int(wnd)
explicit operator nint(wnd)
explicit operator wnd(int)
explicit operator wnd(nint)
implicit operator wnd(SpecHWND)	Converts from a special handle value.
operator !=(wnd, wnd)	Compares window handles.