FindWindowExA function (winuser.h)

Retrieves a handle to a window whose class name and window name match the specified strings. The function searches child windows, beginning with the one following the specified child window. This function does not perform a case-sensitive search.

Syntax

HWND FindWindowExA(
  [in, optional] HWND   hWndParent,
  [in, optional] HWND   hWndChildAfter,
  [in, optional] LPCSTR lpszClass,
  [in, optional] LPCSTR lpszWindow
);

Parameters

[in, optional] hWndParent

Type: HWND

A handle to the parent window whose child windows are to be searched.

If hwndParent is NULL, the function uses the desktop window as the parent window. The function searches among windows that are child windows of the desktop.

If hwndParent is HWND_MESSAGE, the function searches all message-only windows.

[in, optional] hWndChildAfter

Type: HWND

A handle to a child window. The search begins with the next child window in the Z order. The child window must be a direct child window of hwndParent, not just a descendant window.

If hwndChildAfter is NULL, the search begins with the first child window of hwndParent.

Note that if both hwndParent and hwndChildAfter are NULL, the function searches all top-level and message-only windows.

[in, optional] lpszClass

Type: LPCSTR

The class name or a class atom created by a previous call to the RegisterClass or RegisterClassEx function. The atom must be placed in the low-order word of lpszClass; the high-order word must be zero.

If lpszClass is a string, it specifies the window class name. The class name can be any name registered with RegisterClass or RegisterClassEx, or any of the predefined control-class names, or it can be MAKEINTATOM(0x8000). In this latter case, 0x8000 is the atom for a menu class. For more information, see the Remarks section of this topic.

[in, optional] lpszWindow

Type: LPCSTR

The window name (the window's title). If this parameter is NULL, all window names match.

Return value

Type: HWND

If the function succeeds, the return value is a handle to the window that has the specified class and window names.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The FindWindowEx function searches only direct child windows. It does not search other descendants.

If the lpszWindow parameter is not NULL, FindWindowEx calls the GetWindowText function to retrieve the window name for comparison. For a description of a potential problem that can arise, see the Remarks section of GetWindowText.

An application can call this function in the following way.

FindWindowEx( NULL, NULL, MAKEINTATOM(0x8000), NULL );

Note that 0x8000 is the atom for a menu class. When an application calls this function, the function checks whether a context menu is being displayed that the application created.

Note

The winuser.h header defines FindWindowEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winuser.h (include Windows.h)
Library User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-window-l1-1-1 (introduced in Windows 8.1)

See also

Conceptual

EnumWindows

FindWindow

GetClassName

GetWindowText

Reference

RegisterClass

RegisterClassEx

Windows