Win API
Win API
Functions
T IT L E DESC RIP T IO N
BringWindowToTop Brings the specified window to the top of the Z order. If the
window is a top-level window, it is activated. If the window is
a child window, the top-level parent window associated with
the child window is activated.
CallMsgFilterA Passes the specified message and hook code to the hook
procedures associated with the WH_SYSMSGFILTER and
WH_MSGFILTER hooks.
CallMsgFilterW Passes the specified message and hook code to the hook
procedures associated with the WH_SYSMSGFILTER and
WH_MSGFILTER hooks.
GetClassWord Retrieves the 16-bit (WORD) value at the specified offset into
the extra class memory for the window class to which the
specified window belongs.
GetMessagePos Retrieves the cursor position for the last message retrieved
by the GetMessage function.
GetMessageTime Retrieves the message time for the last message retrieved by
the GetMessage function.
GetProcessDefaultLayout Retrieves the default layout that is used when windows are
created with no parent or owner.
GetWindowModuleFileNameA Retrieves the full path and file name of the module
associated with the specified window handle.
GetWindowModuleFileNameW Retrieves the full path and file name of the module
associated with the specified window handle.
GetWindowPlacement Retrieves the show state and the restored, minimized, and
maximized positions of the specified window.
GetWindowTextA Copies the text of the specified window's title bar (if it has
one) into a buffer. If the specified window is a control, the
text of the control is copied. However, GetWindowText
cannot retrieve the text of a control in another application.
GetWindowTextW Copies the text of the specified window's title bar (if it has
one) into a buffer. If the specified window is a control, the
text of the control is copied. However, GetWindowText
cannot retrieve the text of a control in another application.
InternalGetWindowText Copies the text of the specified window's title bar (if it has
one) into a buffer.
T IT L E DESC RIP T IO N
SetClassWord Replaces the 16-bit (WORD) value at the specified offset into
the extra class memory for the window class to which the
specified window belongs.
SetForegroundWindow Brings the thread that created the specified window into the
foreground and activates the window.
SetMessageExtraInfo Sets the extra message information for the current thread.
SetProcessDefaultLayout Changes the default layout when windows are created with
no parent or owner only for the currently running process.
SetWindowPlacement Sets the show state and the restored, minimized, and
maximized positions of the specified window.
SetWindowTextA Changes the text of the specified window's title bar (if it has
one). If the specified window is a control, the text of the
control is changed. However, SetWindowText cannot change
the text of a control in another application.
SetWindowTextW Changes the text of the specified window's title bar (if it has
one). If the specified window is a control, the text of the
control is changed. However, SetWindowText cannot change
the text of a control in another application.
ShowWindowAsync Sets the show state of a window without waiting for the
operation to complete.
Structures
T IT L E DESC RIP T IO N
Functions
T IT L E DESC RIP T IO N
Structures
T IT L E DESC RIP T IO N
Functions
T IT L E DESC RIP T IO N
_lopen The _lopen function opens an existing file and sets the file
pointer to the beginning of the file. This function is provided
for compatibility with 16-bit versions of Windows. Win32-
based applications should use the CreateFile function.
_lread The _lread function reads data from the specified file. This
function is provided for compatibility with 16-bit versions of
Windows. Win32-based applications should use the ReadFile
function.
AddAtomA Adds a character string to the local atom table and returns a
unique value (an atom) identifying the string.
AddAtomW Adds a character string to the local atom table and returns a
unique value (an atom) identifying the string.
ApplicationRecoveryFinished Indicates that the calling application has completed its data
recovery.
ClearEventLogA Clears the specified event log, and optionally saves the
current copy of the log to a backup file.
ClearEventLogW Clears the specified event log, and optionally saves the
current copy of the log to a backup file.
ConvertThreadToFiber Converts the current thread into a fiber. You must convert a
thread into a fiber before you can schedule other fibers.
ConvertThreadToFiberEx Converts the current thread into a fiber. You must convert a
thread into a fiber before you can schedule other fibers.
CreateHardLinkA Establishes a hard link between an existing file and a new file.
CreateHardLinkTransactedA Establishes a hard link between an existing file and a new file
as a transacted operation.
CreateHardLinkTransactedW Establishes a hard link between an existing file and a new file
as a transacted operation.
CreateHardLinkW Establishes a hard link between an existing file and a new file.
CreateProcessWithLogonW Creates a new process and its primary thread. Then the new
process runs the specified executable file in the security
context of the specified credentials (user, domain, and
password). It can optionally load the user profile for a
specified user.
CreateProcessWithTokenW Creates a new process and its primary thread. The new
process runs in the security context of the specified token. It
can optionally load the user profile for the specified user.
DeleteTimerQueue Deletes a timer queue. Any pending timers in the queue are
canceled and deleted.
FindAtomA Searches the local atom table for the specified character
string and retrieves the atom associated with that string.
FindAtomW Searches the local atom table for the specified character
string and retrieves the atom associated with that string.
GetCommTimeouts Retrieves the time-out parameters for all read and write
operations on a specified communications device.
GetFullPathNameTransactedA Retrieves the full path and file name of the specified file as a
transacted operation.
GetFullPathNameTransactedW Retrieves the full path and file name of the specified file as a
transacted operation.
GetLogicalDriveStringsA Fills a buffer with strings that specify valid drives in the
system.
GetNamedPipeClientComputerNameA Retrieves the client computer name for the specified named
pipe.
GetNamedPipeClientProcessId Retrieves the client process identifier for the specified named
pipe.
GetNamedPipeClientSessionId Retrieves the client session identifier for the specified named
pipe.
GetNamedPipeServerSessionId Retrieves the server session identifier for the specified named
pipe.
GetNumaNodeNumberFromHandle Retrieves the NUMA node associated with the file or I/O
device represented by the specified file handle.
GetPrivateProfileSection Retrieves all the keys and values for the specified section of
an initialization file.
GetPrivateProfileSectionA Retrieves all the keys and values for the specified section of
an initialization file.
GetPrivateProfileSectionW Retrieves all the keys and values for the specified section of
an initialization file.
GetProcessAffinityMask Retrieves the process affinity mask for the specified process
and the system affinity mask for the system.
GetProfileSectionA Retrieves all the keys and values for the specified section of
the Win.ini file.
GetProfileSectionW Retrieves all the keys and values for the specified section of
the Win.ini file.
GetSystemDEPPolicy Gets the data execution prevention (DEP) policy setting for
the system.
GetSystemRegistryQuota Retrieves the current size of the registry and the maximum
size that the registry is allowed to attain on the system.
GetUserNameA Retrieves the name of the user associated with the current
thread.
GetUserNameW Retrieves the name of the user associated with the current
thread.
GetVolumePathNameA Retrieves the volume mount point where the specified path
is mounted.
GetVolumePathNamesForVolumeNameA Retrieves a list of drive letters and mounted folder paths for
the specified volume.
GlobalAddAtomA Adds a character string to the global atom table and returns
a unique value (an atom) identifying the string.
GlobalAddAtomExA Adds a character string to the global atom table and returns
a unique value (an atom) identifying the string.
GlobalAddAtomExW Adds a character string to the global atom table and returns
a unique value (an atom) identifying the string.
GlobalAddAtomW Adds a character string to the global atom table and returns
a unique value (an atom) identifying the string.
GlobalFindAtomA Searches the global atom table for the specified character
string and retrieves the global atom associated with that
string.
GlobalFindAtomW Searches the global atom table for the specified character
string and retrieves the global atom associated with that
string.
GlobalFree Frees the specified global memory object and invalidates its
handle.
T IT L E DESC RIP T IO N
InitAtomTable Initializes the local atom table and sets the number of hash
buckets to the specified size.
IsBadReadPtr Verifies that the calling process has read access to the
specified range of memory.
IsBadStringPtrA Verifies that the calling process has read access to the
specified range of memory.
IsBadStringPtrW Verifies that the calling process has read access to the
specified range of memory.
T IT L E DESC RIP T IO N
IsBadWritePtr Verifies that the calling process has write access to the
specified range of memory.
LocalFree Frees the specified local memory object and invalidates its
handle.
LookupAccountSidLocalA Retrieves the name of the account for the specified SID on
the local machine.
LookupAccountSidLocalW Retrieves the name of the account for the specified SID on
the local machine.
MulDiv Multiplies two 32-bit values and then divides the 64-bit
result by a third 32-bit value.
PulseEvent Sets the specified event object to the signaled state and then
resets it to the nonsignaled state after releasing the
appropriate number of waiting threads.
QueryFullProcessImageNameA Retrieves the full name of the executable image for the
specified process.
QueryFullProcessImageNameW Retrieves the full name of the executable image for the
specified process.
ReadThreadProfilingData Reads the specified profiling data associated with the thread.
ReOpenFile Reopens the specified file system object with different access
rights, sharing mode, and flags.
ReplaceFileA Replaces one file with another file, with the option of creating
a backup copy of the original file.
ReplaceFileW Replaces one file with another file, with the option of creating
a backup copy of the original file.
SetCommTimeouts Sets the time-out parameters for all read and write
operations on a specified communications device.
SetDllDirectoryA Adds a directory to the search path used to locate DLLs for
the application.
SetDllDirectoryW Adds a directory to the search path used to locate DLLs for
the application.
SetFileCompletionNotificationModes Sets the notification modes for a file handle, allowing you to
specify how completion notifications work for the specified
file.
SetHandleCount
SetMailslotInfo Sets the time-out value used by the specified mailslot for a
read operation.
SetProcessAffinityMask Sets a processor affinity mask for the threads of the specified
process.
SetProcessWorkingSetSize Sets the minimum and maximum working set sizes for the
specified process.
SetSearchPathMode Sets the per-process mode that the SearchPath function uses
when locating files.
WritePrivateProfileSectionA Replaces the keys and values for the specified section in an
initialization file.
WritePrivateProfileSectionW Replaces the keys and values for the specified section in an
initialization file.
WriteProfileStringA Copies a string into the specified section of the Win.ini file.
T IT L E DESC RIP T IO N
WriteProfileStringW Copies a string into the specified section of the Win.ini file.
Callback functions
T IT L E DESC RIP T IO N
Structures
T IT L E DESC RIP T IO N
FILE_BASIC_INFO Contains the basic information for a file. Used for file
handles.
FILE_END_OF_FILE_INFO Contains the specified value to which the end of the file
should be set.
Enumerations
T IT L E DESC RIP T IO N
Syntax
int __clrcall WinMain(
HINSTANCE hInstance,
HINSTANCE hPrevInstance,
LPSTR lpCmdLine,
int nShowCmd
);
Parameters
hInstance
Type: HINSTANCE
A handle to the current instance of the application.
hPrevInstance
Type: HINSTANCE
A handle to the previous instance of the application. This parameter is always NULL . If you need to detect
whether another instance already exists, create a uniquely named mutex using the CreateMutex function.
CreateMutex will succeed even if the mutex already exists, but the function will return
ERROR_ALREADY_EXISTS . This indicates that another instance of your application exists, because it created
the mutex first. However, a malicious user can create this mutex before you do and prevent your application
from starting. To prevent this situation, create a randomly named mutex and store the name so that it can only
be obtained by an authorized user. Alternatively, you can use a file for this purpose. To limit your application to
one instance per user, create a locked file in the user's profile directory.
lpCmdLine
Type: LPSTR
The command line for the application, excluding the program name. To retrieve the entire command line, use the
GetCommandLine function.
nShowCmd
TBD
Return value
Type: int
If the function succeeds, terminating when it receives a WM_QUIT message, it should return the exit value
contained in that message's wParam parameter. If the function terminates before entering the message loop, it
should return zero.
Remarks
The name WinMain is used by convention by many programming frameworks. Depending on the
programming framework, the call to the WinMain function can be preceded and followed by additional
activities specific to that framework.
Your WinMain should initialize the application, display its main window, and enter a message retrieval-and-
dispatch loop that is the top-level control structure for the remainder of the application's execution. Terminate
the message loop when it receives a WM_QUIT message. At that point, your WinMain should exit the
application, returning the value passed in the WM_QUIT message's wParam parameter. If WM_QUIT was
received as a result of calling PostQuitMessage, the value of wParam is the value of the PostQuitMessage
function's nExitCode parameter. For more information, see Creating a Message Loop.
ANSI applications can use the lpCmdLine parameter of the WinMain function to access the command-line
string, excluding the program name. Note that lpCmdLine uses the LPSTR data type instead of the LPTSTR data
type. This means that WinMain cannot be used by Unicode programs. The GetCommandLineW function can be
used to obtain the command line as a Unicode string. Some programming frameworks might provide an
alternative entry point that provides a Unicode command line. For example, the Microsoft Visual Studio C++
complier uses the name wWinMain for the Unicode entry point.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
CreateMutex
DispatchMessage
GetCommandLine
GetMessage
Other Resources
PostQuitMessage
Reference
TranslateMessage
Windows
windef.h header
2/1/2021 • 2 minutes to read • Edit Online
Structures
T IT L E DESC RIP T IO N
Enumerations
T IT L E DESC RIP T IO N
DPI_AWARENESS Identifies the dots per inch (dpi) setting for a thread, process,
or window.
Functions
T IT L E DESC RIP T IO N
Button_GetCheck Gets the check state of a radio button or check box. You can
use this macro or send the BM_GETCHECK message
explicitly.
Button_GetState Retrieves the state of a button or check box. You can use this
macro or send the BM_GETSTATE message explicitly.
Button_SetCheck Sets the check state of a radio button or check box. You can
use this macro or send the BM_SETCHECK message explicitly.
Button_SetStyle Sets the style of a button. You can use this macro or send
the BM_SETSTYLE message explicitly.
ComboBox_AddItemData Adds item data to the list in a combo box at the specified
location. You can use this macro or send the CB_ADDSTRING
message explicitly.
ComboBox_FindItemData Finds the first item in a combo box list that has the specified
item data. You can use this macro or send the
CB_FINDSTRING message explicitly.
ComboBox_FindString Finds the first string in a combo box list that begins with the
specified string. You can use this macro or send the
CB_FINDSTRING message explicitly.
ComboBox_FindStringExact Finds the first string in a combo box list that exactly matches
the specified string, except that the search is not case
sensitive. You can use this macro or send the
CB_FINDSTRINGEXACT message explicitly.
ComboBox_GetCount Gets the number of items in the list box of a combo box. You
can use this macro or send the CB_GETCOUNT message
explicitly.
ComboBox_GetCurSel Gets the index of the currently selected item in a combo box.
You can use this macro or send the CB_GETCURSEL message
explicitly.
ComboBox_GetItemHeight Retrieves the height of list items in a combo box. You can use
this macro or send the CB_GETITEMHEIGHT message
explicitly.
ComboBox_GetLBText Gets a string from a list in a combo box. You can use this
macro or send the CB_GETLBTEXT message explicitly.
ComboBox_GetLBTextLen Gets the length of a string in the list in a combo box. You
can use this macro or send the CB_GETLBTEXTLEN message
explicitly.
ComboBox_LimitText Limits the length of the text the user may type into the edit
control of a combo box. You can use this macro or send the
CB_LIMITTEXT message explicitly.
ComboBox_ResetContent Removes all items from the list box and edit control of a
combo box. You can use this macro or send the
CB_RESETCONTENT message explicitly.
ComboBox_SelectItemData Searches a list in a combo box for an item that has the
specified item data. If a matching item is found, the item is
selected. You can use this macro or send the
CB_SELECTSTRING message explicitly.
ComboBox_SelectString Searches a list in a combo box for an item that begins with
the characters in a specified string. If a matching item is
found, the item is selected. You can use this macro or send
the CB_SELECTSTRING message explicitly.
ComboBox_SetCurSel Sets the currently selected item in a combo box. You can use
this macro or send the CB_SETCURSEL message explicitly.
ComboBox_SetExtendedUI Selects either the default user interface (UI) or the extended
UI for a combo box that has the CBS_DROPDOWN or
CBS_DROPDOWNLIST style. You can use this macro or send
the CB_SETEXTENDEDUI message explicitly.
ComboBox_SetItemHeight Sets the height of list items or the selection field in a combo
box. You can use this macro or send the CB_SETITEMHEIGHT
message explicitly.
ComboBox_ShowDropdown Shows or hides the list in a combo box. You can use this
macro or send the CB_SHOWDROPDOWN message
explicitly.
Edit_EmptyUndoBuffer Resets the undo flag of an edit or rich edit control. The undo
flag is set whenever an operation within the edit control can
be undone. You can use this macro or send the
EM_EMPTYUNDOBUFFER message explicitly.
T IT L E DESC RIP T IO N
Edit_GetHandle Gets a handle to the memory currently allocated for the text
of a multiline edit control. You can use this macro or send
the EM_GETHANDLE message explicitly.
Edit_GetLine Retrieves a line of text from an edit or rich edit control. You
can use this macro or send the EM_GETLINE message
explicitly.
Edit_GetLineCount Gets the number of lines in the text of an edit control. You
can use this macro or send the EM_GETLINECOUNT
message explicitly.
Edit_GetPasswordChar Gets the password character for an edit or rich edit control.
You can use this macro or send the
EM_GETPASSWORDCHAR message explicitly.
Edit_GetRect Gets the formatting rectangle of an edit control. You can use
this macro or send the EM_GETRECT message explicitly.
Edit_LimitText Limits the length of text that can be entered into an edit
control. You can use this macro or send the EM_LIMITTEXT
message explicitly.
Edit_LineFromChar Gets the index of the line that contains the specified
character index in a multiline edit or rich edit control. You can
use this macro or send the EM_LINEFROMCHAR message
explicitly.
T IT L E DESC RIP T IO N
Edit_ScrollCaret Scrolls the caret into view in an edit or rich edit control. You
can use this macro or send the EM_SCROLLCARET message
explicitly.
Edit_SetModify Sets or clears the modification flag for an edit control. The
modification flag indicates whether the text within the edit
control has been modified. You can use this macro or send
the EM_SETMODIFY message explicitly.
Edit_SetRect Sets the formatting rectangle of an edit control. You can use
this macro or send the EM_SETRECT message explicitly.
Edit_SetTabStops Sets the tab stops in a multiline edit or rich edit control.
When text is copied to the control, any tab character in the
text causes space to be generated up to the next tab stop.
You can use this macro or send the EM_SETTABSTOPS
message explicitly.
T IT L E DESC RIP T IO N
ListBox_AddItemData Adds item data to the list box at the specified location. You
can use this macro or send the LB_ADDSTRING message
explicitly.
ListBox_DeleteString Deletes the item at the specified location in a list box. You
can use this macro or send the LB_DELETESTRING message
explicitly.
ListBox_FindItemData Finds the first item in a list box that has the specified item
data. You can use this macro or send the LB_FINDSTRING
message explicitly.
ListBox_FindString Finds the first string in a list box that begins with the
specified string. You can use this macro or send the
LB_FINDSTRING message explicitly.
ListBox_FindStringExact Finds the first list box string that exactly matches the
specified string, except that the search is not case sensitive.
You can use this macro or send the LB_FINDSTRINGEXACT
message explicitly.
ListBox_GetCaretIndex Retrieves the index of the list box item that has the focus
rectangle in a multiple-selection list box. The item may or
may not be selected. You can use this macro or send the
LB_GETCARETINDEX message explicitly.
ListBox_GetCount Gets the number of items in a list box. You can use this
macro or send the LB_GETCOUNT message explicitly.
ListBox_GetHorizontalExtent Gets the width that a list box can be scrolled horizontally
(the scrollable width) if the list box has a horizontal scroll bar.
You can use this macro or send the
LB_GETHORIZONTALEXTENT message explicitly.
ListBox_GetItemRect Gets the dimensions of the rectangle that bounds a list box
item as it is currently displayed in the list box. You can use
this macro or send the LB_GETITEMRECT message explicitly.
ListBox_GetSel Gets the selection state of an item. You can use this macro
or send the LB_GETSEL message explicitly.
ListBox_GetText Gets a string from a list box. You can use this macro or send
the LB_GETTEXT message explicitly.
ListBox_GetTextLen Gets the length of a string in a list box. You can use this
macro or send the LB_GETTEXTLEN message explicitly.
ListBox_GetTopIndex Gets the index of the first visible item in a list box. You can
use this macro or send the LB_GETTOPINDEX message
explicitly.
ListBox_InsertItemData Inserts item data to a list box at the specified location. You
can use this macro or send the LB_INSERTSTRING message
explicitly.
ListBox_InsertString Adds a string to a list box at the specified location. You can
use this macro or send the LB_INSERTSTRING message
explicitly.
ListBox_ResetContent Removes all items from a list box. You can use this macro or
send the LB_RESETCONTENT message explicitly.
ListBox_SelectItemData Searches a list box for an item that has the specified item
data. If a matching item is found, the item is selected. You
can use this macro or send the LB_SELECTSTRING message
explicitly.
T IT L E DESC RIP T IO N
ListBox_SelectString Searches a list box for an item that begins with the
characters in a specified string. If a matching item is found,
the item is selected. You can use this macro or send the
LB_SELECTSTRING message explicitly.
ListBox_SetCaretIndex Sets the focus rectangle to the item at the specified index in
a multiple-selection list box. If the item is not visible, it is
scrolled into view. You can use this macro or send the
LB_SETCARETINDEX message explicitly.
ListBox_SetHorizontalExtent Set the width by which a list box can be scrolled horizontally
(the scrollable width).
ListBox_SetTabStops Sets the tab-stop positions in a list box. You can use this
macro or send the LB_SETTABSTOPS message explicitly.
ListBox_SetTopIndex Ensures that the specified item in a list box is visible. You can
use this macro or send the LB_SETTOPINDEX message
explicitly.
ScrollBar_SetPos Sets the position of the scroll box (thumb) in the specified
scroll bar and, if requested, redraws the scroll bar to reflect
the new position of the scroll box.
SelectFont The SelectFont macro selects a font object into the specified
device context (DC). The new font object replaces the
previous font object.
Static_SetIcon Sets the icon for a static control. You can use this macro or
send the STM_SETICON message explicitly.
Syntax
void GET_X_LPARAM(
lp
);
Parameters
lp
Return value
Type: int
X-coordinate.
Remarks
Use GET_X_LPARAM instead of LOWORD to extract signed coordinate data. Negative screen coordinates may
be returned on multiple monitor systems.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GET_Y_LPARAM
LOWORD
Reference
Windows Data Types
GET_Y_LPARAM macro (windowsx.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
void GET_Y_LPARAM(
lp
);
Parameters
lp
Return value
Type: int
Y-coordinate.
Remarks
Use GET_Y_LPARAM instead of HIWORD to extract signed coordinate data. Negative screen coordinates may
be returned on multiple monitor systems.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GET_X_LPARAM
HIWORD
Reference
Windows Data Types
winuser.h header
2/1/2021 • 78 minutes to read • Edit Online
Functions
T IT L E DESC RIP T IO N
ActivateKeyboardLayout Sets the input locale identifier (formerly called the keyboard
layout handle) for the calling thread or the current process.
The input locale identifier specifies a locale as well as the
physical layout of the keyboard.
AppendMenuA Appends a new item to the end of the specified menu bar,
drop-down menu, submenu, or shortcut menu. You can use
this function to specify the content, appearance, and
behavior of the menu item.
T IT L E DESC RIP T IO N
AppendMenuW Appends a new item to the end of the specified menu bar,
drop-down menu, submenu, or shortcut menu. You can use
this function to specify the content, appearance, and
behavior of the menu item.
BringWindowToTop Brings the specified window to the top of the Z order. If the
window is a top-level window, it is activated. If the window is
a child window, the top-level parent window associated with
the child window is activated.
CallMsgFilterA Passes the specified message and hook code to the hook
procedures associated with the WH_SYSMSGFILTER and
WH_MSGFILTER hooks.
CallMsgFilterW Passes the specified message and hook code to the hook
procedures associated with the WH_SYSMSGFILTER and
WH_MSGFILTER hooks.
CopyImage Creates a new image (icon, cursor, or bitmap) and copies the
attributes of the specified image to the new one. If
necessary, the function stretches the bits to fit the desired
size of the new image.
CreateCaret Creates a new shape for the system caret and assigns
ownership of the caret to the specified window. The caret
shape can be a line, a block, or a bitmap.
CreateCursor Creates a cursor having the specified size, bit patterns, and
hot spot.
CreateIcon Creates an icon that has the specified size, colors, and bit
patterns.
DeleteMenu Deletes an item from the specified menu. If the menu item
opens a menu or submenu, this function destroys the
handle to the menu or submenu and frees the memory used
by the menu or submenu.
DestroyCaret Destroys the caret's current shape, frees the caret from the
window, and removes the caret from the screen.
DestroyIcon Destroys an icon and frees any memory the icon occupied.
DestroyMenu Destroys the specified menu and frees any memory that the
menu occupies.
DisableProcessWindowsGhosting Disables the window ghosting feature for the calling GUI
process. Window ghosting is a Windows Manager feature
that lets the user minimize, move, or close the main window
of an application that is not responding.
DlgDirListA Replaces the contents of a list box with the names of the
subdirectories and files in a specified directory. You can filter
the list of names by specifying a set of file attributes. The list
can optionally include mapped drives.
DlgDirListComboBoxA Replaces the contents of a combo box with the names of the
subdirectories and files in a specified directory. You can filter
the list of names by specifying a set of file attributes. The list
of names can include mapped drive letters.
DlgDirListComboBoxW Replaces the contents of a combo box with the names of the
subdirectories and files in a specified directory. You can filter
the list of names by specifying a set of file attributes. The list
of names can include mapped drive letters.
DlgDirListW Replaces the contents of a list box with the names of the
subdirectories and files in a specified directory. You can filter
the list of names by specifying a set of file attributes. The list
can optionally include mapped drives.
DragDetect Captures the mouse and tracks its movement until the user
releases the left button, presses the ESC key, or moves the
mouse outside the drag rectangle around the specified
point.
DrawMenuBar Redraws the menu bar of the specified window. If the menu
bar changes after the system has created the window, this
function must be called to draw the changed menu bar.
EnableMouseInPointer Enables the mouse to act as a pointer input device and send
WM_POINTER messages.
EndDialog Destroys a modal dialog box, causing the system to end any
processing for the dialog box.
ExitWindowsEx Logs off the interactive user, shuts down the system, or
shuts down and restarts the system.
FlashWindow Flashes the specified window one time. It does not change
the active state of the window.
FlashWindowEx Flashes the specified window. It does not change the active
state of the window.
GET_DEVICE_LPARAM Retrieves the input device type from the specified LPARAM
value.
GET_FLAGS_LPARAM Retrieves the state of certain virtual keys from the specified
LPARAM value.
GET_KEYSTATE_LPARAM Retrieves the state of certain virtual keys from the specified
LPARAM value.
GET_KEYSTATE_WPARAM Retrieves the state of certain virtual keys from the specified
WPARAM value.
GetCapture Retrieves a handle to the window (if any) that has captured
the mouse. Only one window at a time can capture the
mouse; this window receives mouse input whether or not
the cursor is within its borders.
GetCaretBlinkTime Retrieves the time required to invert the caret's pixels. The
user can set this value.
GetClassWord Retrieves the 16-bit (WORD) value at the specified offset into
the extra class memory for the window class to which the
specified window belongs.
GetDialogBaseUnits Retrieves the system's dialog base units, which are the
average width and height of characters in the system font.
GetDialogDpiChangeBehavior Returns the flags that might have been set on a given dialog
by an earlier call to SetDialogDpiChangeBehavior.
GetDpiForWindow Returns the dots per inch (dpi) value for the associated
window.
T IT L E DESC RIP T IO N
GetFocus Retrieves the handle to the window that has the keyboard
focus, if the window is attached to the calling thread's
message queue.
GetKeyboardLayout Retrieves the active input locale identifier (formerly called the
keyboard layout).
GetKeyboardState Copies the status of the 256 virtual keys to the specified
buffer.
GetKeyState Retrieves the status of the specified virtual key. The status
specifies whether the key is up, down, or toggled (on,
off�alternating each time the key is pressed).
GetMenuState Retrieves the menu flags associated with the specified menu
item.
GetMenuStringA Copies the text string of the specified menu item into the
specified buffer.
GetMenuStringW Copies the text string of the specified menu item into the
specified buffer.
GetMessagePos Retrieves the cursor position for the last message retrieved
by the GetMessage function.
GetMessageTime Retrieves the message time for the last message retrieved by
the GetMessage function.
GetOpenClipboardWindow Retrieves the handle to the window that currently has the
clipboard open.
T IT L E DESC RIP T IO N
GetPointerDeviceCursors Gets the cursor IDs that are mapped to the cursors
associated with a pointer device.
GetPointerDeviceRects Gets the x and y range for the pointer device (in himetric)
and the x and y range (current resolution) for the display
that the pointer device is mapped to.
GetPointerPenInfo Gets the pen-based information for the specified pointer (of
type PT_PEN) associated with the current message.
GetProcessDefaultLayout Retrieves the default layout that is used when windows are
created with no parent or owner.
GetRawPointerDeviceData Gets the raw input data from the pointer device.
T IT L E DESC RIP T IO N
GetRegisteredRawInputDevices Retrieves the information about the raw input devices for the
current application.
GetWindowModuleFileNameA Retrieves the full path and file name of the module
associated with the specified window handle.
GetWindowModuleFileNameW Retrieves the full path and file name of the module
associated with the specified window handle.
GetWindowPlacement Retrieves the show state and the restored, minimized, and
maximized positions of the specified window.
GetWindowTextA Copies the text of the specified window's title bar (if it has
one) into a buffer. If the specified window is a control, the
text of the control is copied. However, GetWindowText
cannot retrieve the text of a control in another application.
GetWindowTextW Copies the text of the specified window's title bar (if it has
one) into a buffer. If the specified window is a control, the
text of the control is copied. However, GetWindowText
cannot retrieve the text of a control in another application.
T IT L E DESC RIP T IO N
HideCaret Removes the caret from the screen. Hiding a caret does not
destroy its current shape or invalidate the insertion point.
InsertMenuA Inserts a new menu item into a menu, moving other items
down the menu.
InsertMenuW Inserts a new menu item into a menu, moving other items
down the menu.
T IT L E DESC RIP T IO N
InternalGetWindowText Copies the text of the specified window's title bar (if it has
one) into a buffer.
IsCharLowerW
IsWow64Message Determines whether the last message read from the current
thread's queue originated from a WOW64 process.
LoadIconA Loads the specified icon resource from the executable (.exe)
file associated with an application instance.
LoadIconW Loads the specified icon resource from the executable (.exe)
file associated with an application instance.
LoadMenuA Loads the specified menu resource from the executable (.exe)
file associated with an application instance.
LoadMenuW Loads the specified menu resource from the executable (.exe)
file associated with an application instance.
LookupIconIdFromDirectory Searches through icon or cursor data for the icon or cursor
that best fits the current display device.
LookupIconIdFromDirectoryEx Searches through icon or cursor data for the icon or cursor
that best fits the current display device.
MsgWaitForMultipleObjects Waits until one or all of the specified objects are in the
signaled state or the time-out interval elapses. The objects
can include input event objects.
T IT L E DESC RIP T IO N
MsgWaitForMultipleObjectsEx Waits until one or all of the specified objects are in the
signaled state, an I/O completion routine or asynchronous
procedure call (APC) is queued to the thread, or the time-
out interval elapses. The array of objects can include input
event objects.
OemKeyScan Maps OEMASCII codes 0 through 0x0FF into the OEM scan
codes and shift states. The function provides information
that allows a program to send OEM text to another program
by simulating keyboard input.
RegisterDeviceNotificationA Registers the device or type of device for which a window will
receive notifications.
RegisterDeviceNotificationW Registers the device or type of device for which a window will
receive notifications.
RegisterRawInputDevices Registers the devices that supply the raw input data.
SetClassWord Replaces the 16-bit (WORD) value at the specified offset into
the extra class memory for the window class to which the
specified window belongs.
SetForegroundWindow Brings the thread that created the specified window into the
foreground and activates the window.
SetGestureConfig Configures the messages that are sent from a window for
Windows Touch gestures.
SetMenuDefaultItem Sets the default menu item for the specified menu.
SetMessageExtraInfo Sets the extra message information for the current thread.
SetProcessDefaultLayout Changes the default layout when windows are created with
no parent or owner only for the currently running process.
SetProcessDpiAwarenessContext Sets the current process to a specified dots per inch (dpi)
awareness context. The DPI awareness contexts are from the
DPI_AWARENESS_CONTEXT value.
SetScrollPos The SetScrollPos function sets the position of the scroll box
(thumb) in the specified scroll bar and, if requested, redraws
the scroll bar to reflect the new position of the scroll box.
SetThreadDpiAwarenessContext Set the DPI awareness for the current thread to the provided
value.
SetUserObjectSecurity Sets the security of a user object. This can be, for example, a
window or a DDE conversation.
SetWindowPlacement Sets the show state and the restored, minimized, and
maximized positions of the specified window.
T IT L E DESC RIP T IO N
SetWindowTextA Changes the text of the specified window's title bar (if it has
one). If the specified window is a control, the text of the
control is changed. However, SetWindowText cannot change
the text of a control in another application.
SetWindowTextW Changes the text of the specified window's title bar (if it has
one). If the specified window is a control, the text of the
control is changed. However, SetWindowText cannot change
the text of a control in another application.
ShowCaret Makes the caret visible on the screen at the caret's current
position. When the caret becomes visible, it begins flashing
automatically.
ShowWindowAsync Sets the show state of a window without waiting for the
operation to complete.
ShutdownBlockReasonCreate Indicates that the system cannot be shut down and sets a
reason string to be displayed to the user if system shutdown
is initiated.
ShutdownBlockReasonDestroy Indicates that the system can be shut down and frees the
reason string.
SwapMouseButton Reverses or restores the meaning of the left and right mouse
buttons.
SwitchDesktop Makes the specified desktop visible and activates it. This
enables the desktop to receive input from the user.
WaitForInputIdle Waits until the specified process has finished processing its
initial input and is waiting for user input with no input
pending, or until the time-out interval has elapsed.
Callback functions
T IT L E DESC RIP T IO N
Structures
T IT L E DESC RIP T IO N
FLASHWINFO Contains the flash status for a window and the number of
times the system should flash the window.
MENUGETOBJECTINFO Contains information about the menu that the mouse cursor
is on.
POWERBROADCAST_SETTING Sent with a power setting event and contains data about the
specific change.
RID_DEVICE_INFO Defines the raw input data coming from any device.
RID_DEVICE_INFO_HID Defines the raw input data coming from the specified
Human Interface Device (HID).
RID_DEVICE_INFO_KEYBOARD Defines the raw input data coming from the specified
keyboard.
RID_DEVICE_INFO_MOUSE Defines the raw input data coming from the specified mouse.
TOUCH_HIT_TESTING_PROXIMITY_EVALUATION Contains the hit test score that indicates whether the object
is the likely target of the touch contact area, relative to other
objects that intersect the touch contact area.
Enumerations
T IT L E DESC RIP T IO N
Calculates the required size of the window rectangle, based on the desired client-rectangle size. The window
rectangle can then be passed to the CreateWindow function to create a window whose client area is the desired
size.
To specify an extended window style, use the AdjustWindowRectEx function.
Syntax
BOOL AdjustWindowRect(
LPRECT lpRect,
DWORD dwStyle,
BOOL bMenu
);
Parameters
lpRect
Type: LPRECT
A pointer to a RECT structure that contains the coordinates of the top-left and bottom-right corners of the
desired client area. When the function returns, the structure contains the coordinates of the top-left and bottom-
right corners of the window to accommodate the desired client area.
dwStyle
Type: DWORD
The window style of the window whose required size is to be calculated. Note that you cannot specify the
WS_OVERL APPED style.
bMenu
Type: BOOL
Indicates whether the window has a menu.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
A client rectangle is the smallest rectangle that completely encloses a client area. A window rectangle is the
smallest rectangle that completely encloses the window, which includes the client area and the nonclient area.
The AdjustWindowRect function does not add extra space when a menu bar wraps to two or more rows.
The AdjustWindowRect function does not take the WS_VSCROLL or WS_HSCROLL styles into account. To
account for the scroll bars, call the GetSystemMetrics function with SM_CXVSCROLL or SM_CYHSCROLL .
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AdjustWindowRectEx
Conceptual
CreateWindow
GetSystemMetrics
Other Resources
RECT
Reference
Windows
AdjustWindowRectEx function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Calculates the required size of the window rectangle, based on the desired size of the client rectangle. The
window rectangle can then be passed to the CreateWindowEx function to create a window whose client area is
the desired size.
Syntax
BOOL AdjustWindowRectEx(
LPRECT lpRect,
DWORD dwStyle,
BOOL bMenu,
DWORD dwExStyle
);
Parameters
lpRect
Type: LPRECT
A pointer to a RECT structure that contains the coordinates of the top-left and bottom-right corners of the
desired client area. When the function returns, the structure contains the coordinates of the top-left and bottom-
right corners of the window to accommodate the desired client area.
dwStyle
Type: DWORD
The window style of the window whose required size is to be calculated. Note that you cannot specify the
WS_OVERL APPED style.
bMenu
Type: BOOL
Indicates whether the window has a menu.
dwExStyle
Type: DWORD
The extended window style of the window whose required size is to be calculated.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
A client rectangle is the smallest rectangle that completely encloses a client area. A window rectangle is the
smallest rectangle that completely encloses the window, which includes the client area and the nonclient area.
The AdjustWindowRectEx function does not add extra space when a menu bar wraps to two or more rows.
The AdjustWindowRectEx function does not take the WS_VSCROLL or WS_HSCROLL styles into account. To
account for the scroll bars, call the GetSystemMetrics function with SM_CXVSCROLL or SM_CYHSCROLL .
This API is not DPI aware, and should not be used if the calling thread is per-monitor DPI aware. For the DPI-
aware version of this API, see AdjustWindowsRectExForDPI. For more information on DPI awareness, see the
Windows High DPI documentation.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AdjustWindowsRectExForDPI
Conceptual
CreateWindowEx
Other Resources
RECT
Reference
Windows
AllowSetForegroundWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enables the specified process to set the foreground window using the SetForegroundWindow function. The
calling process must already be able to set the foreground window. For more information, see Remarks later in
this topic.
Syntax
BOOL AllowSetForegroundWindow(
DWORD dwProcessId
);
Parameters
dwProcessId
Type: DWORD
The identifier of the process that will be enabled to set the foreground window. If this parameter is ASFW_ANY ,
all processes will be enabled to set the foreground window.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. The function will fail if the calling process cannot set the foreground
window. To get extended error information, call GetLastError.
Remarks
The system restricts which processes can set the foreground window. A process can set the foreground window
only if one of the following conditions is true:
The process is the foreground process.
The process was started by the foreground process.
The process received the last input event.
There is no foreground process.
The foreground process is being debugged.
The foreground is not locked (see LockSetForegroundWindow).
The foreground lock time-out has expired (see SPI_GETFOREGROUNDLOCKTIMEOUT in
SystemParametersInfo).
No menus are active.
A process that can set the foreground window can enable another process to set the foreground window by calling
AllowSetForegroundWindow . The process specified by dwProcessId loses the ability to set the foreground
window the next time the user generates input, unless the input is directed at that process, or the next time a
process calls AllowSetForegroundWindow , unless that process is specified.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
LockSetForegroundWindow
Reference
SetForegroundWindow
Windows
ALTTABINFO structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagALTTABINFO {
DWORD cbSize;
int cItems;
int cColumns;
int cRows;
int iColFocus;
int iRowFocus;
int cxItem;
int cyItem;
POINT ptStart;
} ALTTABINFO, *PALTTABINFO, *LPALTTABINFO;
Members
cbSize
Type: DWORD
The size, in bytes, of the structure. The caller must set this to sizeof(ALTTABINFO) .
cItems
Type: int
The number of items in the window.
cColumns
Type: int
The number of columns in the window.
cRows
Type: int
The number of rows in the window.
iColFocus
Type: int
The column of the item that has the focus.
iRowFocus
Type: int
The row of the item that has the focus.
cxItem
Type: int
The width of each icon in the application-switching window.
cyItem
Type: int
The height of each icon in the application-switching window.
ptStart
Type: POINT
The top-left corner of the first icon.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GetAltTabInfo
Reference
Windows
AnimateWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enables you to produce special effects when showing or hiding windows. There are four types of animation: roll,
slide, collapse or expand, and alpha-blended fade.
Syntax
BOOL AnimateWindow(
HWND hWnd,
DWORD dwTime,
DWORD dwFlags
);
Parameters
hWnd
Type: HWND
A handle to the window to animate. The calling thread must own this window.
dwTime
Type: DWORD
The time it takes to play the animation, in milliseconds. Typically, an animation takes 200 milliseconds to play.
dwFlags
Type: DWORD
The type of animation. This parameter can be one or more of the following values. Note that, by default, these
flags take effect when showing a window. To take effect when hiding a window, use AW_HIDE and a logical OR
operator with the appropriate flags.
VA L UE M EA N IN G
Animates the window from left to right. This flag can be used
AW_HOR_POSITIVE with roll or slide animation. It is ignored when used with
0x00000001 AW_CENTER or AW_BLEND .
Animates the window from right to left. This flag can be used
AW_HOR_NEGATIVE with roll or slide animation. It is ignored when used with
0x00000002 AW_CENTER or AW_BLEND .
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. The function will fail in the following situations:
If the window is already visible and you are trying to show the window.
If the window is already hidden and you are trying to hide the window.
If there is no direction specified for the slide or roll animation.
When trying to animate a child window with AW_BLEND .
If the thread does not own the window. Note that, in this case, AnimateWindow fails but GetLastError
returns ERROR_SUCCESS .
To get extended error information, call the GetLastError function.
Remarks
To show or hide a window without special effects, use ShowWindow.
When using slide or roll animation, you must specify the direction. It can be either AW_HOR_POSITIVE ,
AW_HOR_NEGATIVE , AW_VER_POSITIVE, or AW_VER_NEGATIVE.
You can combine AW_HOR_POSITIVE or AW_HOR_NEGATIVE with AW_VER_POSITIVE or
AW_VER_NEGATIVE to animate a window diagonally.
The window procedures for the window and its child windows should handle any WM_PRINT or
WM_PRINTCLIENT messages. Dialog boxes, controls, and common controls already handle WM_PRINTCLIENT .
The default window procedure already handles WM_PRINT .
If a child window is displayed partially clipped, when it is animated it will have holes where it is clipped.
AnimateWindow supports RTL windows.
Avoid animating a window that has a drop shadow because it produces visually distracting, jerky animations.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Other Resources
Reference
ShowWindow
WM_PRINT
WM_PRINTCLIENT
Windows
ANIMATIONINFO structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Describes the animation effects associated with user actions. This structure is used with the
SystemParametersInfo function when the SPI_GETANIMATION or SPI_SETANIMATION action value is specified.
Syntax
typedef struct tagANIMATIONINFO {
UINT cbSize;
int iMinAnimate;
} ANIMATIONINFO, *LPANIMATIONINFO;
Members
cbSize
The size of the structure, in bytes. The caller must set this to sizeof(ANIMATIONINFO) .
iMinAnimate
If this member is nonzero, minimize and restore animation is enabled; otherwise it is disabled.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
SystemParametersInfo
AnyPopup function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Indicates whether an owned, visible, top-level pop-up, or overlapped window exists on the screen. The function
searches the entire screen, not just the calling application's client area.
This function is provided only for compatibility with 16-bit versions of Windows. It is generally not useful.
Syntax
BOOL AnyPopup();
Parameters
This function has no parameters.
Return value
Type: BOOL
If a pop-up window exists, the return value is nonzero, even if the pop-up window is completely covered by
other windows.
If a pop-up window does not exist, the return value is zero.
Remarks
This function does not detect unowned pop-up windows or windows that do not have the WS_VISIBLE style bit
set.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetLastActivePopup
Reference
ShowOwnedPopups
Windows
ArrangeIconicWindows function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Arranges all the minimized (iconic) child windows of the specified parent window.
Syntax
UINT ArrangeIconicWindows(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the parent window.
Return value
Type: UINT
If the function succeeds, the return value is the height of one row of icons.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
An application that maintains its own minimized child windows can use the ArrangeIconicWindows function
to arrange icons in a parent window. This function can also arrange icons on the desktop. To retrieve the window
handle to the desktop window, use the GetDesktopWindow function.
An application sends the WM_MDIICONARRANGE message to the multiple-document interface (MDI) client
window to prompt the client window to arrange its minimized MDI child windows.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CloseWindow
Conceptual
GetDesktopWindow
Reference
Windows
AUDIODESCRIPTION structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information associated with audio descriptions. This structure is used with the SystemParametersInfo
function when the SPI_GETAUDIODESCRIPTION or SPI_SETAUDIODESCRIPTION action value is specified.
Syntax
typedef struct tagAUDIODESCRIPTION {
UINT cbSize;
BOOL Enabled;
LCID Locale;
} AUDIODESCRIPTION, *LPAUDIODESCRIPTION;
Members
cbSize
The size of the structure, in bytes. The caller must set this member to sizeof(AUDIODESCRIPTION) .
Enabled
If this member is TRUE , audio descriptions are enabled; Otherwise, this member is FALSE .
Locale
The locale identifier (LCID) of the language for the audio description. For more information, see Locales and
Languages.
Remarks
To compile an application that uses this structure, define _WIN32_WINNT as 0x0600 or later. For more
information, see Using the Windows Headers.
Requirements
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
See also
SystemParametersInfo
BeginDeferWindowPos function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Allocates memory for a multiple-window- position structure and returns the handle to the structure.
Syntax
HDWP BeginDeferWindowPos(
int nNumWindows
);
Parameters
nNumWindows
Type: int
The initial number of windows for which to store position information. The DeferWindowPos function increases
the size of the structure, if necessary.
Return value
Type: HDWP
If the function succeeds, the return value identifies the multiple-window-position structure. If insufficient system
resources are available to allocate the structure, the return value is NULL . To get extended error information, call
GetLastError.
Remarks
The multiple-window-position structure is an internal structure; an application cannot access it directly.
DeferWindowPos fills the multiple-window-position structure with information about the target position for one
or more windows about to be moved. The EndDeferWindowPos function accepts the handle to this structure and
repositions the windows by using the information stored in the structure.
If any of the windows in the multiple-window- position structure have the SWP_HIDEWINDOW or
SWP_SHOWWINDOW flag set, none of the windows are repositioned.
If the system must increase the size of the multiple-window- position structure beyond the initial size specified
by the nNumWindows parameter but cannot allocate enough memory to do so, the system fails the entire
window positioning sequence (BeginDeferWindowPos , DeferWindowPos, and EndDeferWindowPos). By
specifying the maximum size needed, an application can detect and process failure early in the process.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
DeferWindowPos
EndDeferWindowPos
Reference
SetWindowPos
Windows
BringWindowToTop function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Brings the specified window to the top of the Z order. If the window is a top-level window, it is activated. If the
window is a child window, the top-level parent window associated with the child window is activated.
Syntax
BOOL BringWindowToTop(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to bring to the top of the Z order.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Use the BringWindowToTop function to uncover any window that is partially or completely obscured by other
windows.
Calling this function is similar to calling the SetWindowPos function to change a window's position in the Z
order. BringWindowToTop does not make a window a top-level window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
SetWindowPos
Windows
BroadcastSystemMessage function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sends a message to the specified recipients. The recipients can be applications, installable drivers, network
drivers, system-level device drivers, or any combination of these system components.
To receive additional information if the request is defined, use the BroadcastSystemMessageEx function.
Syntax
long BroadcastSystemMessage(
DWORD flags,
LPDWORD lpInfo,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
flags
Type: DWORD
The broadcast option. This parameter can be one or more of the following values.
VA L UE M EA N IN G
lpInfo
Type: LPDWORD
A pointer to a variable that contains and receives information about the recipients of the message.
When the function returns, this variable receives a combination of these values identifying which recipients
actually received the message.
If this parameter is NULL , the function broadcasts to all components.
This parameter can be one or more of the following values.
VA L UE M EA N IN G
Broadcast to applications.
BSM_APPLICATIONS
0x00000008
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: long
If the function succeeds, the return value is a positive value.
If the function is unable to broadcast the message, the return value is –1.
If the dwFlags parameter is BSF_QUERY and at least one recipient returned BROADCAST_QUERY_DENY to
the corresponding message, the return value is zero. To get extended error information, call GetLastError.
Remarks
If BSF_QUERY is not specified, the function sends the specified message to all requested recipients, ignoring
values returned by those recipients.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
Examples
For an example, see Terminating a Process.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
BroadcastSystemMessageEx
Conceptual
Messages and Message Queues
Reference
SendNotifyMessage
BroadcastSystemMessageExA function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Sends a message to the specified recipients. The recipients can be applications, installable drivers, network
drivers, system-level device drivers, or any combination of these system components.
This function is similar to BroadcastSystemMessage except that this function can return more information from
the recipients.
Syntax
long BroadcastSystemMessageExA(
DWORD flags,
LPDWORD lpInfo,
UINT Msg,
WPARAM wParam,
LPARAM lParam,
PBSMINFO pbsmInfo
);
Parameters
flags
Type: DWORD
The broadcast option. This parameter can be one or more of the following values.
VA L UE M EA N IN G
lpInfo
Type: LPDWORD
A pointer to a variable that contains and receives information about the recipients of the message.
When the function returns, this variable receives a combination of these values identifying which recipients
actually received the message.
If this parameter is NULL , the function broadcasts to all components.
This parameter can be one or more of the following values.
VA L UE M EA N IN G
Broadcast to applications.
BSM_APPLICATIONS
0x00000008
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
pbsmInfo
Type: PBSMINFO
A pointer to a BSMINFO structure that contains additional information if the request is denied and dwFlags is set
to BSF_QUERY .
Return value
Type: long
If the function succeeds, the return value is a positive value.
If the function is unable to broadcast the message, the return value is –1.
If the dwFlags parameter is BSF_QUERY and at least one recipient returned BROADCAST_QUERY_DENY to
the corresponding message, the return value is zero. To get extended error information, call GetLastError.
Remarks
If BSF_QUERY is not specified, the function sends the specified message to all requested recipients, ignoring
values returned by those recipients.
If the caller's thread is on a desktop other than that of the window that denied the request, the caller must call
SetThreadDesktop(hdesk) to query anything on that window. Also, the caller must call CloseDesktop on the
returned hdesk handle.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
NOTE
The winuser.h header defines BroadcastSystemMessageEx 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
Minimum suppor ted client Windows XP [desktop apps only]
Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
BSMINFO
BroadcastSystemMessage
Conceptual
Messages and Message Queues
Reference
SendNotifyMessage
BroadcastSystemMessageExW function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Sends a message to the specified recipients. The recipients can be applications, installable drivers, network
drivers, system-level device drivers, or any combination of these system components.
This function is similar to BroadcastSystemMessage except that this function can return more information from
the recipients.
Syntax
long BroadcastSystemMessageExW(
DWORD flags,
LPDWORD lpInfo,
UINT Msg,
WPARAM wParam,
LPARAM lParam,
PBSMINFO pbsmInfo
);
Parameters
flags
Type: DWORD
The broadcast option. This parameter can be one or more of the following values.
VA L UE M EA N IN G
lpInfo
Type: LPDWORD
A pointer to a variable that contains and receives information about the recipients of the message.
When the function returns, this variable receives a combination of these values identifying which recipients
actually received the message.
If this parameter is NULL , the function broadcasts to all components.
This parameter can be one or more of the following values.
VA L UE M EA N IN G
Broadcast to applications.
BSM_APPLICATIONS
0x00000008
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
pbsmInfo
Type: PBSMINFO
A pointer to a BSMINFO structure that contains additional information if the request is denied and dwFlags is set
to BSF_QUERY .
Return value
Type: long
If the function succeeds, the return value is a positive value.
If the function is unable to broadcast the message, the return value is –1.
If the dwFlags parameter is BSF_QUERY and at least one recipient returned BROADCAST_QUERY_DENY to
the corresponding message, the return value is zero. To get extended error information, call GetLastError.
Remarks
If BSF_QUERY is not specified, the function sends the specified message to all requested recipients, ignoring
values returned by those recipients.
If the caller's thread is on a desktop other than that of the window that denied the request, the caller must call
SetThreadDesktop(hdesk) to query anything on that window. Also, the caller must call CloseDesktop on the
returned hdesk handle.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
NOTE
The winuser.h header defines BroadcastSystemMessageEx 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
Minimum suppor ted client Windows XP [desktop apps only]
Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
BSMINFO
BroadcastSystemMessage
Conceptual
Messages and Message Queues
Reference
SendNotifyMessage
BroadcastSystemMessageW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sends a message to the specified recipients. The recipients can be applications, installable drivers, network
drivers, system-level device drivers, or any combination of these system components.
To receive additional information if the request is defined, use the BroadcastSystemMessageEx function.
Syntax
long BroadcastSystemMessageW(
DWORD flags,
LPDWORD lpInfo,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
flags
Type: DWORD
The broadcast option. This parameter can be one or more of the following values.
VA L UE M EA N IN G
lpInfo
Type: LPDWORD
A pointer to a variable that contains and receives information about the recipients of the message.
When the function returns, this variable receives a combination of these values identifying which recipients
actually received the message.
If this parameter is NULL , the function broadcasts to all components.
This parameter can be one or more of the following values.
VA L UE M EA N IN G
Broadcast to applications.
BSM_APPLICATIONS
0x00000008
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: long
If the function succeeds, the return value is a positive value.
If the function is unable to broadcast the message, the return value is –1.
If the dwFlags parameter is BSF_QUERY and at least one recipient returned BROADCAST_QUERY_DENY to
the corresponding message, the return value is zero. To get extended error information, call GetLastError.
Remarks
If BSF_QUERY is not specified, the function sends the specified message to all requested recipients, ignoring
values returned by those recipients.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
Examples
For an example, see Terminating a Process.
NOTE
The winuser.h header defines BroadcastSystemMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
BroadcastSystemMessageEx
Conceptual
Messages and Message Queues
Reference
SendNotifyMessage
BSMINFO structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct {
UINT cbSize;
HDESK hdesk;
HWND hwnd;
LUID luid;
} BSMINFO, *PBSMINFO;
Members
cbSize
Type: UINT
The size, in bytes, of this structure.
hdesk
Type: HDESK
A desktop handle to the window specified by hwnd . This value is returned only if BroadcastSystemMessageEx
specifies BSF_RETURNHDESK and BSF_QUERY .
hwnd
Type: HWND
A handle to the window that denied the request. This value is returned if BroadcastSystemMessageEx specifies
BSF_QUERY .
luid
Type: LUID
A locally unique identifier (LUID) for the window.
Requirements
Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Calculates an appropriate pop-up window position using the specified anchor point, pop-up window size, flags,
and the optional exclude rectangle. When the specified pop-up window size is smaller than the desktop window
size, use the CalculatePopupWindowPosition function to ensure that the pop-up window is fully visible on
the desktop window, regardless of the specified anchor point.
Syntax
BOOL CalculatePopupWindowPosition(
const POINT *anchorPoint,
const SIZE *windowSize,
UINT flags,
RECT *excludeRect,
RECT *popupWindowPosition
);
Parameters
anchorPoint
Type: UINT
Use one of the following flags to specify how the function positions the pop-up window horizontally and
vertically. The flags are the same as the vertical and horizontal positioning flags of the TrackPopupMenuEx
function.
Use one of the following flags to specify how the function positions the pop-up window horizontally.
VA L UE M EA N IN G
Uses one of the following flags to specify how the function positions the pop-up window vertically.
VA L UE M EA N IN G
Use one of the following flags to specify whether to accommodate horizontal or vertical alignment.
VA L UE M EA N IN G
VA L UE M EA N IN G
excludeRect
Type: RECT *
A pointer to a structure that specifies the exclude rectangle. It can be NULL .
popupWindowPosition
Type: RECT *
A pointer to a structure that specifies the pop-up window position.
Return value
Type: BOOL
If the function succeeds, it returns TRUE ; otherwise, it returns FALSE . To get extended error information, call
GetLastError.
Remarks
TPM_WORKAREA is supported for the TrackPopupMenu and TrackPopupMenuEx functions.
Requirements
Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Reference
TrackPopupMenu
TrackPopupMenuEx
CallMsgFilterA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Passes the specified message and hook code to the hook procedures associated with the WH_SYSMSGFILTER
and WH_MSGFILTER hooks. A WH_SYSMSGFILTER or WH_MSGFILTER hook procedure is an application-
defined callback function that examines and, optionally, modifies messages for a dialog box, message box, menu,
or scroll bar.
Syntax
BOOL CallMsgFilterA(
LPMSG lpMsg,
int nCode
);
Parameters
lpMsg
Type: LPMSG
A pointer to an MSG structure that contains the message to be passed to the hook procedures.
nCode
Type: int
An application-defined code used by the hook procedure to determine how to process the message. The code
must not have the same value as system-defined hook codes (MSGF_ and HC_) associated with the
WH_SYSMSGFILTER and WH_MSGFILTER hooks.
Return value
Type: BOOL
If the application should process the message further, the return value is zero.
If the application should not process the message further, the return value is nonzero.
Remarks
The system calls CallMsgFilter to enable applications to examine and control the flow of messages during
internal processing of dialog boxes, message boxes, menus, and scroll bars, or when the user activates a
different window by pressing the ALT+TAB key combination.
Install this hook procedure by using the SetWindowsHookEx function.
Examples
For an example, see WH_MSGFILTER and WH_SYSMSGFILTER Hooks.
NOTE
The winuser.h header defines CallMsgFilter 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Hooks
MSG
MessageProc
Reference
SetWindowsHookEx
SysMsgProc
CallMsgFilterW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Passes the specified message and hook code to the hook procedures associated with the WH_SYSMSGFILTER
and WH_MSGFILTER hooks. A WH_SYSMSGFILTER or WH_MSGFILTER hook procedure is an application-
defined callback function that examines and, optionally, modifies messages for a dialog box, message box, menu,
or scroll bar.
Syntax
BOOL CallMsgFilterW(
LPMSG lpMsg,
int nCode
);
Parameters
lpMsg
Type: LPMSG
A pointer to an MSG structure that contains the message to be passed to the hook procedures.
nCode
Type: int
An application-defined code used by the hook procedure to determine how to process the message. The code
must not have the same value as system-defined hook codes (MSGF_ and HC_) associated with the
WH_SYSMSGFILTER and WH_MSGFILTER hooks.
Return value
Type: BOOL
If the application should process the message further, the return value is zero.
If the application should not process the message further, the return value is nonzero.
Remarks
The system calls CallMsgFilter to enable applications to examine and control the flow of messages during
internal processing of dialog boxes, message boxes, menus, and scroll bars, or when the user activates a
different window by pressing the ALT+TAB key combination.
Install this hook procedure by using the SetWindowsHookEx function.
Examples
For an example, see WH_MSGFILTER and WH_SYSMSGFILTER Hooks.
NOTE
The winuser.h header defines CallMsgFilter 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Hooks
MSG
MessageProc
Reference
SetWindowsHookEx
SysMsgProc
CallNextHookEx function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Passes the hook information to the next hook procedure in the current hook chain. A hook procedure can call
this function either before or after processing the hook information.
Syntax
LRESULT CallNextHookEx(
HHOOK hhk,
int nCode,
WPARAM wParam,
LPARAM lParam
);
Parameters
hhk
Type: HHOOK
This parameter is ignored.
nCode
Type: int
The hook code passed to the current hook procedure. The next hook procedure uses this code to determine how
to process the hook information.
wParam
Type: WPARAM
The wParam value passed to the current hook procedure. The meaning of this parameter depends on the type of
hook associated with the current hook chain.
lParam
Type: LPARAM
The lParam value passed to the current hook procedure. The meaning of this parameter depends on the type of
hook associated with the current hook chain.
Return value
Type: LRESULT
This value is returned by the next hook procedure in the chain. The current hook procedure must also return this
value. The meaning of the return value depends on the hook type. For more information, see the descriptions of
the individual hook procedures.
Remarks
Hook procedures are installed in chains for particular hook types. CallNextHookEx calls the next hook in the
chain.
Calling CallNextHookEx is optional, but it is highly recommended; otherwise, other applications that have
installed hooks will not receive hook notifications and may behave incorrectly as a result. You should call
CallNextHookEx unless you absolutely need to prevent the notification from being seen by other applications.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Hooks
Reference
SetWindowsHookEx
UnhookWindowsHookEx
CallWindowProcA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
LRESULT CallWindowProcA(
WNDPROC lpPrevWndFunc,
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
lpPrevWndFunc
Type: WNDPROC
The previous window procedure. If this value is obtained by calling the GetWindowLong function with the
nIndex parameter set to GWL_WNDPROC or DWL_DLGPROC , it is actually either the address of a window or
dialog box procedure, or a special internal value meaningful only to CallWindowProc .
hWnd
Type: HWND
A handle to the window procedure to receive the message.
Msg
Type: UINT
The message.
wParam
Type: WPARAM
Additional message-specific information. The contents of this parameter depend on the value of the Msg
parameter.
lParam
Type: LPARAM
Additional message-specific information. The contents of this parameter depend on the value of the Msg
parameter.
Return value
Type: LRESULT
The return value specifies the result of the message processing and depends on the message sent.
Remarks
Use the CallWindowProc function for window subclassing. Usually, all windows with the same class share one
window procedure. A subclass is a window or set of windows with the same class whose messages are
intercepted and processed by another window procedure (or procedures) before being passed to the window
procedure of the class.
The SetWindowLong function creates the subclass by changing the window procedure associated with a
particular window, causing the system to call the new window procedure instead of the previous one. An
application must pass any messages not processed by the new window procedure to the previous window
procedure by calling CallWindowProc . This allows the application to create a chain of window procedures.
If STRICT is defined, the lpPrevWndFunc parameter has the data type WNDPROC . The WNDPROC type is
declared as follows:
If STRICT is not defined, the lpPrevWndFunc parameter has the data type FARPROC . The FARPROC type is
declared as follows:
In C, the FARPROC declaration indicates a callback function that has an unspecified parameter list. In C++,
however, the empty parameter list in the declaration indicates that a function has no parameters. This subtle
distinction can break careless code. Following is one way to handle this situation:
#ifdef STRICT
WNDPROC MyWindowProcedure
#else
FARPROC MyWindowProcedure
#endif
...
lResult = CallWindowProc(MyWindowProcedure, ...) ;
For further information about functions declared with empty argument lists, refer to
The C++ Programming Language, Second Edition, by Bjarne Stroustrup.
The CallWindowProc function handles Unicode-to-ANSI conversion. You cannot take advantage of this
conversion if you call the window procedure directly.
Examples
For an example, see Subclassing a Window
NOTE
The winuser.h header defines CallWindowProc 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowLong
Reference
SetClassLong
SetWindowLong
Window Procedures
CallWindowProcW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
LRESULT CallWindowProcW(
WNDPROC lpPrevWndFunc,
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
lpPrevWndFunc
Type: WNDPROC
The previous window procedure. If this value is obtained by calling the GetWindowLong function with the
nIndex parameter set to GWL_WNDPROC or DWL_DLGPROC , it is actually either the address of a window or
dialog box procedure, or a special internal value meaningful only to CallWindowProc .
hWnd
Type: HWND
A handle to the window procedure to receive the message.
Msg
Type: UINT
The message.
wParam
Type: WPARAM
Additional message-specific information. The contents of this parameter depend on the value of the Msg
parameter.
lParam
Type: LPARAM
Additional message-specific information. The contents of this parameter depend on the value of the Msg
parameter.
Return value
Type: LRESULT
The return value specifies the result of the message processing and depends on the message sent.
Remarks
Use the CallWindowProc function for window subclassing. Usually, all windows with the same class share one
window procedure. A subclass is a window or set of windows with the same class whose messages are
intercepted and processed by another window procedure (or procedures) before being passed to the window
procedure of the class.
The SetWindowLong function creates the subclass by changing the window procedure associated with a
particular window, causing the system to call the new window procedure instead of the previous one. An
application must pass any messages not processed by the new window procedure to the previous window
procedure by calling CallWindowProc . This allows the application to create a chain of window procedures.
If STRICT is defined, the lpPrevWndFunc parameter has the data type WNDPROC . The WNDPROC type is
declared as follows:
If STRICT is not defined, the lpPrevWndFunc parameter has the data type FARPROC . The FARPROC type is
declared as follows:
In C, the FARPROC declaration indicates a callback function that has an unspecified parameter list. In C++,
however, the empty parameter list in the declaration indicates that a function has no parameters. This subtle
distinction can break careless code. Following is one way to handle this situation:
#ifdef STRICT
WNDPROC MyWindowProcedure
#else
FARPROC MyWindowProcedure
#endif
...
lResult = CallWindowProc(MyWindowProcedure, ...) ;
For further information about functions declared with empty argument lists, refer to
The C++ Programming Language, Second Edition, by Bjarne Stroustrup.
The CallWindowProc function handles Unicode-to-ANSI conversion. You cannot take advantage of this
conversion if you call the window procedure directly.
Examples
For an example, see Subclassing a Window
NOTE
The winuser.h header defines CallWindowProc 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowLong
Reference
SetClassLong
SetWindowLong
Window Procedures
CascadeWindows function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
WORD CascadeWindows(
HWND hwndParent,
UINT wHow,
const RECT *lpRect,
UINT cKids,
const HWND *lpKids
);
Parameters
hwndParent
Type: HWND
A handle to the parent window. If this parameter is NULL , the desktop window is assumed.
wHow
Type: UINT
A cascade flag. This parameter can be one or more of the following values.
VA L UE M EA N IN G
lpRect
Type: UINT
The number of elements in the array specified by the lpKids parameter. This parameter is ignored if lpKids is
NULL .
lpKids
Type: const HWND*
An array of handles to the child windows to arrange. If a specified child window is a top-level window with the
style WS_EX_TOPMOST or WS_EX_TOOLWINDOW , the child window is not arranged. If this parameter is
NULL , all child windows of the specified parent window (or of the desktop window) are arranged.
Return value
Type: WORD
If the function succeeds, the return value is the number of windows arranged.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
By default, CascadeWindows arranges the windows in the order provided by the lpKids array, but preserves
the Z-Order. If you specify the MDITILE_ZORDER flag, CascadeWindows arranges the windows in Z order.
Calling CascadeWindows causes all maximized windows to be restored to their previous size.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Windows Overview
CBT_CREATEWNDA structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information passed to a WH_CBT hook procedure, CBTProc, before a window is created.
Syntax
typedef struct tagCBT_CREATEWNDA {
struct tagCREATESTRUCTA *lpcs;
HWND hwndInsertAfter;
} CBT_CREATEWNDA, *LPCBT_CREATEWNDA;
Members
lpcs
Type: LPCREATESTRUCT
A pointer to a CREATESTRUCT structure that contains initialization parameters for the window about to be
created.
hwndInsertAfter
Type: HWND
A handle to the window whose position in the Z order precedes that of the window being created. This member
can also be NULL .
Remarks
NOTE
The winuser.h header defines CBT_CREATEWND 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
CBTProc
CREATESTRUCT
Conceptual
Hooks
Reference
SetWindowsHookEx
CBT_CREATEWNDW structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information passed to a WH_CBT hook procedure, CBTProc, before a window is created.
Syntax
typedef struct tagCBT_CREATEWNDW {
struct tagCREATESTRUCTW *lpcs;
HWND hwndInsertAfter;
} CBT_CREATEWNDW, *LPCBT_CREATEWNDW;
Members
lpcs
Type: LPCREATESTRUCT
A pointer to a CREATESTRUCT structure that contains initialization parameters for the window about to be
created.
hwndInsertAfter
Type: HWND
A handle to the window whose position in the Z order precedes that of the window being created. This member
can also be NULL .
Remarks
NOTE
The winuser.h header defines CBT_CREATEWND 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
CBTProc
CREATESTRUCT
Conceptual
Hooks
Reference
SetWindowsHookEx
CBTACTIVATESTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information passed to a WH_CBT hook procedure, CBTProc, before a window is activated.
Syntax
typedef struct tagCBTACTIVATESTRUCT {
BOOL fMouse;
HWND hWndActive;
} CBTACTIVATESTRUCT, *LPCBTACTIVATESTRUCT;
Members
fMouse
Type: BOOL
This member is TRUE if a mouse click is causing the activation or FALSE if it is not.
hWndActive
Type: HWND
A handle to the active window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
CBTProc
Conceptual
Hooks
Reference
SetWindowsHookEx
CHANGEFILTERSTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagCHANGEFILTERSTRUCT {
DWORD cbSize;
DWORD ExtStatus;
} CHANGEFILTERSTRUCT, *PCHANGEFILTERSTRUCT;
Members
cbSize
Type: DWORD
The size of the structure, in bytes. Must be set to sizeof(CHANGEFILTERSTRUCT) , otherwise the function fails with
ERROR_INVALID_PARAMETER .
ExtStatus
Type: DWORD
If the function succeeds, this field contains one of the following values.
VA L UE M EA N IN G
Remarks
Certain messages whose value is smaller than WM_USER are required to pass through the filter, regardless of
the filter setting. There will be no effect when you attempt to use this function to allow or block such messages.
An application may use the ChangeWindowMessageFilter function to allow or block a message in a process-
wide manner. If the message is allowed by either the process message filter or the window message filter, it will
be delivered to the window.
The following table lists the possible values returned in ExtStatus .
M ESSA GE A L REA DY M ESSA GE A L REA DY O P ERAT IO N REQ UEST ED IN DIC ATO R RET URN ED IN
A L LO W ED AT H IGH ER SC O P E A L LO W ED B Y W IN DO W 'S EXT STAT US O N SUC C ESS
M ESSA GE F ILT ER
No No MSGFLT_ALLOW MSGFLTINFO_NONE
No No MSGFLT_DISALLOW MSGFLTINFO_ALREADY
DISALLOWED_FORWND
No No MSGFLT_RESET MSGFLTINFO_NONE
Requirements
Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
See also
ChangeWindowMessageFilterEx
ChangeWindowMessageFilter function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL ChangeWindowMessageFilter(
UINT message,
DWORD dwFlag
);
Parameters
message
Type: UINT
The message to add to or remove from the filter.
dwFlag
Type: DWORD
The action to be performed. One of the following values.
VA L UE M EA N IN G
Adds the message to the filter. This has the effect of allowing
MSGFLT_ADD the message to be received.
1
Removes the message from the filter. This has the effect of
MSGFLT_REMOVE blocking the message.
2
Return value
Type: BOOL
TRUE if successful; otherwise, FALSE . To get extended error information, call GetLastError.
Note A message can be successfully removed from the filter, but that is not a guarantee that the message will be blocked.
See the Remarks section for more details.
Remarks
UIPI is a security feature that prevents messages from being received from a lower integrity level sender. All
such messages with a value above WM_USER are blocked by default. The filter, somewhat contrary to intuition,
is a list of messages that are allowed through. Therefore, adding a message to the filter allows that message to
be received from a lower integrity sender, while removing a message blocks that message from being received.
Certain messages with a value less than WM_USER are required to pass through the filter regardless of the
filter setting. You can call this function to remove one of those messages from the filter and it will return TRUE .
However, the message will still be received by the calling process.
Processes at or below SECURITY_MANDATORY_LOW_RID are not allowed to change the filter. If those
processes call this function, it will fail.
For more information on integrity levels, see Understanding and Working in Protected Mode Internet Explorer.
Requirements
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
Librar y User32.lib
DLL User32.dll
ChangeWindowMessageFilterEx function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Modifies the User Interface Privilege Isolation (UIPI) message filter for a specified window.
Syntax
BOOL ChangeWindowMessageFilterEx(
HWND hwnd,
UINT message,
DWORD action,
PCHANGEFILTERSTRUCT pChangeFilterStruct
);
Parameters
hwnd
Type: HWND
A handle to the window whose UIPI message filter is to be modified.
message
Type: UINT
The message that the message filter allows through or blocks.
action
Type: DWORD
The action to be performed, and can take one of the following values:
VA L UE M EA N IN G
pChangeFilterStruct
Type: PCHANGEFILTERSTRUCT
Optional pointer to a CHANGEFILTERSTRUCT structure.
Return value
Type: BOOL
If the function succeeds, it returns TRUE ; otherwise, it returns FALSE . To get extended error information, call
GetLastError.
Remarks
UIPI is a security feature that prevents messages from being received from a lower-integrity-level sender. You
can use this function to allow specific messages to be delivered to a window even if the message originates
from a process at a lower integrity level. Unlike the ChangeWindowMessageFilter function, which controls the
process message filter, the ChangeWindowMessageFilterEx function controls the window message filter.
An application may use the ChangeWindowMessageFilter function to allow or block a message in a process-
wide manner. If the message is allowed by either the process message filter or the window message filter, it will
be delivered to the window.
Note that processes at or below SECURITY_MANDATORY_LOW_RID are not allowed to change the message
filter. If those processes call this function, it will fail and generate the extended error code,
ERROR_ACCESS_DENIED .
Certain messages whose value is smaller than WM_USER are required to be passed through the filter,
regardless of the filter setting. There will be no effect when you attempt to use this function to allow or block
such messages.
Requirements
Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
ChangeWindowMessageFilter
Conceptual
Reference
Windows
ChildWindowFromPoint function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Determines which, if any, of the child windows belonging to a parent window contains the specified point. The
search is restricted to immediate child windows. Grandchildren, and deeper descendant windows are not
searched.
To skip certain child windows, use the ChildWindowFromPointEx function.
Syntax
HWND ChildWindowFromPoint(
HWND hWndParent,
POINT Point
);
Parameters
hWndParent
Type: HWND
A handle to the parent window.
Point
Type: POINT
A structure that defines the client coordinates, relative to hWndParent, of the point to be checked.
Return value
Type: HWND
The return value is a handle to the child window that contains the point, even if the child window is hidden or
disabled. If the point lies outside the parent window, the return value is NULL . If the point is within the parent
window but not within any child window, the return value is a handle to the parent window.
Remarks
The system maintains an internal list, containing the handles of the child windows associated with a parent
window. The order of the handles in the list depends on the Z order of the child windows. If more than one child
window contains the specified point, the system returns a handle to the first window in the list that contains the
point.
ChildWindowFromPoint treats an HTTRANSPARENT area of a standard control the same as other parts of
the control. In contrast, RealChildWindowFromPoint treats an HTTRANSPARENT area differently; it returns the
child window behind a transparent area of a control. For example, if the point is in a transparent area of a
groupbox, ChildWindowFromPoint returns the groupbox while RealChildWindowFromPoint returns the
child window behind the groupbox. However, both APIs return a static field, even though it, too, returns
HTTRANSPARENT .
Examples
For an example, see "Creating a Combo Box Toolbar" in Using Combo Boxes.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
ChildWindowFromPointEx
Conceptual
Other Resources
POINT
RealChildWindowFromPoint
Reference
WindowFromPoint
Windows
ChildWindowFromPointEx function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Determines which, if any, of the child windows belonging to the specified parent window contains the specified
point. The function can ignore invisible, disabled, and transparent child windows. The search is restricted to
immediate child windows. Grandchildren and deeper descendants are not searched.
Syntax
HWND ChildWindowFromPointEx(
HWND hwnd,
POINT pt,
UINT flags
);
Parameters
hwnd
Type: HWND
A handle to the parent window.
pt
Type: POINT
A structure that defines the client coordinates (relative to hwndParent) of the point to be checked.
flags
Type: UINT
The child windows to be skipped. This parameter can be one or more of the following values.
VA L UE M EA N IN G
Remarks
The system maintains an internal list that contains the handles of the child windows associated with a parent
window. The order of the handles in the list depends on the Z order of the child windows. If more than one child
window contains the specified point, the system returns a handle to the first window in the list that contains the
point and meets the criteria specified by uFlags.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Other Resources
POINT
Reference
WindowFromPoint
Windows
CLIENTCREATESTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information about the menu and first multiple-document interface (MDI) child window of an MDI client
window. An application passes a pointer to this structure as the lpParam parameter of the CreateWindow
function when creating an MDI client window.
Syntax
typedef struct tagCLIENTCREATESTRUCT {
HANDLE hWindowMenu;
UINT idFirstChild;
} CLIENTCREATESTRUCT, *LPCLIENTCREATESTRUCT;
Members
hWindowMenu
Type: HANDLE
A handle to the MDI application's window menu. An MDI application can retrieve this handle from the menu of
the MDI frame window by using the GetSubMenu function.
idFirstChild
Type: UINT
The child window identifier of the first MDI child window created. The system increments the identifier for each
additional MDI child window the application creates, and reassigns identifiers when the application destroys a
window to keep the range of identifiers contiguous. These identifiers are used in WM_COMMAND messages
sent to the application's MDI frame window when a child window is chosen from the window menu; they should
not conflict with any other command identifiers.
Remarks
When the MDI client window is created by calling CreateWindow, the system sends a WM_CREATE message to
the window. The lParam parameter of WM_CREATE contains a pointer to a CREATESTRUCT structure. The
lpCreateParams member of this structure contains a pointer to a CLIENTCREATESTRUCT structure.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
About the Multiple Document Interface
Conceptual
CreateWindow
GetSubMenu
MDICREATESTRUCT
Reference
WM_COMMAND
Windows
CloseWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL CloseWindow(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to be minimized.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
To destroy a window, an application must use the DestroyWindow function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Syntax
HWND CreateMDIWindowA(
LPCSTR lpClassName,
LPCSTR lpWindowName,
DWORD dwStyle,
int X,
int Y,
int nWidth,
int nHeight,
HWND hWndParent,
HINSTANCE hInstance,
LPARAM lParam
);
Parameters
lpClassName
Type: LPCTSTR
The window class of the MDI child window. The class name must have been registered by a call to the
RegisterClassEx function.
lpWindowName
Type: LPCTSTR
The window name. The system displays the name in the title bar of the child window.
dwStyle
Type: DWORD
The style of the MDI child window. If the MDI client window is created with the MDIS_ALLCHILDSTYLES
window style, this parameter can be any combination of the window styles listed in the Window Styles page.
Otherwise, this parameter is limited to one or more of the following values.
VA L UE M EA N IN G
Type: int
The initial horizontal position, in client coordinates, of the MDI child window. If this parameter is
CW_USEDEFAULT ((int)0x80000000), the MDI child window is assigned the default horizontal position.
Y
Type: int
The initial vertical position, in client coordinates, of the MDI child window. If this parameter is
CW_USEDEFAULT , the MDI child window is assigned the default vertical position.
nWidth
Type: int
The initial width, in device units, of the MDI child window. If this parameter is CW_USEDEFAULT , the MDI child
window is assigned the default width.
nHeight
Type: int
The initial height, in device units, of the MDI child window. If this parameter is set to CW_USEDEFAULT , the MDI
child window is assigned the default height.
hWndParent
Type: HWND
A handle to the MDI client window that will be the parent of the new MDI child window.
hInstance
Type: HINSTANCE
A handle to the instance of the application creating the MDI child window.
lParam
Type: LPARAM
An application-defined value.
Return value
Type: HWND
If the function succeeds, the return value is the handle to the created window.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
NOTE
The winuser.h header defines CreateMDIWindow 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
CreateWindow
Multiple Document Interface
Reference
RegisterClassEx
WM_MDICREATE
CreateMDIWindowW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
HWND CreateMDIWindowW(
LPCWSTR lpClassName,
LPCWSTR lpWindowName,
DWORD dwStyle,
int X,
int Y,
int nWidth,
int nHeight,
HWND hWndParent,
HINSTANCE hInstance,
LPARAM lParam
);
Parameters
lpClassName
Type: LPCTSTR
The window class of the MDI child window. The class name must have been registered by a call to the
RegisterClassEx function.
lpWindowName
Type: LPCTSTR
The window name. The system displays the name in the title bar of the child window.
dwStyle
Type: DWORD
The style of the MDI child window. If the MDI client window is created with the MDIS_ALLCHILDSTYLES
window style, this parameter can be any combination of the window styles listed in the Window Styles page.
Otherwise, this parameter is limited to one or more of the following values.
VA L UE M EA N IN G
Type: int
The initial horizontal position, in client coordinates, of the MDI child window. If this parameter is
CW_USEDEFAULT ((int)0x80000000), the MDI child window is assigned the default horizontal position.
Y
Type: int
The initial vertical position, in client coordinates, of the MDI child window. If this parameter is
CW_USEDEFAULT , the MDI child window is assigned the default vertical position.
nWidth
Type: int
The initial width, in device units, of the MDI child window. If this parameter is CW_USEDEFAULT , the MDI child
window is assigned the default width.
nHeight
Type: int
The initial height, in device units, of the MDI child window. If this parameter is set to CW_USEDEFAULT , the MDI
child window is assigned the default height.
hWndParent
Type: HWND
A handle to the MDI client window that will be the parent of the new MDI child window.
hInstance
Type: HINSTANCE
A handle to the instance of the application creating the MDI child window.
lParam
Type: LPARAM
An application-defined value.
Return value
Type: HWND
If the function succeeds, the return value is the handle to the created window.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
NOTE
The winuser.h header defines CreateMDIWindow 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
CreateWindow
Multiple Document Interface
Reference
RegisterClassEx
WM_MDICREATE
CREATESTRUCTA structure (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Defines the initialization parameters passed to the window procedure of an application. These members are
identical to the parameters of the CreateWindowEx function.
Syntax
typedef struct tagCREATESTRUCTA {
LPVOID lpCreateParams;
HINSTANCE hInstance;
HMENU hMenu;
HWND hwndParent;
int cy;
int cx;
int y;
int x;
LONG style;
LPCSTR lpszName;
LPCSTR lpszClass;
DWORD dwExStyle;
} CREATESTRUCTA, *LPCREATESTRUCTA;
Members
lpCreateParams
Type: LPVOID
Contains additional data which may be used to create the window. If the window is being created as a result of a
call to the CreateWindow or CreateWindowEx function, this member contains the value of the lpParam
parameter specified in the function call.
If the window being created is a MDI client window, this member contains a pointer to a CLIENTCREATESTRUCT
structure. If the window being created is a MDI child window, this member contains a pointer to an
MDICREATESTRUCT structure.
If the window is being created from a dialog template, this member is the address of a SHORT value that
specifies the size, in bytes, of the window creation data. The value is immediately followed by the creation data.
For more information, see the following Remarks section.
hInstance
Type: HINSTANCE
A handle to the module that owns the new window.
hMenu
Type: HMENU
A handle to the menu to be used by the new window.
hwndParent
Type: HWND
A handle to the parent window, if the window is a child window. If the window is owned, this member identifies
the owner window. If the window is not a child or owned window, this member is NULL .
cy
Type: int
The height of the new window, in pixels.
cx
Type: int
The width of the new window, in pixels.
y
Type: int
The y-coordinate of the upper left corner of the new window. If the new window is a child window, coordinates
are relative to the parent window. Otherwise, the coordinates are relative to the screen origin.
x
Type: int
The x-coordinate of the upper left corner of the new window. If the new window is a child window, coordinates
are relative to the parent window. Otherwise, the coordinates are relative to the screen origin.
style
Type: LONG
The style for the new window. For a list of possible values, see Window Styles.
lpszName
Type: LPCTSTR
The name of the new window.
lpszClass
Type: LPCTSTR
A pointer to a null-terminated string or an atom that specifies the class name of the new window.
dwExStyle
Type: DWORD
The extended window style for the new window. For a list of possible values, see Extended Window Styles.
Remarks
Because the lpszClass member can contain a pointer to a local (and thus inaccessable) atom, do not obtain the
class name by using this member. Use the GetClassName function instead.
You should access the data represented by the lpCreateParams member using a pointer that has been
declared using the UNALIGNED type, because the pointer may not be DWORD aligned. This is demonstrated
in the following example:
typedef struct tagMyData
{
// Define creation data here.
} MYDATA;
NOTE
The winuser.h header defines CREATESTRUCT 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
About the Multiple Document Interface
Conceptual
CreateWindow
CreateWindowEx
MDICREATESTRUCT
Reference
Windows
CREATESTRUCTW structure (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Defines the initialization parameters passed to the window procedure of an application. These members are
identical to the parameters of the CreateWindowEx function.
Syntax
typedef struct tagCREATESTRUCTW {
LPVOID lpCreateParams;
HINSTANCE hInstance;
HMENU hMenu;
HWND hwndParent;
int cy;
int cx;
int y;
int x;
LONG style;
LPCWSTR lpszName;
LPCWSTR lpszClass;
DWORD dwExStyle;
} CREATESTRUCTW, *LPCREATESTRUCTW;
Members
lpCreateParams
Type: LPVOID
Contains additional data which may be used to create the window. If the window is being created as a result of a
call to the CreateWindow or CreateWindowEx function, this member contains the value of the lpParam
parameter specified in the function call.
If the window being created is a MDI client window, this member contains a pointer to a CLIENTCREATESTRUCT
structure. If the window being created is a MDI child window, this member contains a pointer to an
MDICREATESTRUCT structure.
If the window is being created from a dialog template, this member is the address of a SHORT value that
specifies the size, in bytes, of the window creation data. The value is immediately followed by the creation data.
For more information, see the following Remarks section.
hInstance
Type: HINSTANCE
A handle to the module that owns the new window.
hMenu
Type: HMENU
A handle to the menu to be used by the new window.
hwndParent
Type: HWND
A handle to the parent window, if the window is a child window. If the window is owned, this member identifies
the owner window. If the window is not a child or owned window, this member is NULL .
cy
Type: int
The height of the new window, in pixels.
cx
Type: int
The width of the new window, in pixels.
y
Type: int
The y-coordinate of the upper left corner of the new window. If the new window is a child window, coordinates
are relative to the parent window. Otherwise, the coordinates are relative to the screen origin.
x
Type: int
The x-coordinate of the upper left corner of the new window. If the new window is a child window, coordinates
are relative to the parent window. Otherwise, the coordinates are relative to the screen origin.
style
Type: LONG
The style for the new window. For a list of possible values, see Window Styles.
lpszName
Type: LPCTSTR
The name of the new window.
lpszClass
Type: LPCTSTR
A pointer to a null-terminated string or an atom that specifies the class name of the new window.
dwExStyle
Type: DWORD
The extended window style for the new window. For a list of possible values, see Extended Window Styles.
Remarks
Because the lpszClass member can contain a pointer to a local (and thus inaccessable) atom, do not obtain the
class name by using this member. Use the GetClassName function instead.
You should access the data represented by the lpCreateParams member using a pointer that has been
declared using the UNALIGNED type, because the pointer may not be DWORD aligned. This is demonstrated
in the following example:
typedef struct tagMyData
{
// Define creation data here.
} MYDATA;
NOTE
The winuser.h header defines CREATESTRUCT 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
About the Multiple Document Interface
Conceptual
CreateWindow
CreateWindowEx
MDICREATESTRUCT
Reference
Windows
CreateWindowA macro (winuser.h)
2/1/2021 • 9 minutes to read • Edit Online
Creates an overlapped, pop-up, or child window. It specifies the window class, window title, window style, and
(optionally) the initial position and size of the window. The function also specifies the window's parent or owner,
if any, and the window's menu.
To use extended window styles in addition to the styles supported by CreateWindow , use the CreateWindowEx
function.
Syntax
void CreateWindowA(
lpClassName,
lpWindowName,
dwStyle,
x,
y,
nWidth,
nHeight,
hWndParent,
hMenu,
hInstance,
lpParam
);
Parameters
lpClassName
Type: LPCTSTR
A null -terminated string or a class atom created by a previous call to the RegisterClass or RegisterClassEx
function. The atom must be in the low-order word of lpClassName; the high-order word must be zero. If
lpClassName is a string, it specifies the window class name. The class name can be any name registered with
RegisterClass or RegisterClassEx , provided that the module that registers the class is also the module that
creates the window. The class name can also be any of the predefined system class names. For a list of system
class names, see the Remarks section.
lpWindowName
Type: LPCTSTR
The window name. If the window style specifies a title bar, the window title pointed to by lpWindowName is
displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static
controls, use lpWindowName to specify the text of the control. When creating a static control with the SS_ICON
style, use lpWindowName to specify the icon name or identifier. To specify an identifier, use the syntax "#num".
dwStyle
Type: DWORD
The style of the window being created. This parameter can be a combination of the window style values, plus the
control styles indicated in the Remarks section.
x
Type: int
The initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial
x-coordinate of the window's upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of
the upper-left corner of the window relative to the upper-left corner of the parent window's client area. If this
parameter is set to CW_USEDEFAULT , the system selects the default position for the window's upper-left
corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified
for a pop-up or child window, the x and y parameters are set to zero.
y
Type: int
The initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-
coordinate of the window's upper-left corner, in screen coordinates. For a child window, y is the initial y-
coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window's
client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box's client area relative
to the upper-left corner of the parent window's client area.
If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to
CW_USEDEFAULT , then the y parameter determines how the window is shown. If the y parameter is
CW_USEDEFAULT , then the window manager calls ShowWindow with the SW_SHOW flag after the window
has been created. If the y parameter is some other value, then the window manager calls ShowWindow with
that value as the nCmdShow parameter.
nWidth
Type: int
The width, in device units, of the window. For overlapped windows, nWidth is either the window's width, in
screen coordinates, or CW_USEDEFAULT . If nWidth is CW_USEDEFAULT , the system selects a default width
and height for the window; the default width extends from the initial x-coordinate to the right edge of the
screen, and the default height extends from the initial y-coordinate to the top of the icon area.
CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child
window, nWidth and nHeight are set to zero.
nHeight
Type: int
The height, in device units, of the window. For overlapped windows, nHeight is the window's height, in screen
coordinates. If nWidth is set to CW_USEDEFAULT , the system ignores nHeight.
hWndParent
Type: HWND
A handle to the parent or owner window of the window being created. To create a child window or an owned
window, supply a valid window handle. This parameter is optional for pop-up windows.
To create a message-only window, supply HWND_MESSAGE or a handle to an existing message-only window.
hMenu
Type: HMENU
A handle to a menu, or specifies a child-window identifier depending on the window style. For an overlapped or
pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to
be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box
control to notify its parent about events. The application determines the child-window identifier; it must be
unique for all child windows with the same parent window.
hInstance
Type: HINSTANCE
A handle to the instance of the module to be associated with the window.
lpParam
Type: LPVOID
A pointer to a value to be passed to the window through the CREATESTRUCT structure (lpCreateParams
member) pointed to by the lParam param of the WM_CREATE message. This message is sent to the created
window by this function before it returns.
If an application calls CreateWindow to create a MDI client window, lpParam should point to a
CLIENTCREATESTRUCT structure. If an MDI client window calls CreateWindow to create an MDI child window,
lpParam should point to a MDICREATESTRUCT structure. lpParam may be NULL if no additional data is needed.
Returns
Type: HWND
If the function succeeds, the return value is a handle to the new window.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Return value
None
Remarks
Before returning, CreateWindow sends a WM_CREATE message to the window procedure. For overlapped,
pop-up, and child windows, CreateWindow sends WM_CREATE , WM_GETMINMAXINFO, and WM_NCCREATE
messages to the window. The lParam parameter of the WM_CREATE message contains a pointer to a
CREATESTRUCT structure. If the WS_VISIBLE style is specified, CreateWindow sends the window all the
messages required to activate and show the window.
If the created window is a child window, its default position is at the bottom of the Z-order. If the created window
is a top-level window, its default position is at the top of the Z-order (but beneath all topmost windows unless
the created window is itself topmost).
For information on controlling whether the Taskbar displays a button for the created window, see Managing
Taskbar Buttons.
For information on removing a window, see the DestroyWindow function.
The following predefined system classes can be specified in the lpClassName parameter. Note the
corresponding control styles you can use in the dwStyle parameter.
SY ST EM C L A SS M EA N IN G
BUTTON Designates a small rectangular child window that represents
a button the user can click to turn it on or off. Button
controls can be used alone or in groups, and they can either
be labeled or appear without text. Button controls typically
change appearance when the user clicks them. For more
information, see Buttons
For a table of the button styles you can specify in the
dwStyle parameter, see Button Styles.
#ifdef UNICODE
#define CreateWindow CreateWindowW
#else
#define CreateWindow CreateWindowA
#endif
Examples
For an example, see Using Window Classes.
NOTE
The winuser.h header defines CreateWindow 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
About the Multiple Document Interface
Common Control Window Classes
Conceptual
CreateWindowEx
DestroyWindow
EnableWindow
Other Resources
Reference
RegisterClass
RegisterClassEx
ShowWindow
WM_COMMAND
WM_CREATE
WM_GETMINMAXINFO
WM_NCCREATE
WM_PAINT
Windows
CreateWindowExA function (winuser.h)
2/1/2021 • 10 minutes to read • Edit Online
Creates an overlapped, pop-up, or child window with an extended window style; otherwise, this function is
identical to the CreateWindow function. For more information about creating a window and for full descriptions
of the other parameters of CreateWindowEx , see CreateWindow .
Syntax
HWND CreateWindowExA(
DWORD dwExStyle,
LPCSTR lpClassName,
LPCSTR lpWindowName,
DWORD dwStyle,
int X,
int Y,
int nWidth,
int nHeight,
HWND hWndParent,
HMENU hMenu,
HINSTANCE hInstance,
LPVOID lpParam
);
Parameters
dwExStyle
Type: DWORD
The extended window style of the window being created. For a list of possible values, see Extended Window
Styles.
lpClassName
Type: LPCTSTR
A null -terminated string or a class atom created by a previous call to the RegisterClass or RegisterClassEx
function. The atom must be in the low-order word of lpClassName; the high-order word must be zero. If
lpClassName is a string, it specifies the window class name. The class name can be any name registered with
RegisterClass or RegisterClassEx , provided that the module that registers the class is also the module that
creates the window. The class name can also be any of the predefined system class names.
lpWindowName
Type: LPCTSTR
The window name. If the window style specifies a title bar, the window title pointed to by lpWindowName is
displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static
controls, use lpWindowName to specify the text of the control. When creating a static control with the SS_ICON
style, use lpWindowName to specify the icon name or identifier. To specify an identifier, use the syntax "#num".
dwStyle
Type: DWORD
The style of the window being created. This parameter can be a combination of the window style values, plus the
control styles indicated in the Remarks section.
X
Type: int
The initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial
x-coordinate of the window's upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of
the upper-left corner of the window relative to the upper-left corner of the parent window's client area. If x is set
to CW_USEDEFAULT , the system selects the default position for the window's upper-left corner and ignores the
y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child
window, the x and y parameters are set to zero.
Y
Type: int
The initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-
coordinate of the window's upper-left corner, in screen coordinates. For a child window, y is the initial y-
coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window's
client area. For a list box y is the initial y-coordinate of the upper-left corner of the list box's client area relative to
the upper-left corner of the parent window's client area.
If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to
CW_USEDEFAULT , then the y parameter determines how the window is shown. If the y parameter is
CW_USEDEFAULT , then the window manager calls ShowWindow with the SW_SHOW flag after the window
has been created. If the y parameter is some other value, then the window manager calls ShowWindow with
that value as the nCmdShow parameter.
nWidth
Type: int
The width, in device units, of the window. For overlapped windows, nWidth is the window's width, in screen
coordinates, or CW_USEDEFAULT . If nWidth is CW_USEDEFAULT , the system selects a default width and
height for the window; the default width extends from the initial x-coordinates to the right edge of the screen;
the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid
only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, the nWidth and
nHeight parameter are set to zero.
nHeight
Type: int
The height, in device units, of the window. For overlapped windows, nHeight is the window's height, in screen
coordinates. If the nWidth parameter is set to CW_USEDEFAULT , the system ignores nHeight.
hWndParent
Type: HWND
A handle to the parent or owner window of the window being created. To create a child window or an owned
window, supply a valid window handle. This parameter is optional for pop-up windows.
To create a message-only window, supply HWND_MESSAGE or a handle to an existing message-only window.
hMenu
Type: HMENU
A handle to a menu, or specifies a child-window identifier, depending on the window style. For an overlapped or
pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to
be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box
control to notify its parent about events. The application determines the child-window identifier; it must be
unique for all child windows with the same parent window.
hInstance
Type: HINSTANCE
A handle to the instance of the module to be associated with the window.
lpParam
Type: LPVOID
Pointer to a value to be passed to the window through the CREATESTRUCT structure (lpCreateParams
member) pointed to by the lParam param of the WM_CREATE message. This message is sent to the created
window by this function before it returns.
If an application calls CreateWindow to create a MDI client window, lpParam should point to a
CLIENTCREATESTRUCT structure. If an MDI client window calls CreateWindow to create an MDI child window,
lpParam should point to a MDICREATESTRUCT structure. lpParam may be NULL if no additional data is needed.
Return value
Type: HWND
If the function succeeds, the return value is a handle to the new window.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
This function typically fails for one of the following reasons:
an invalid parameter value
the system class was registered by a different module
The WH_CBT hook is installed and returns a failure code
if one of the controls in the dialog template is not registered, or its window window procedure fails
WM_CREATE or WM_NCCREATE
Remarks
The CreateWindowEx function sends WM_NCCREATE, WM_NCCALCSIZE, and WM_CREATE messages to the
window being created.
If the created window is a child window, its default position is at the bottom of the Z-order. If the created window
is a top-level window, its default position is at the top of the Z-order (but beneath all topmost windows unless
the created window is itself topmost).
For information on controlling whether the Taskbar displays a button for the created window, see Managing
Taskbar Buttons.
For information on removing a window, see the DestroyWindow function.
The following predefined control classes can be specified in the lpClassName parameter. Note the
corresponding control styles you can use in the dwStyle parameter.
C L A SS M EA N IN G
BUTTON Designates a small rectangular child window that represents
a button the user can click to turn it on or off. Button
controls can be used alone or in groups, and they can either
be labeled or appear without text. Button controls typically
change appearance when the user clicks them. For more
information, see Buttons.
For a table of the button styles you can specify in the
dwStyle parameter, see Button Styles.
The WS_EX_NOACTIVATE value for dwExStyle prevents foreground activation by the system. To prevent queue
activation when the user clicks on the window, you must process the WM_MOUSEACTIVATE message
appropriately. To bring the window to the foreground or to activate it programmatically, use
SetForegroundWindow or SetActiveWindow. Returning FALSE to WM_NCACTIVATE prevents the window from
losing queue activation. However, the return value is ignored at activation time.
With WS_EX_COMPOSITED set, all descendants of a window get bottom-to-top painting order using double-
buffering. Bottom-to-top painting order allows a descendent window to have translucency (alpha) and
transparency (color-key) effects, but only if the descendent window also has the WS_EX_TRANSPARENT bit
set. Double-buffering allows the window and its descendents to be painted without flicker.
Example
The following sample code illustrates the use of CreateWindowExA .
BOOL Create(
PCWSTR lpWindowName,
DWORD dwStyle,
DWORD dwExStyle = 0,
int x = CW_USEDEFAULT,
int y = CW_USEDEFAULT,
int nWidth = CW_USEDEFAULT,
int nHeight = CW_USEDEFAULT,
HWND hWndParent = 0,
HMENU hMenu = 0
)
{
WNDCLASS wc = {0};
wc.lpfnWndProc = DERIVED_TYPE::WindowProc;
wc.hInstance = GetModuleHandle(NULL);
wc.lpszClassName = ClassName();
RegisterClass(&wc);
m_hwnd = CreateWindowEx(
dwExStyle, ClassName(), lpWindowName, dwStyle, x, y,
nWidth, nHeight, hWndParent, hMenu, GetModuleHandle(NULL), this
);
NOTE
The winuser.h header defines CreateWindowEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
About the Multiple Document Interface
CLIENTCREATESTRUCT
CREATESTRUCT
Conceptual
CreateWindow
DestroyWindow
EnableWindow
Other Resources
Reference
RegisterClass
RegisterClassEx
SetActiveWindow
SetForegroundWindow
SetWindowLong
SetWindowPos
ShowWindow
WM_CREATE
WM_NCCALCSIZE
WM_NCCREATE
WM_PAINT
WM_PARENTNOTIFY
Windows
CreateWindowExW function (winuser.h)
2/1/2021 • 10 minutes to read • Edit Online
Creates an overlapped, pop-up, or child window with an extended window style; otherwise, this function is
identical to the CreateWindow function. For more information about creating a window and for full descriptions
of the other parameters of CreateWindowEx , see CreateWindow .
Syntax
HWND CreateWindowExW(
DWORD dwExStyle,
LPCWSTR lpClassName,
LPCWSTR lpWindowName,
DWORD dwStyle,
int X,
int Y,
int nWidth,
int nHeight,
HWND hWndParent,
HMENU hMenu,
HINSTANCE hInstance,
LPVOID lpParam
);
Parameters
dwExStyle
Type: DWORD
The extended window style of the window being created. For a list of possible values, see Extended Window
Styles.
lpClassName
Type: LPCTSTR
A null -terminated string or a class atom created by a previous call to the RegisterClass or RegisterClassEx
function. The atom must be in the low-order word of lpClassName; the high-order word must be zero. If
lpClassName is a string, it specifies the window class name. The class name can be any name registered with
RegisterClass or RegisterClassEx , provided that the module that registers the class is also the module that
creates the window. The class name can also be any of the predefined system class names.
lpWindowName
Type: LPCTSTR
The window name. If the window style specifies a title bar, the window title pointed to by lpWindowName is
displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static
controls, use lpWindowName to specify the text of the control. When creating a static control with the SS_ICON
style, use lpWindowName to specify the icon name or identifier. To specify an identifier, use the syntax "#num".
dwStyle
Type: DWORD
The style of the window being created. This parameter can be a combination of the window style values, plus the
control styles indicated in the Remarks section.
X
Type: int
The initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial
x-coordinate of the window's upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of
the upper-left corner of the window relative to the upper-left corner of the parent window's client area. If x is set
to CW_USEDEFAULT , the system selects the default position for the window's upper-left corner and ignores the
y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child
window, the x and y parameters are set to zero.
Y
Type: int
The initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-
coordinate of the window's upper-left corner, in screen coordinates. For a child window, y is the initial y-
coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window's
client area. For a list box y is the initial y-coordinate of the upper-left corner of the list box's client area relative to
the upper-left corner of the parent window's client area.
If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to
CW_USEDEFAULT , then the y parameter determines how the window is shown. If the y parameter is
CW_USEDEFAULT , then the window manager calls ShowWindow with the SW_SHOW flag after the window
has been created. If the y parameter is some other value, then the window manager calls ShowWindow with
that value as the nCmdShow parameter.
nWidth
Type: int
The width, in device units, of the window. For overlapped windows, nWidth is the window's width, in screen
coordinates, or CW_USEDEFAULT . If nWidth is CW_USEDEFAULT , the system selects a default width and
height for the window; the default width extends from the initial x-coordinates to the right edge of the screen;
the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid
only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, the nWidth and
nHeight parameter are set to zero.
nHeight
Type: int
The height, in device units, of the window. For overlapped windows, nHeight is the window's height, in screen
coordinates. If the nWidth parameter is set to CW_USEDEFAULT , the system ignores nHeight.
hWndParent
Type: HWND
A handle to the parent or owner window of the window being created. To create a child window or an owned
window, supply a valid window handle. This parameter is optional for pop-up windows.
To create a message-only window, supply HWND_MESSAGE or a handle to an existing message-only window.
hMenu
Type: HMENU
A handle to a menu, or specifies a child-window identifier, depending on the window style. For an overlapped or
pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to
be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box
control to notify its parent about events. The application determines the child-window identifier; it must be
unique for all child windows with the same parent window.
hInstance
Type: HINSTANCE
A handle to the instance of the module to be associated with the window.
lpParam
Type: LPVOID
Pointer to a value to be passed to the window through the CREATESTRUCT structure (lpCreateParams
member) pointed to by the lParam param of the WM_CREATE message. This message is sent to the created
window by this function before it returns.
If an application calls CreateWindow to create a MDI client window, lpParam should point to a
CLIENTCREATESTRUCT structure. If an MDI client window calls CreateWindow to create an MDI child window,
lpParam should point to a MDICREATESTRUCT structure. lpParam may be NULL if no additional data is needed.
Return value
Type: HWND
If the function succeeds, the return value is a handle to the new window.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
This function typically fails for one of the following reasons:
an invalid parameter value
the system class was registered by a different module
The WH_CBT hook is installed and returns a failure code
if one of the controls in the dialog template is not registered, or its window window procedure fails
WM_CREATE or WM_NCCREATE
Remarks
The CreateWindowEx function sends WM_NCCREATE, WM_NCCALCSIZE, and WM_CREATE messages to the
window being created.
If the created window is a child window, its default position is at the bottom of the Z-order. If the created window
is a top-level window, its default position is at the top of the Z-order (but beneath all topmost windows unless
the created window is itself topmost).
For information on controlling whether the Taskbar displays a button for the created window, see Managing
Taskbar Buttons.
For information on removing a window, see the DestroyWindow function.
The following predefined control classes can be specified in the lpClassName parameter. Note the
corresponding control styles you can use in the dwStyle parameter.
C L A SS M EA N IN G
BUTTON Designates a small rectangular child window that represents
a button the user can click to turn it on or off. Button
controls can be used alone or in groups, and they can either
be labeled or appear without text. Button controls typically
change appearance when the user clicks them. For more
information, see Buttons.
For a table of the button styles you can specify in the
dwStyle parameter, see Button Styles.
The WS_EX_NOACTIVATE value for dwExStyle prevents foreground activation by the system. To prevent queue
activation when the user clicks on the window, you must process the WM_MOUSEACTIVATE message
appropriately. To bring the window to the foreground or to activate it programmatically, use
SetForegroundWindow or SetActiveWindow. Returning FALSE to WM_NCACTIVATE prevents the window from
losing queue activation. However, the return value is ignored at activation time.
With WS_EX_COMPOSITED set, all descendants of a window get bottom-to-top painting order using double-
buffering. Bottom-to-top painting order allows a descendent window to have translucency (alpha) and
transparency (color-key) effects, but only if the descendent window also has the WS_EX_TRANSPARENT bit
set. Double-buffering allows the window and its descendents to be painted without flicker.
Example
The following sample code illustrates the use of CreateWindowExA .
BOOL Create(
PCWSTR lpWindowName,
DWORD dwStyle,
DWORD dwExStyle = 0,
int x = CW_USEDEFAULT,
int y = CW_USEDEFAULT,
int nWidth = CW_USEDEFAULT,
int nHeight = CW_USEDEFAULT,
HWND hWndParent = 0,
HMENU hMenu = 0
)
{
WNDCLASS wc = {0};
wc.lpfnWndProc = DERIVED_TYPE::WindowProc;
wc.hInstance = GetModuleHandle(NULL);
wc.lpszClassName = ClassName();
RegisterClass(&wc);
m_hwnd = CreateWindowEx(
dwExStyle, ClassName(), lpWindowName, dwStyle, x, y,
nWidth, nHeight, hWndParent, hMenu, GetModuleHandle(NULL), this
);
NOTE
The winuser.h header defines CreateWindowEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
About the Multiple Document Interface
CLIENTCREATESTRUCT
CREATESTRUCT
Conceptual
CreateWindow
DestroyWindow
EnableWindow
Other Resources
Reference
RegisterClass
RegisterClassEx
SetActiveWindow
SetForegroundWindow
SetWindowLong
SetWindowPos
ShowWindow
WM_CREATE
WM_NCCALCSIZE
WM_NCCREATE
WM_PAINT
WM_PARENTNOTIFY
Windows
CreateWindowW macro (winuser.h)
2/1/2021 • 9 minutes to read • Edit Online
Creates an overlapped, pop-up, or child window. It specifies the window class, window title, window style, and
(optionally) the initial position and size of the window. The function also specifies the window's parent or owner,
if any, and the window's menu.
To use extended window styles in addition to the styles supported by CreateWindow , use the CreateWindowEx
function.
Syntax
void CreateWindowW(
lpClassName,
lpWindowName,
dwStyle,
x,
y,
nWidth,
nHeight,
hWndParent,
hMenu,
hInstance,
lpParam
);
Parameters
lpClassName
Type: LPCTSTR
A null -terminated string or a class atom created by a previous call to the RegisterClass or RegisterClassEx
function. The atom must be in the low-order word of lpClassName; the high-order word must be zero. If
lpClassName is a string, it specifies the window class name. The class name can be any name registered with
RegisterClass or RegisterClassEx , provided that the module that registers the class is also the module that
creates the window. The class name can also be any of the predefined system class names. For a list of system
class names, see the Remarks section.
lpWindowName
Type: LPCTSTR
The window name. If the window style specifies a title bar, the window title pointed to by lpWindowName is
displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static
controls, use lpWindowName to specify the text of the control. When creating a static control with the SS_ICON
style, use lpWindowName to specify the icon name or identifier. To specify an identifier, use the syntax "#num".
dwStyle
Type: DWORD
The style of the window being created. This parameter can be a combination of the window style values, plus the
control styles indicated in the Remarks section.
x
Type: int
The initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial
x-coordinate of the window's upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of
the upper-left corner of the window relative to the upper-left corner of the parent window's client area. If this
parameter is set to CW_USEDEFAULT , the system selects the default position for the window's upper-left
corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified
for a pop-up or child window, the x and y parameters are set to zero.
y
Type: int
The initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-
coordinate of the window's upper-left corner, in screen coordinates. For a child window, y is the initial y-
coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window's
client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box's client area relative
to the upper-left corner of the parent window's client area.
If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to
CW_USEDEFAULT , then the y parameter determines how the window is shown. If the y parameter is
CW_USEDEFAULT , then the window manager calls ShowWindow with the SW_SHOW flag after the window
has been created. If the y parameter is some other value, then the window manager calls ShowWindow with
that value as the nCmdShow parameter.
nWidth
Type: int
The width, in device units, of the window. For overlapped windows, nWidth is either the window's width, in
screen coordinates, or CW_USEDEFAULT . If nWidth is CW_USEDEFAULT , the system selects a default width
and height for the window; the default width extends from the initial x-coordinate to the right edge of the
screen, and the default height extends from the initial y-coordinate to the top of the icon area.
CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child
window, nWidth and nHeight are set to zero.
nHeight
Type: int
The height, in device units, of the window. For overlapped windows, nHeight is the window's height, in screen
coordinates. If nWidth is set to CW_USEDEFAULT , the system ignores nHeight.
hWndParent
Type: HWND
A handle to the parent or owner window of the window being created. To create a child window or an owned
window, supply a valid window handle. This parameter is optional for pop-up windows.
To create a message-only window, supply HWND_MESSAGE or a handle to an existing message-only window.
hMenu
Type: HMENU
A handle to a menu, or specifies a child-window identifier depending on the window style. For an overlapped or
pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to
be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box
control to notify its parent about events. The application determines the child-window identifier; it must be
unique for all child windows with the same parent window.
hInstance
Type: HINSTANCE
A handle to the instance of the module to be associated with the window.
lpParam
Type: LPVOID
A pointer to a value to be passed to the window through the CREATESTRUCT structure (lpCreateParams
member) pointed to by the lParam param of the WM_CREATE message. This message is sent to the created
window by this function before it returns.
If an application calls CreateWindow to create a MDI client window, lpParam should point to a
CLIENTCREATESTRUCT structure. If an MDI client window calls CreateWindow to create an MDI child window,
lpParam should point to a MDICREATESTRUCT structure. lpParam may be NULL if no additional data is needed.
Returns
Type: HWND
If the function succeeds, the return value is a handle to the new window.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Return value
None
Remarks
Before returning, CreateWindow sends a WM_CREATE message to the window procedure. For overlapped,
pop-up, and child windows, CreateWindow sends WM_CREATE , WM_GETMINMAXINFO, and WM_NCCREATE
messages to the window. The lParam parameter of the WM_CREATE message contains a pointer to a
CREATESTRUCT structure. If the WS_VISIBLE style is specified, CreateWindow sends the window all the
messages required to activate and show the window.
If the created window is a child window, its default position is at the bottom of the Z-order. If the created window
is a top-level window, its default position is at the top of the Z-order (but beneath all topmost windows unless
the created window is itself topmost).
For information on controlling whether the Taskbar displays a button for the created window, see Managing
Taskbar Buttons.
For information on removing a window, see the DestroyWindow function.
The following predefined system classes can be specified in the lpClassName parameter. Note the
corresponding control styles you can use in the dwStyle parameter.
SY ST EM C L A SS M EA N IN G
BUTTON Designates a small rectangular child window that represents
a button the user can click to turn it on or off. Button
controls can be used alone or in groups, and they can either
be labeled or appear without text. Button controls typically
change appearance when the user clicks them. For more
information, see Buttons
For a table of the button styles you can specify in the
dwStyle parameter, see Button Styles.
#ifdef UNICODE
#define CreateWindow CreateWindowW
#else
#define CreateWindow CreateWindowA
#endif
Examples
For an example, see Using Window Classes.
NOTE
The winuser.h header defines CreateWindow 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
About the Multiple Document Interface
Common Control Window Classes
Conceptual
CreateWindowEx
DestroyWindow
EnableWindow
Other Resources
Reference
RegisterClass
RegisterClassEx
ShowWindow
WM_COMMAND
WM_CREATE
WM_GETMINMAXINFO
WM_NCCREATE
WM_PAINT
Windows
CWPRETSTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagCWPRETSTRUCT {
LRESULT lResult;
LPARAM lParam;
WPARAM wParam;
UINT message;
HWND hwnd;
} CWPRETSTRUCT, *PCWPRETSTRUCT, *NPCWPRETSTRUCT, *LPCWPRETSTRUCT;
Members
lResult
Type: LRESULT
The return value of the window procedure that processed the message specified by the message value.
lParam
Type: LPARAM
Additional information about the message. The exact meaning depends on the message value.
wParam
Type: WPARAM
Additional information about the message. The exact meaning depends on the message value.
message
Type: UINT
The message.
hwnd
Type: HWND
A handle to the window that processed the message specified by the message value.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Header winuser.h (include Windows.h)
See also
CallWndRetProc
Conceptual
Hooks
Reference
SetWindowsHookEx
CWPSTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagCWPSTRUCT {
LPARAM lParam;
WPARAM wParam;
UINT message;
HWND hwnd;
} CWPSTRUCT, *PCWPSTRUCT, *NPCWPSTRUCT, *LPCWPSTRUCT;
Members
lParam
Type: LPARAM
Additional information about the message. The exact meaning depends on the message value.
wParam
Type: WPARAM
Additional information about the message. The exact meaning depends on the message value.
message
Type: UINT
The message.
hwnd
Type: HWND
A handle to the window to receive the message.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
CallWndProc
Conceptual
Hooks
Reference
SetWindowsHookEx
DEBUGHOOKINFO structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagDEBUGHOOKINFO {
DWORD idThread;
DWORD idThreadInstaller;
LPARAM lParam;
WPARAM wParam;
int code;
} DEBUGHOOKINFO, *PDEBUGHOOKINFO, *NPDEBUGHOOKINFO, *LPDEBUGHOOKINFO;
Members
idThread
Type: DWORD
A handle to the thread containing the filter function.
idThreadInstaller
Type: DWORD
A handle to the thread that installed the debugging filter function.
lParam
Type: LPARAM
The value to be passed to the hook in the lParam parameter of the DebugProc callback function.
wParam
Type: WPARAM
The value to be passed to the hook in the wParam parameter of the DebugProc callback function.
code
Type: int
The value to be passed to the hook in the nCode parameter of the DebugProc callback function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Header winuser.h (include Windows.h)
See also
Conceptual
DebugProc
Hooks
Reference
SetWindowsHookEx
DeferWindowPos function (winuser.h)
2/1/2021 • 5 minutes to read • Edit Online
Updates the specified multiple-window – position structure for the specified window. The function then returns a
handle to the updated structure. The EndDeferWindowPos function uses the information in this structure to
change the position and size of a number of windows simultaneously. The BeginDeferWindowPos function
creates the structure.
Syntax
HDWP DeferWindowPos(
HDWP hWinPosInfo,
HWND hWnd,
HWND hWndInsertAfter,
int x,
int y,
int cx,
int cy,
UINT uFlags
);
Parameters
hWinPosInfo
Type: HDWP
A handle to a multiple-window – position structure that contains size and position information for one or more
windows. This structure is returned by BeginDeferWindowPos or by the most recent call to DeferWindowPos .
hWnd
Type: HWND
A handle to the window for which update information is stored in the structure. All windows in a multiple-
window – position structure must have the same parent.
hWndInsertAfter
Type: HWND
A handle to the window that precedes the positioned window in the Z order. This parameter must be a window
handle or one of the following values. This parameter is ignored if the SWP_NOZORDER flag is set in the
uFlags parameter.
VA L UE M EA N IN G
Type: int
The x-coordinate of the window's upper-left corner.
y
Type: int
The y-coordinate of the window's upper-left corner.
cx
Type: int
The window's new width, in pixels.
cy
Type: int
The window's new height, in pixels.
uFlags
Type: UINT
A combination of the following values that affect the size and position of the window.
VA L UE M EA N IN G
Return value
Type: HDWP
The return value identifies the updated multiple-window – position structure. The handle returned by this
function may differ from the handle passed to the function. The new handle that this function returns should be
passed during the next call to the DeferWindowPos or EndDeferWindowPos function.
If insufficient system resources are available for the function to succeed, the return value is NULL . To get
extended error information, call GetLastError.
Remarks
If a call to DeferWindowPos fails, the application should abandon the window-positioning operation and not
call EndDeferWindowPos.
If SWP_NOZORDER is not specified, the system places the window identified by the hWnd parameter in the
position following the window identified by the hWndInsertAfter parameter. If hWndInsertAfter is NULL or
HWND_TOP , the system places the hWnd window at the top of the Z order. If hWndInsertAfter is set to
HWND_BOTTOM , the system places the hWnd window at the bottom of the Z order.
All coordinates for child windows are relative to the upper-left corner of the parent window's client area.
A window can be made a topmost window either by setting hWndInsertAfter to the HWND_TOPMOST flag
and ensuring that the SWP_NOZORDER flag is not set, or by setting the window's position in the Z order so
that it is above any existing topmost windows. When a non-topmost window is made topmost, its owned
windows are also made topmost. Its owners, however, are not changed.
If neither the SWP_NOACTIVATE nor SWP_NOZORDER flag is specified (that is, when the application
requests that a window be simultaneously activated and its position in the Z order changed), the value specified
in hWndInsertAfter is used only in the following circumstances:
Neither the HWND_TOPMOST nor HWND_NOTOPMOST flag is specified in hWndInsertAfter.
The window identified by hWnd is not the active window.
An application cannot activate an inactive window without also bringing it to the top of the Z order. An application
can change an activated window's position in the Z order without restrictions, or it can activate a window and then
move it to the top of the topmost or non-topmost windows.
A topmost window is no longer topmost if it is repositioned to the bottom (HWND_BOTTOM ) of the Z order or
after any non-topmost window. When a topmost window is made non-topmost, its owners and its owned
windows are also made non-topmost windows.
A non-topmost window may own a topmost window, but not vice versa. Any window (for example, a dialog box)
owned by a topmost window is itself made a topmost window to ensure that all owned windows stay above
their owner.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Provides default processing for any window messages that the window procedure of a multiple-document
interface (MDI) frame window does not process. All window messages that are not explicitly processed by the
window procedure must be passed to the DefFrameProc function, not the DefWindowProc function.
Syntax
LRESULT DefFrameProcA(
HWND hWnd,
HWND hWndMDIClient,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the MDI frame window.
hWndMDIClient
Type: HWND
A handle to the MDI client window.
uMsg
Type: UINT
The message to be processed.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: LRESULT
The return value specifies the result of the message processing and depends on the message. If the
hWndMDIClient parameter is NULL , the return value is the same as for the DefWindowProc function.
Remarks
When an application's window procedure does not handle a message, it typically passes the message to the
DefWindowProc function to process the message. MDI applications use the DefFrameProc and
DefMDIChildProc functions instead of DefWindowProc to provide default message processing. All messages
that an application would usually pass to DefWindowProc (such as nonclient messages and the WM_SETTEXT
message) should be passed to DefFrameProc instead. The DefFrameProc function also handles the following
messages.
M ESSA GE RESP O N SE
WM_COMMAND Activates the MDI child window that the user chooses. This
message is sent when the user chooses an MDI child
window from the window menu of the MDI frame window.
The window identifier accompanying this message identifies
the MDI child window to be activated.
WM_MENUCHAR Opens the window menu of the active MDI child window
when the user presses the ALT+ – (minus) key combination.
WM_SETFOCUS Passes the keyboard focus to the MDI client window, which
in turn passes it to the active MDI child window.
WM_SIZE Resizes the MDI client window to fit in the new frame
window's client area. If the frame window procedure sizes the
MDI client window to a different size, it should not pass the
message to the DefWindowProc function.
NOTE
The winuser.h header defines DefFrameProc 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
DefMDIChildProc
DefWindowProc
Multiple Document Interface
Reference
WM_SETTEXT
DefFrameProcW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Provides default processing for any window messages that the window procedure of a multiple-document
interface (MDI) frame window does not process. All window messages that are not explicitly processed by the
window procedure must be passed to the DefFrameProc function, not the DefWindowProc function.
Syntax
LRESULT DefFrameProcW(
HWND hWnd,
HWND hWndMDIClient,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the MDI frame window.
hWndMDIClient
Type: HWND
A handle to the MDI client window.
uMsg
Type: UINT
The message to be processed.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: LRESULT
The return value specifies the result of the message processing and depends on the message. If the
hWndMDIClient parameter is NULL , the return value is the same as for the DefWindowProc function.
Remarks
When an application's window procedure does not handle a message, it typically passes the message to the
DefWindowProc function to process the message. MDI applications use the DefFrameProc and
DefMDIChildProc functions instead of DefWindowProc to provide default message processing. All messages
that an application would usually pass to DefWindowProc (such as nonclient messages and the WM_SETTEXT
message) should be passed to DefFrameProc instead. The DefFrameProc function also handles the following
messages.
M ESSA GE RESP O N SE
WM_COMMAND Activates the MDI child window that the user chooses. This
message is sent when the user chooses an MDI child
window from the window menu of the MDI frame window.
The window identifier accompanying this message identifies
the MDI child window to be activated.
WM_MENUCHAR Opens the window menu of the active MDI child window
when the user presses the ALT+ – (minus) key combination.
WM_SETFOCUS Passes the keyboard focus to the MDI client window, which
in turn passes it to the active MDI child window.
WM_SIZE Resizes the MDI client window to fit in the new frame
window's client area. If the frame window procedure sizes the
MDI client window to a different size, it should not pass the
message to the DefWindowProc function.
NOTE
The winuser.h header defines DefFrameProc 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
DefMDIChildProc
DefWindowProc
Multiple Document Interface
Reference
WM_SETTEXT
DefMDIChildProcA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Provides default processing for any window message that the window procedure of a multiple-document
interface (MDI) child window does not process. A window message not processed by the window procedure
must be passed to the DefMDIChildProc function, not to the DefWindowProc function.
Syntax
LRESULT LRESULT DefMDIChildProcA(
HWND hWnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the MDI child window.
uMsg
Type: UINT
The message to be processed.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: LRESULT
The return value specifies the result of the message processing and depends on the message.
Remarks
The DefMDIChildProc function assumes that the parent window of the MDI child window identified by the
hWnd parameter was created with the MDICLIENT class.
When an application's window procedure does not handle a message, it typically passes the message to the
DefWindowProc function to process the message. MDI applications use the DefFrameProc and
DefMDIChildProc functions instead of DefWindowProc to provide default message processing. All messages
that an application would usually pass to DefWindowProc (such as nonclient messages and the WM_SETTEXT
message) should be passed to DefMDIChildProc instead. In addition, DefMDIChildProc also handles the
following messages.
M ESSA GE RESP O N SE
WM_SETFOCUS Activates the child window if it is not the active MDI child
window.
NOTE
The winuser.h header defines DefMDIChildProc 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
DefFrameProc
DefWindowProc
Multiple Document Interface
Reference
WM_CHILDACTIVATE
WM_GETMINMAXINFO
WM_MENUCHAR
WM_MOVE
WM_SETFOCUS
WM_SETTEXT
WM_SIZE
WM_SYSCOMMAND
DefMDIChildProcW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Provides default processing for any window message that the window procedure of a multiple-document
interface (MDI) child window does not process. A window message not processed by the window procedure
must be passed to the DefMDIChildProc function, not to the DefWindowProc function.
Syntax
LRESULT LRESULT DefMDIChildProcW(
HWND hWnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the MDI child window.
uMsg
Type: UINT
The message to be processed.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: LRESULT
The return value specifies the result of the message processing and depends on the message.
Remarks
The DefMDIChildProc function assumes that the parent window of the MDI child window identified by the
hWnd parameter was created with the MDICLIENT class.
When an application's window procedure does not handle a message, it typically passes the message to the
DefWindowProc function to process the message. MDI applications use the DefFrameProc and
DefMDIChildProc functions instead of DefWindowProc to provide default message processing. All messages
that an application would usually pass to DefWindowProc (such as nonclient messages and the WM_SETTEXT
message) should be passed to DefMDIChildProc instead. In addition, DefMDIChildProc also handles the
following messages.
M ESSA GE RESP O N SE
WM_SETFOCUS Activates the child window if it is not the active MDI child
window.
NOTE
The winuser.h header defines DefMDIChildProc 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
DefFrameProc
DefWindowProc
Multiple Document Interface
Reference
WM_CHILDACTIVATE
WM_GETMINMAXINFO
WM_MENUCHAR
WM_MOVE
WM_SETFOCUS
WM_SETTEXT
WM_SIZE
WM_SYSCOMMAND
DefWindowProcA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Calls the default window procedure to provide default processing for any window messages that an application
does not process. This function ensures that every message is processed. DefWindowProc is called with the
same parameters received by the window procedure.
Syntax
LRESULT LRESULT DefWindowProcA(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window procedure that received the message.
Msg
Type: UINT
The message.
wParam
Type: WPARAM
Additional message information. The content of this parameter depends on the value of the Msg parameter.
lParam
Type: LPARAM
Additional message information. The content of this parameter depends on the value of the Msg parameter.
Return value
Type: LRESULT
The return value is the result of the message processing and depends on the message.
Remarks
NOTE
The winuser.h header defines DefWindowProc 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CallWindowProc
Conceptual
DefDlgProc
Reference
Window Procedures
WindowProc
DefWindowProcW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Calls the default window procedure to provide default processing for any window messages that an application
does not process. This function ensures that every message is processed. DefWindowProc is called with the
same parameters received by the window procedure.
Syntax
LRESULT LRESULT DefWindowProcW(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window procedure that received the message.
Msg
Type: UINT
The message.
wParam
Type: WPARAM
Additional message information. The content of this parameter depends on the value of the Msg parameter.
lParam
Type: LPARAM
Additional message information. The content of this parameter depends on the value of the Msg parameter.
Return value
Type: LRESULT
The return value is the result of the message processing and depends on the message.
Remarks
NOTE
The winuser.h header defines DefWindowProc 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CallWindowProc
Conceptual
DefDlgProc
Reference
Window Procedures
WindowProc
DeregisterShellHookWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
[This function is not intended for general use. It may be altered or unavailable in subsequent versions of
Windows.]
Unregisters a specified Shell window that is registered to receive Shell hook messages.
Syntax
BOOL DeregisterShellHookWindow(
HWND hwnd
);
Parameters
hwnd
Type: HWND
A handle to the window to be unregistered. The window was registered with a call to the
RegisterShellHookWindow function.
Return value
Type: BOOL
TRUE if the function succeeds; FALSE if the function fails.
Remarks
This function was not included in the SDK headers and libraries until Windows XP with Service Pack 1 (SP1) and
Windows Server 2003. If you do not have a header file and import library for this function, you can call the
function using LoadLibrary and GetProcAddress.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
RegisterShellHookWindow
Windows
DestroyWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Destroys the specified window. The function sends WM_DESTROY and WM_NCDESTROY messages to the
window to deactivate it and remove the keyboard focus from it. The function also destroys the window's menu,
flushes the thread message queue, destroys timers, removes clipboard ownership, and breaks the clipboard
viewer chain (if the window is at the top of the viewer chain).
If the specified window is a parent or owner window, DestroyWindow automatically destroys the associated
child or owned windows when it destroys the parent or owner window. The function first destroys child or
owned windows, and then it destroys the parent or owner window.
DestroyWindow also destroys modeless dialog boxes created by the CreateDialog function.
Syntax
BOOL DestroyWindow(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to be destroyed.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
A thread cannot use DestroyWindow to destroy a window created by a different thread.
If the window being destroyed is a child window that does not have the WS_EX_NOPARENTNOTIFY style, a
WM_PARENTNOTIFY message is sent to the parent.
Examples
For an example, see Destroying a Window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
CreateDialog
CreateWindow
CreateWindowEx
Reference
WM_DESTROY
WM_NCDESTROY
WM_PARENTNOTIFY
Windows
DispatchMessage function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the
GetMessage function.
Syntax
LRESULT DispatchMessage(
const MSG *lpMsg
);
Parameters
lpMsg
Return value
Type: LRESULT
The return value specifies the value returned by the window procedure. Although its meaning depends on the
message being dispatched, the return value generally is ignored.
Remarks
The MSG structure must contain valid message values. If the lpmsg parameter points to a WM_TIMER message
and the lParam parameter of the WM_TIMER message is not NULL , lParam points to a function that is called
instead of the window procedure.
Note that the application is responsible for retrieving and dispatching input messages to the dialog box. Most
applications use the main message loop for this. However, to permit the user to move to and to select controls
by using the keyboard, the application must call IsDialogMessage. For more information, see Dialog Box
Keyboard Interface.
Examples
For an example, see Creating a Message Loop.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
IsDialogMessage
MSG
Messages and Message Queues
PeekMessage
Reference
TranslateMessage
WM_TIMER
DispatchMessageA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the
GetMessage function.
Syntax
LRESULT DispatchMessageA(
const MSG *lpMsg
);
Parameters
lpMsg
Return value
Type: LRESULT
The return value specifies the value returned by the window procedure. Although its meaning depends on the
message being dispatched, the return value generally is ignored.
Remarks
The MSG structure must contain valid message values. If the lpmsg parameter points to a WM_TIMER message
and the lParam parameter of the WM_TIMER message is not NULL , lParam points to a function that is called
instead of the window procedure.
Note that the application is responsible for retrieving and dispatching input messages to the dialog box. Most
applications use the main message loop for this. However, to permit the user to move to and to select controls
by using the keyboard, the application must call IsDialogMessage. For more information, see Dialog Box
Keyboard Interface.
Examples
For an example, see Creating a Message Loop.
NOTE
The winuser.h header defines DispatchMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
IsDialogMessage
MSG
Messages and Message Queues
PeekMessage
Reference
TranslateMessage
WM_TIMER
DispatchMessageW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the
GetMessage function.
Syntax
LRESULT DispatchMessageW(
const MSG *lpMsg
);
Parameters
lpMsg
Return value
Type: LRESULT
The return value specifies the value returned by the window procedure. Although its meaning depends on the
message being dispatched, the return value generally is ignored.
Remarks
The MSG structure must contain valid message values. If the lpmsg parameter points to a WM_TIMER message
and the lParam parameter of the WM_TIMER message is not NULL , lParam points to a function that is called
instead of the window procedure.
Note that the application is responsible for retrieving and dispatching input messages to the dialog box. Most
applications use the main message loop for this. However, to permit the user to move to and to select controls
by using the keyboard, the application must call IsDialogMessage. For more information, see Dialog Box
Keyboard Interface.
Examples
For an example, see Creating a Message Loop.
NOTE
The winuser.h header defines DispatchMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
IsDialogMessage
MSG
Messages and Message Queues
PeekMessage
Reference
TranslateMessage
WM_TIMER
EndDeferWindowPos function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Simultaneously updates the position and size of one or more windows in a single screen-refreshing cycle.
Syntax
BOOL EndDeferWindowPos(
HDWP hWinPosInfo
);
Parameters
hWinPosInfo
Type: HDWP
A handle to a multiple-window – position structure that contains size and position information for one or more
windows. This internal structure is returned by the BeginDeferWindowPos function or by the most recent call to
the DeferWindowPos function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The EndDeferWindowPos function sends the WM_WINDOWPOSCHANGING and
WM_WINDOWPOSCHANGED messages to each window identified in the internal structure.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-window-l1-1-4 (introduced in Windows
10, version 10.0.14393)
See also
BeginDeferWindowPos
Conceptual
DeferWindowPos
Reference
WM_WINDOWPOSCHANGED
WM_WINDOWPOSCHANGING
Windows
EndTask function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
[This function is not intended for general use. It may be altered or unavailable in subsequent versions of
Windows.]
Forcibly closes the specified window.
Syntax
BOOL EndTask(
HWND hWnd,
BOOL fShutDown,
BOOL fForce
);
Parameters
hWnd
Type: HWND
A handle to the window to be closed.
fShutDown
Type: BOOL
Ignored. Must be FALSE .
fForce
Type: BOOL
A TRUE for this parameter will force the destruction of the window if an initial attempt fails to gently close the
window using WM_CLOSE. With a FALSE for this parameter, only the close with WM_CLOSE is attempted.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is FALSE . To get extended error information, call GetLastError.
Remarks
This function was not included in the SDK headers and libraries until Windows XP with Service Pack 1 (SP1) and
Windows Server 2003. If you do not have a header file and import library for this function, you can call the
function using LoadLibrary and GetProcAddress.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CloseWindow
Conceptual
DestroyWindow
Reference
WM_CLOSE
Windows
EnumChildWindows function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enumerates the child windows that belong to the specified parent window by passing the handle to each child
window, in turn, to an application-defined callback function. EnumChildWindows continues until the last child
window is enumerated or the callback function returns FALSE .
Syntax
BOOL EnumChildWindows(
HWND hWndParent,
WNDENUMPROC lpEnumFunc,
LPARAM lParam
);
Parameters
hWndParent
Type: HWND
A handle to the parent window whose child windows are to be enumerated. If this parameter is NULL , this
function is equivalent to EnumWindows.
lpEnumFunc
Type: WNDENUMPROC
A pointer to an application-defined callback function. For more information, see EnumChildProc.
lParam
Type: LPARAM
An application-defined value to be passed to the callback function.
Return value
Type: BOOL
The return value is not used.
Remarks
If a child window has created child windows of its own, EnumChildWindows enumerates those windows as
well.
A child window that is moved or repositioned in the Z order during the enumeration process will be properly
enumerated. The function does not enumerate a child window that is destroyed before being enumerated or
that is created during the enumeration process.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumChildProc
EnumThreadWindows
EnumWindows
GetWindow
Reference
Windows
EnumPropsA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enumerates all entries in the property list of a window by passing them, one by one, to the specified callback
function. EnumProps continues until the last entry is enumerated or the callback function returns FALSE .
To pass application-defined data to the callback function, use EnumPropsEx function.
Syntax
int EnumPropsA(
HWND hWnd,
PROPENUMPROCA lpEnumFunc
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list is to be enumerated.
lpEnumFunc
Type: PROPENUMPROC
A pointer to the callback function. For more information about the callback function, see the PropEnumProc
function.
Return value
Type: int
The return value specifies the last value returned by the callback function. It is -1 if the function did not find a
property for enumeration.
Remarks
An application can remove only those properties it has added. It must not remove properties added by other
applications or by the system itself.
NOTE
The winuser.h header defines EnumProps 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumPropsEx
PropEnumProc
Reference
Window Properties
EnumPropsExA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enumerates all entries in the property list of a window by passing them, one by one, to the specified callback
function. EnumPropsEx continues until the last entry is enumerated or the callback function returns FALSE .
Syntax
int EnumPropsExA(
HWND hWnd,
PROPENUMPROCEXA lpEnumFunc,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list is to be enumerated.
lpEnumFunc
Type: PROPENUMPROCEX
A pointer to the callback function. For more information about the callback function, see the PropEnumProcEx
function.
lParam
Type: LPARAM
Application-defined data to be passed to the callback function.
Return value
Type: int
The return value specifies the last value returned by the callback function. It is -1 if the function did not find a
property for enumeration.
Remarks
An application can remove only those properties it has added. It must not remove properties added by other
applications or by the system itself.
Examples
For an example, see Listing Window Properties for a Given Window.
NOTE
The winuser.h header defines EnumPropsEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
PropEnumProcEx
Reference
Window Properties
EnumPropsExW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enumerates all entries in the property list of a window by passing them, one by one, to the specified callback
function. EnumPropsEx continues until the last entry is enumerated or the callback function returns FALSE .
Syntax
int EnumPropsExW(
HWND hWnd,
PROPENUMPROCEXW lpEnumFunc,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list is to be enumerated.
lpEnumFunc
Type: PROPENUMPROCEX
A pointer to the callback function. For more information about the callback function, see the PropEnumProcEx
function.
lParam
Type: LPARAM
Application-defined data to be passed to the callback function.
Return value
Type: int
The return value specifies the last value returned by the callback function. It is -1 if the function did not find a
property for enumeration.
Remarks
An application can remove only those properties it has added. It must not remove properties added by other
applications or by the system itself.
Examples
For an example, see Listing Window Properties for a Given Window.
NOTE
The winuser.h header defines EnumPropsEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
PropEnumProcEx
Reference
Window Properties
EnumPropsW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enumerates all entries in the property list of a window by passing them, one by one, to the specified callback
function. EnumProps continues until the last entry is enumerated or the callback function returns FALSE .
To pass application-defined data to the callback function, use EnumPropsEx function.
Syntax
int EnumPropsW(
HWND hWnd,
PROPENUMPROCW lpEnumFunc
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list is to be enumerated.
lpEnumFunc
Type: PROPENUMPROC
A pointer to the callback function. For more information about the callback function, see the PropEnumProc
function.
Return value
Type: int
The return value specifies the last value returned by the callback function. It is -1 if the function did not find a
property for enumeration.
Remarks
An application can remove only those properties it has added. It must not remove properties added by other
applications or by the system itself.
NOTE
The winuser.h header defines EnumProps 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumPropsEx
PropEnumProc
Reference
Window Properties
EnumThreadWindows function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enumerates all nonchild windows associated with a thread by passing the handle to each window, in turn, to an
application-defined callback function. EnumThreadWindows continues until the last window is enumerated or
the callback function returns FALSE . To enumerate child windows of a particular window, use the
EnumChildWindows function.
Syntax
BOOL EnumThreadWindows(
DWORD dwThreadId,
WNDENUMPROC lpfn,
LPARAM lParam
);
Parameters
dwThreadId
Type: DWORD
The identifier of the thread whose windows are to be enumerated.
lpfn
Type: WNDENUMPROC
A pointer to an application-defined callback function. For more information, see EnumThreadWndProc.
lParam
Type: LPARAM
An application-defined value to be passed to the callback function.
Return value
Type: BOOL
If the callback function returns TRUE for all windows in the thread specified by dwThreadId, the return value is
TRUE . If the callback function returns FALSE on any enumerated window, or if there are no windows found in
the thread specified by dwThreadId, the return value is FALSE .
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Target Platform Windows
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumChildWindows
EnumThreadWndProc
EnumWindows
Reference
Windows
EnumWindows function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Enumerates all top-level windows on the screen by passing the handle to each window, in turn, to an
application-defined callback function. EnumWindows continues until the last top-level window is enumerated
or the callback function returns FALSE .
Syntax
BOOL EnumWindows(
WNDENUMPROC lpEnumFunc,
LPARAM lParam
);
Parameters
lpEnumFunc
Type: WNDENUMPROC
A pointer to an application-defined callback function. For more information, see EnumWindowsProc.
lParam
Type: LPARAM
An application-defined value to be passed to the callback function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If EnumWindowsProc returns zero, the return value is also zero. In this case, the callback function should call
SetLastError to obtain a meaningful error code to be returned to the caller of EnumWindows .
Remarks
The EnumWindows function does not enumerate child windows, with the exception of a few top-level windows
owned by the system that have the WS_CHILD style.
This function is more reliable than calling the GetWindow function in a loop. An application that calls
GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to a window that
has been destroyed.
Note For Windows 8 and later, EnumWindows enumerates only top-level windows of desktop apps.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumChildWindows
EnumWindowsProc
GetWindow
Reference
Windows
EVENTMSG structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information about a hardware message sent to the system message queue. This structure is used to
store message information for the JournalPlaybackProc callback function.
Syntax
typedef struct tagEVENTMSG {
UINT message;
UINT paramL;
UINT paramH;
DWORD time;
HWND hwnd;
} EVENTMSG, *PEVENTMSGMSG, *NPEVENTMSGMSG, *LPEVENTMSGMSG, *PEVENTMSG, *NPEVENTMSG, *LPEVENTMSG;
Members
message
Type: UINT
The message.
paramL
Type: UINT
Additional information about the message. The exact meaning depends on the message value.
paramH
Type: UINT
Additional information about the message. The exact meaning depends on the message value.
time
Type: DWORD
The time at which the message was posted.
hwnd
Type: HWND
A handle to the window to which the message was posted.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
Hooks
JournalPlaybackProc
Reference
SetWindowsHookEx
FindWindowA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a handle to the top-level window whose class name and window name match the specified strings.
This function does not search child windows. This function does not perform a case-sensitive search.
To search child windows, beginning with a specified child window, use the FindWindowEx function.
Syntax
HWND FindWindowA(
LPCSTR lpClassName,
LPCSTR lpWindowName
);
Parameters
lpClassName
Type: LPCTSTR
The class name or a class atom created by a previous call to the RegisterClass or RegisterClassEx function. The
atom must be in the low-order word of lpClassName; the high-order word must be zero.
If lpClassName points to 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.
If lpClassName is NULL , it finds any window whose title matches the lpWindowName parameter.
lpWindowName
Type: LPCTSTR
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 name and
window name.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
If the lpWindowName parameter is not NULL , FindWindow calls the GetWindowText function to retrieve the
window name for comparison. For a description of a potential problem that can arise, see the Remarks for
GetWindowText .
Examples
For an example, see Retrieving the Number of Mouse Wheel Scroll Lines.
NOTE
The winuser.h header defines FindWindow 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumWindows
FindWindowEx
GetClassName
GetWindowText
Reference
RegisterClass
RegisterClassEx
Windows
FindWindowExA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
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(
HWND hWndParent,
HWND hWndChildAfter,
LPCSTR lpszClass,
LPCSTR lpszWindow
);
Parameters
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.
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.
lpszClass
Type: LPCTSTR
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.
lpszWindow
Type: LPCTSTR
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
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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumWindows
FindWindow
GetClassName
GetWindowText
Reference
RegisterClass
RegisterClassEx
Windows
FindWindowExW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
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 FindWindowExW(
HWND hWndParent,
HWND hWndChildAfter,
LPCWSTR lpszClass,
LPCWSTR lpszWindow
);
Parameters
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.
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.
lpszClass
Type: LPCTSTR
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.
lpszWindow
Type: LPCTSTR
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
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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumWindows
FindWindow
GetClassName
GetWindowText
Reference
RegisterClass
RegisterClassEx
Windows
FindWindowW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a handle to the top-level window whose class name and window name match the specified strings.
This function does not search child windows. This function does not perform a case-sensitive search.
To search child windows, beginning with a specified child window, use the FindWindowEx function.
Syntax
HWND FindWindowW(
LPCWSTR lpClassName,
LPCWSTR lpWindowName
);
Parameters
lpClassName
Type: LPCTSTR
The class name or a class atom created by a previous call to the RegisterClass or RegisterClassEx function. The
atom must be in the low-order word of lpClassName; the high-order word must be zero.
If lpClassName points to 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.
If lpClassName is NULL , it finds any window whose title matches the lpWindowName parameter.
lpWindowName
Type: LPCTSTR
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 name and
window name.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
If the lpWindowName parameter is not NULL , FindWindow calls the GetWindowText function to retrieve the
window name for comparison. For a description of a potential problem that can arise, see the Remarks for
GetWindowText .
Examples
For an example, see Retrieving the Number of Mouse Wheel Scroll Lines.
NOTE
The winuser.h header defines FindWindow 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
EnumWindows
FindWindowEx
GetClassName
GetWindowText
Reference
RegisterClass
RegisterClassEx
Windows
GetAltTabInfoA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves status information for the specified window if it is the application-switching (ALT+TAB) window.
Syntax
BOOL GetAltTabInfoA(
HWND hwnd,
int iItem,
PALTTABINFO pati,
LPSTR pszItemText,
UINT cchItemText
);
Parameters
hwnd
Type: HWND
A handle to the window for which status information will be retrieved. This window must be the application-
switching window.
iItem
Type: int
The index of the icon in the application-switching window. If the pszItemText parameter is not NULL , the name
of the item is copied to the pszItemText string. If this parameter is –1, the name of the item is not copied.
pati
Type: PALTTABINFO
A pointer to an ALTTABINFO structure to receive the status information. Note that you must set the csSize
member to sizeof(ALTTABINFO) before calling this function.
pszItemText
Type: LPTSTR
The name of the item. If this parameter is NULL , the name of the item is not copied.
cchItemText
Type: UINT
The size, in characters, of the pszItemText buffer.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The application-switching window enables you to switch to the most recently used application window. To
display the application-switching window, press ALT+TAB. To select an application from the list, continue to hold
ALT down and press TAB to move through the list. Add SHIFT to reverse direction through the list.
NOTE
The winuser.h header defines GetAltTabInfo 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
ALTTABINFO
Conceptual
Reference
Windows
GetAltTabInfoW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves status information for the specified window if it is the application-switching (ALT+TAB) window.
Syntax
BOOL GetAltTabInfoW(
HWND hwnd,
int iItem,
PALTTABINFO pati,
LPWSTR pszItemText,
UINT cchItemText
);
Parameters
hwnd
Type: HWND
A handle to the window for which status information will be retrieved. This window must be the application-
switching window.
iItem
Type: int
The index of the icon in the application-switching window. If the pszItemText parameter is not NULL , the name
of the item is copied to the pszItemText string. If this parameter is –1, the name of the item is not copied.
pati
Type: PALTTABINFO
A pointer to an ALTTABINFO structure to receive the status information. Note that you must set the csSize
member to sizeof(ALTTABINFO) before calling this function.
pszItemText
Type: LPTSTR
The name of the item. If this parameter is NULL , the name of the item is not copied.
cchItemText
Type: UINT
The size, in characters, of the pszItemText buffer.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The application-switching window enables you to switch to the most recently used application window. To
display the application-switching window, press ALT+TAB. To select an application from the list, continue to hold
ALT down and press TAB to move through the list. Add SHIFT to reverse direction through the list.
NOTE
The winuser.h header defines GetAltTabInfo 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
ALTTABINFO
Conceptual
Reference
Windows
GetAncestor function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
HWND GetAncestor(
HWND hwnd,
UINT gaFlags
);
Parameters
hwnd
Type: HWND
A handle to the window whose ancestor is to be retrieved. If this parameter is the desktop window, the function
returns NULL .
gaFlags
Type: UINT
The ancestor to be retrieved. This parameter can be one of the following values.
VA L UE M EA N IN G
Return value
Type: HWND
The return value is the handle to the ancestor window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetParent
Reference
Windows
GetClassInfoA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Note The GetClassInfo function has been superseded by the GetClassInfoEx function. You can still use GetClassInfo ,
however, if you do not need information about the class small icon.
Syntax
BOOL GetClassInfoA(
HINSTANCE hInstance,
LPCSTR lpClassName,
LPWNDCLASSA lpWndClass
);
Parameters
hInstance
Type: HINSTANCE
A handle to the instance of the application that created the class. To retrieve information about classes defined
by the system (such as buttons or list boxes), set this parameter to NULL .
lpClassName
Type: LPCTSTR
The class name. The name must be that of a preregistered class or a class registered by a previous call to the
RegisterClass or RegisterClassEx function.
Alternatively, this parameter can be an atom. If so, it must be a class atom created by a previous call to
RegisterClass or RegisterClassEx. The atom must be in the low-order word of lpClassName; the high-order word
must be zero.
lpWndClass
Return value
Type: BOOL
If the function finds a matching class and successfully copies the data, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
NOTE
The winuser.h header defines GetClassInfo 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassInfoEx
GetClassLong
GetClassName
Reference
RegisterClass
RegisterClassEx
WNDCLASS
Window Classes
GetClassInfoExA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves information about a window class, including a handle to the small icon associated with the window
class. The GetClassInfo function does not retrieve a handle to the small icon.
Syntax
BOOL GetClassInfoExA(
HINSTANCE hInstance,
LPCSTR lpszClass,
LPWNDCLASSEXA lpwcx
);
Parameters
hInstance
Type: HINSTANCE
A handle to the instance of the application that created the class. To retrieve information about classes defined
by the system (such as buttons or list boxes), set this parameter to NULL .
lpszClass
Type: LPCTSTR
The class name. The name must be that of a preregistered class or a class registered by a previous call to the
RegisterClass or RegisterClassEx function. Alternatively, this parameter can be a class atom created by a previous
call to RegisterClass or RegisterClassEx . The atom must be in the low-order word of lpszClass; the high-
order word must be zero.
lpwcx
Return value
Type: BOOL
If the function finds a matching class and successfully copies the data, the return value is nonzero.
If the function does not find a matching class and successfully copy the data, the return value is zero. To get
extended error information, call GetLastError.
Remarks
Class atoms are created using the RegisterClass or RegisterClassEx function, not the GlobalAddAtom function.
NOTE
The winuser.h header defines GetClassInfoEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLong
GetClassName
Reference
RegisterClass
RegisterClassEx
Window Classes
GetClassInfoExW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves information about a window class, including a handle to the small icon associated with the window
class. The GetClassInfo function does not retrieve a handle to the small icon.
Syntax
BOOL GetClassInfoExW(
HINSTANCE hInstance,
LPCWSTR lpszClass,
LPWNDCLASSEXW lpwcx
);
Parameters
hInstance
Type: HINSTANCE
A handle to the instance of the application that created the class. To retrieve information about classes defined
by the system (such as buttons or list boxes), set this parameter to NULL .
lpszClass
Type: LPCTSTR
The class name. The name must be that of a preregistered class or a class registered by a previous call to the
RegisterClass or RegisterClassEx function. Alternatively, this parameter can be a class atom created by a previous
call to RegisterClass or RegisterClassEx . The atom must be in the low-order word of lpszClass; the high-
order word must be zero.
lpwcx
Return value
Type: BOOL
If the function finds a matching class and successfully copies the data, the return value is nonzero.
If the function does not find a matching class and successfully copy the data, the return value is zero. To get
extended error information, call GetLastError.
Remarks
Class atoms are created using the RegisterClass or RegisterClassEx function, not the GlobalAddAtom function.
NOTE
The winuser.h header defines GetClassInfoEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLong
GetClassName
Reference
RegisterClass
RegisterClassEx
Window Classes
GetClassInfoW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Note The GetClassInfo function has been superseded by the GetClassInfoEx function. You can still use GetClassInfo ,
however, if you do not need information about the class small icon.
Syntax
BOOL GetClassInfoW(
HINSTANCE hInstance,
LPCWSTR lpClassName,
LPWNDCLASSW lpWndClass
);
Parameters
hInstance
Type: HINSTANCE
A handle to the instance of the application that created the class. To retrieve information about classes defined
by the system (such as buttons or list boxes), set this parameter to NULL .
lpClassName
Type: LPCTSTR
The class name. The name must be that of a preregistered class or a class registered by a previous call to the
RegisterClass or RegisterClassEx function.
Alternatively, this parameter can be an atom. If so, it must be a class atom created by a previous call to
RegisterClass or RegisterClassEx. The atom must be in the low-order word of lpClassName; the high-order word
must be zero.
lpWndClass
Return value
Type: BOOL
If the function finds a matching class and successfully copies the data, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
NOTE
The winuser.h header defines GetClassInfo 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassInfoEx
GetClassLong
GetClassName
Reference
RegisterClass
RegisterClassEx
WNDCLASS
Window Classes
GetClassLongA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the specified 32-bit (DWORD ) value from the WNDCLASSEX structure associated with the specified
window.
Note If you are retrieving a pointer or a handle, this function has been superseded by the GetClassLongPtr function.
(Pointers and handles are 32 bits on 32-bit Windows and 64 bits on 64-bit Windows.)
Syntax
DWORD GetClassLongA(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The value to be retrieved. To retrieve a value from the extra class memory, specify the positive, zero-based byte
offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra class
memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would
be an index to the third integer. To retrieve any other value from the WNDCLASSEX structure, specify one of the
following values.
VA L UE M EA N IN G
Return value
Type: DWORD
If the function succeeds, the return value is the requested value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASSEX
structure used with the RegisterClassEx function.
NOTE
The winuser.h header defines GetClassLong 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLongPtr
GetWindowLong
Reference
RegisterClassEx
SetClassLong
WNDCLASSEX
Window Classes
GetClassLongPtrA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the specified value from the WNDCLASSEX structure associated with the specified window.
Note To write code that is compatible with both 32-bit and 64-bit versions of Windows, use GetClassLongPtr . When
compiling for 32-bit Windows, GetClassLongPtr is defined as a call to the GetClassLong function.
Syntax
ULONG_PTR GetClassLongPtrA(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The value to be retrieved. To retrieve a value from the extra class memory, specify the positive, zero-based byte
offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra class
memory, minus eight; for example, if you specified 24 or more bytes of extra class memory, a value of 16 would
be an index to the third integer. To retrieve any other value from the WNDCLASSEX structure, specify one of the
following values.
VA L UE M EA N IN G
Return value
Type: ULONG_PTR
If the function succeeds, the return value is the requested value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASSEX
structure used with the RegisterClassEx function.
NOTE
The winuser.h header defines GetClassLongPtr 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowLongPtr
Reference
RegisterClassEx
SetClassLongPtr
WNDCLASSEX
Window Classes
GetClassLongPtrW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the specified value from the WNDCLASSEX structure associated with the specified window.
Note To write code that is compatible with both 32-bit and 64-bit versions of Windows, use GetClassLongPtr . When
compiling for 32-bit Windows, GetClassLongPtr is defined as a call to the GetClassLong function.
Syntax
ULONG_PTR GetClassLongPtrW(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The value to be retrieved. To retrieve a value from the extra class memory, specify the positive, zero-based byte
offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra class
memory, minus eight; for example, if you specified 24 or more bytes of extra class memory, a value of 16 would
be an index to the third integer. To retrieve any other value from the WNDCLASSEX structure, specify one of the
following values.
VA L UE M EA N IN G
Return value
Type: ULONG_PTR
If the function succeeds, the return value is the requested value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASSEX
structure used with the RegisterClassEx function.
NOTE
The winuser.h header defines GetClassLongPtr 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowLongPtr
Reference
RegisterClassEx
SetClassLongPtr
WNDCLASSEX
Window Classes
GetClassLongW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the specified 32-bit (DWORD ) value from the WNDCLASSEX structure associated with the specified
window.
Note If you are retrieving a pointer or a handle, this function has been superseded by the GetClassLongPtr function.
(Pointers and handles are 32 bits on 32-bit Windows and 64 bits on 64-bit Windows.)
Syntax
DWORD GetClassLongW(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The value to be retrieved. To retrieve a value from the extra class memory, specify the positive, zero-based byte
offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra class
memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would
be an index to the third integer. To retrieve any other value from the WNDCLASSEX structure, specify one of the
following values.
VA L UE M EA N IN G
Return value
Type: DWORD
If the function succeeds, the return value is the requested value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASSEX
structure used with the RegisterClassEx function.
NOTE
The winuser.h header defines GetClassLong 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLongPtr
GetWindowLong
Reference
RegisterClassEx
SetClassLong
WNDCLASSEX
Window Classes
GetClassName function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the name of the class to which the specified window belongs.
Syntax
int GetClassName(
HWND hWnd,
LPTSTR lpClassName,
int nMaxCount
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
lpClassName
Type: LPTSTR
The class name string.
nMaxCount
Type: int
The length of the lpClassName buffer, in characters. The buffer must be large enough to include the terminating
null character; otherwise, the class name string is truncated to nMaxCount-1 characters.
Return value
Type: int
If the function succeeds, the return value is the number of characters copied to the buffer, not including the
terminating null character.
If the function fails, the return value is zero. To get extended error information, call GetLastError function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
FindWindowA function, GetClassInfoA function, GetClassLongA function, GetClassWord function, Window
Classes
GetClassNameA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the name of the class to which the specified window belongs.
Syntax
int GetClassNameA(
HWND hWnd,
LPSTR lpClassName,
int nMaxCount
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
lpClassName
Type: LPTSTR
The class name string.
nMaxCount
Type: int
The length of the lpClassName buffer, in characters. The buffer must be large enough to include the terminating
null character; otherwise, the class name string is truncated to nMaxCount-1 characters.
Return value
Type: int
If the function succeeds, the return value is the number of characters copied to the buffer, not including the
terminating null character.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
NOTE
The winuser.h header defines GetClassName 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
FindWindow
GetClassInfo
GetClassLong
GetClassWord
Reference
Window Classes
GetClassNameW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the name of the class to which the specified window belongs.
Syntax
int GetClassNameW(
HWND hWnd,
LPWSTR lpClassName,
int nMaxCount
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
lpClassName
Type: LPTSTR
The class name string.
nMaxCount
Type: int
The length of the lpClassName buffer, in characters. The buffer must be large enough to include the terminating
null character; otherwise, the class name string is truncated to nMaxCount-1 characters.
Return value
Type: int
If the function succeeds, the return value is the number of characters copied to the buffer, not including the
terminating null character.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
NOTE
The winuser.h header defines GetClassName 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
FindWindow
GetClassInfo
GetClassLong
GetClassWord
Reference
Window Classes
GetClassWord function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the 16-bit (WORD ) value at the specified offset into the extra class memory for the window class to
which the specified window belongs.
Note This function is deprecated for any use other than nIndex set to GCW_ATOM . The function is provided only for
compatibility with 16-bit versions of Windows. Applications should use the GetClassLongPtr or GetClassLongPtr function.
Syntax
WORD GetClassWord(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of
bytes of class memory, minus two; for example, if you specified 10 or more bytes of extra class memory, a value
of eight would be an index to the fifth 16-bit integer. There is an additional valid value as shown in the following
table.
VA L UE M EA N IN G
Return value
Type: WORD
If the function succeeds, the return value is the requested 16-bit value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS
structure used with the RegisterClass function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLong
Reference
RegisterClass
RegisterClassEx
SetClassWord
WNDCLASS
Window Classes
GetClientRect function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the coordinates of a window's client area. The client coordinates specify the upper-left and lower-right
corners of the client area. Because client coordinates are relative to the upper-left corner of a window's client
area, the coordinates of the upper-left corner are (0,0).
Syntax
BOOL GetClientRect(
HWND hWnd,
LPRECT lpRect
);
Parameters
hWnd
Type: HWND
A handle to the window whose client coordinates are to be retrieved.
lpRect
Type: LPRECT
A pointer to a RECT structure that receives the client coordinates. The left and top members are zero. The right
and bottom members contain the width and height of the window.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
In conformance with conventions for the RECT structure, the bottom-right coordinates of the returned rectangle
are exclusive. In other words, the pixel at (right , bottom ) lies immediately outside the rectangle.
Examples
For example, see Creating, Enumerating, and Sizing Child Windows.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Target Platform Windows
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowRect
Other Resources
RECT
Reference
Windows
GetDesktopWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a handle to the desktop window. The desktop window covers the entire screen. The desktop window is
the area on top of which other windows are painted.
Syntax
HWND GetDesktopWindow();
Parameters
This function has no parameters.
Return value
Type: HWND
The return value is a handle to the desktop window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindow
Reference
Windows
GetForegroundWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a handle to the foreground window (the window with which the user is currently working). The system
assigns a slightly higher priority to the thread that creates the foreground window than it does to other threads.
Syntax
HWND GetForegroundWindow();
Parameters
This function has no parameters.
Return value
Type: HWND
The return value is a handle to the foreground window. The foreground window can be NULL in certain
circumstances, such as when a window is losing activation.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
SetForegroundWindow
Windows
GetGUIThreadInfo function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL GetGUIThreadInfo(
DWORD idThread,
PGUITHREADINFO pgui
);
Parameters
idThread
Type: DWORD
The identifier for the thread for which information is to be retrieved. To retrieve this value, use the
GetWindowThreadProcessId function. If this parameter is NULL , the function returns information for the
foreground thread.
pgui
Type: LPGUITHREADINFO
A pointer to a GUITHREADINFO structure that receives information describing the thread. Note that you must
set the cbSize member to sizeof(GUITHREADINFO) before calling this function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
This function succeeds even if the active window is not owned by the calling process. If the specified thread does
not exist or have an input queue, the function will fail.
This function is useful for retrieving out-of-context information about a thread. The information retrieved is the
same as if an application retrieved the information about itself.
For an edit control, the returned rcCaret rectangle contains the caret plus information on text direction and
padding. Thus, it may not give the correct position of the cursor. The Sans Serif font uses four characters for the
cursor:
C URSO R C H A RA C T ER UN IC O DE C O DE P O IN T
CURSOR_LTR 0xf00c
CURSOR_RTL 0xf00d
CURSOR_THAI 0xf00e
To get the actual insertion point in the rcCaret rectangle, perform the following steps.
1. Call GetKeyboardLayout to retrieve the current input language.
2. Determine the character used for the cursor, based on the current input language.
3. Call CreateFont using Sans Serif for the font, the height given by rcCaret , and a width of zero . For fnWeight
, call SystemParametersInfo(SPI_GETCARETWIDTH, 0, pvParam, 0) . If pvParam is greater than 1, set fnWeight to
700, otherwise set fnWeight to 400.
4. Select the font into a device context (DC) and use GetCharABCWidths to get the B width of the appropriate
cursor character.
5. Add the B width to rcCaret .left to obtain the actual insertion point.
The function may not return valid window handles in the GUITHREADINFO structure when called to retrieve
information for the foreground thread, such as when a window is losing activation.
DPI Virtualization
The coordinates returned in the rcCaret rect of the GUITHREADINFO struct are logical coordinates in terms of the
window associated with the caret. They are not virtualized into the mode of the calling thread.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GUITHREADINFO
GetCursorInfo
GetWindowThreadProcessId
Reference
Windows
GetInputState function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Determines whether there are mouse-button or keyboard messages in the calling thread's message queue.
Syntax
BOOL GetInputState();
Parameters
This function has no parameters.
Return value
Type: BOOL
If the queue contains one or more new mouse-button or keyboard messages, the return value is nonzero.
If there are no new mouse-button or keyboard messages in the queue, the return value is zero.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetQueueStatus
Messages and Message Queues
Reference
GetLastActivePopup function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Determines which pop-up window owned by the specified window was most recently active.
Syntax
HWND GetLastActivePopup(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the owner window.
Return value
Type: HWND
The return value identifies the most recently active pop-up window. The return value is the same as the hWnd
parameter, if any of the following conditions are met:
The window identified by hWnd was most recently active.
The window identified by hWnd does not own any pop-up windows.
The window identifies by hWnd is not a top-level window, or it is owned by another window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Syntax
BOOL GetLayeredWindowAttributes(
HWND hwnd,
COLORREF *pcrKey,
BYTE *pbAlpha,
DWORD *pdwFlags
);
Parameters
hwnd
Type: HWND
A handle to the layered window. A layered window is created by specifying WS_EX_L AYERED when creating
the window with the CreateWindowEx function or by setting WS_EX_L AYERED using SetWindowLong after the
window has been created.
pcrKey
Type: COLORREF *
A pointer to a COLORREF value that receives the transparency color key to be used when composing the layered
window. All pixels painted by the window in this color will be transparent. This can be NULL if the argument is
not needed.
pbAlpha
Type: BYTE*
The Alpha value used to describe the opacity of the layered window. Similar to the SourceConstantAlpha
member of the BLENDFUNCTION structure. When the variable referred to by pbAlpha is 0, the window is
completely transparent. When the variable referred to by pbAlpha is 255, the window is opaque. This can be
NULL if the argument is not needed.
pdwFlags
Type: DWORD*
A layering flag. This parameter can be NULL if the value is not needed. The layering flag can be one or more of
the following values.
VA L UE M EA N IN G
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
GetLayeredWindowAttributes can be called only if the application has previously called
SetLayeredWindowAttributes on the window. The function will fail if the layered window was setup with
UpdateLayeredWindow.
For more information, see Using Layered Windows.
Requirements
Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
CreateWindowEx
Reference
SetLayeredWindowAttributes
SetWindowLong
Using Windows
Windows
GetMessage function (winuser.h)
2/1/2021 • 4 minutes to read • Edit Online
Retrieves a message from the calling thread's message queue. The function dispatches incoming sent messages
until a posted message is available for retrieval.
Unlike GetMessage , the PeekMessage function does not wait for a message to be posted before returning.
Syntax
BOOL GetMessage(
LPMSG lpMsg,
HWND hWnd,
UINT wMsgFilterMin,
UINT wMsgFilterMax
);
Parameters
lpMsg
Type: LPMSG
A pointer to an MSG structure that receives message information from the thread's message queue.
hWnd
Type: HWND
A handle to the window whose messages are to be retrieved. The window must belong to the current thread.
If hWnd is NULL , GetMessage retrieves messages for any window that belongs to the current thread, and any
messages on the current thread's message queue whose hwnd value is NULL (see the MSG structure).
Therefore if hWnd is NULL , both window messages and thread messages are processed.
If hWnd is -1, GetMessage retrieves only messages on the current thread's message queue whose hwnd value
is NULL , that is, thread messages as posted by PostMessage (when the hWnd parameter is NULL ) or
PostThreadMessage.
wMsgFilterMin
Type: UINT
The integer value of the lowest message value to be retrieved. Use WM_KEYFIRST (0x0100) to specify the first
keyboard message or WM_MOUSEFIRST (0x0200) to specify the first mouse message.
Use WM_INPUT here and in wMsgFilterMax to specify only the WM_INPUT messages.
If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no
range filtering is performed).
wMsgFilterMax
Type: UINT
The integer value of the highest message value to be retrieved. Use WM_KEYL AST to specify the last keyboard
message or WM_MOUSEL AST to specify the last mouse message.
Use WM_INPUT here and in wMsgFilterMin to specify only the WM_INPUT messages.
If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no
range filtering is performed).
Return value
Type: BOOL
If the function retrieves a message other than WM_QUIT, the return value is nonzero.
If the function retrieves the WM_QUIT message, the return value is zero.
If there is an error, the return value is -1. For example, the function fails if hWnd is an invalid window handle or
lpMsg is an invalid pointer. To get extended error information, call GetLastError.
Because the return value can be nonzero, zero, or -1, avoid code like this:
The possibility of a -1 return value in the case that hWnd is an invalid parameter (such as referring to a window
that has already been destroyed) means that such code can lead to fatal application errors. Instead, use code like
this:
BOOL bRet;
Remarks
An application typically uses the return value to determine whether to end the main message loop and exit the
program.
The GetMessage function retrieves messages associated with the window identified by the hWnd parameter or
any of its children, as specified by the IsChild function, and within the range of message values given by the
wMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low word in the
wMsgFilterMin and wMsgFilterMax parameters; the high word is reserved for the system.
Note that GetMessage always retrieves WM_QUIT messages, no matter which values you specify for
wMsgFilterMin and wMsgFilterMax.
During this call, the system delivers pending, nonqueued messages, that is, messages sent to windows owned
by the calling thread using the SendMessage, SendMessageCallback, SendMessageTimeout, or
SendNotifyMessage function. Then the first queued message that matches the specified filter is retrieved. The
system may also process internal events. If no filter is specified, messages are processed in the following order:
Sent messages
Posted messages
Input (hardware) messages and system internal events
Sent messages (again)
WM_PAINT messages
WM_TIMER messages
To retrieve input messages before posted messages, use the wMsgFilterMin and wMsgFilterMax parameters.
GetMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until
processed.
If a top-level window stops responding to messages for more than several seconds, the system considers the
window to be not responding and replaces it with a ghost window that has the same z-order, location, size, and
visual attributes. This allows the user to move it, resize it, or even close the application. However, these are the
only actions available because the application is actually not responding. When in the debugger mode, the
system does not generate a ghost window.
DPI Virtualization
This API does not participate in DPI virtualization. The output is in the mode of the window that the message is
targeting. The calling thread is not taken into consideration.
Examples
For an example, see Creating a Message Loop.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsChild
MSG
Messages and Message Queues
PeekMessage
PostMessage
PostThreadMessage
Reference
WaitMessage
GetMessageA function (winuser.h)
2/1/2021 • 4 minutes to read • Edit Online
Retrieves a message from the calling thread's message queue. The function dispatches incoming sent messages
until a posted message is available for retrieval.
Unlike GetMessage , the PeekMessage function does not wait for a message to be posted before returning.
Syntax
BOOL GetMessageA(
LPMSG lpMsg,
HWND hWnd,
UINT wMsgFilterMin,
UINT wMsgFilterMax
);
Parameters
lpMsg
Type: LPMSG
A pointer to an MSG structure that receives message information from the thread's message queue.
hWnd
Type: HWND
A handle to the window whose messages are to be retrieved. The window must belong to the current thread.
If hWnd is NULL , GetMessage retrieves messages for any window that belongs to the current thread, and any
messages on the current thread's message queue whose hwnd value is NULL (see the MSG structure).
Therefore if hWnd is NULL , both window messages and thread messages are processed.
If hWnd is -1, GetMessage retrieves only messages on the current thread's message queue whose hwnd value
is NULL , that is, thread messages as posted by PostMessage (when the hWnd parameter is NULL ) or
PostThreadMessage.
wMsgFilterMin
Type: UINT
The integer value of the lowest message value to be retrieved. Use WM_KEYFIRST (0x0100) to specify the first
keyboard message or WM_MOUSEFIRST (0x0200) to specify the first mouse message.
Use WM_INPUT here and in wMsgFilterMax to specify only the WM_INPUT messages.
If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no
range filtering is performed).
wMsgFilterMax
Type: UINT
The integer value of the highest message value to be retrieved. Use WM_KEYL AST to specify the last keyboard
message or WM_MOUSEL AST to specify the last mouse message.
Use WM_INPUT here and in wMsgFilterMin to specify only the WM_INPUT messages.
If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no
range filtering is performed).
Return value
Type: BOOL
If the function retrieves a message other than WM_QUIT, the return value is nonzero.
If the function retrieves the WM_QUIT message, the return value is zero.
If there is an error, the return value is -1. For example, the function fails if hWnd is an invalid window handle or
lpMsg is an invalid pointer. To get extended error information, call GetLastError.
Because the return value can be nonzero, zero, or -1, avoid code like this:
The possibility of a -1 return value in the case that hWnd is an invalid parameter (such as referring to a window
that has already been destroyed) means that such code can lead to fatal application errors. Instead, use code like
this:
BOOL bRet;
Remarks
An application typically uses the return value to determine whether to end the main message loop and exit the
program.
The GetMessage function retrieves messages associated with the window identified by the hWnd parameter or
any of its children, as specified by the IsChild function, and within the range of message values given by the
wMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low word in the
wMsgFilterMin and wMsgFilterMax parameters; the high word is reserved for the system.
Note that GetMessage always retrieves WM_QUIT messages, no matter which values you specify for
wMsgFilterMin and wMsgFilterMax.
During this call, the system delivers pending, nonqueued messages, that is, messages sent to windows owned
by the calling thread using the SendMessage, SendMessageCallback, SendMessageTimeout, or
SendNotifyMessage function. Then the first queued message that matches the specified filter is retrieved. The
system may also process internal events. If no filter is specified, messages are processed in the following order:
Sent messages
Posted messages
Input (hardware) messages and system internal events
Sent messages (again)
WM_PAINT messages
WM_TIMER messages
To retrieve input messages before posted messages, use the wMsgFilterMin and wMsgFilterMax parameters.
GetMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until
processed.
If a top-level window stops responding to messages for more than several seconds, the system considers the
window to be not responding and replaces it with a ghost window that has the same z-order, location, size, and
visual attributes. This allows the user to move it, resize it, or even close the application. However, these are the
only actions available because the application is actually not responding. When in the debugger mode, the
system does not generate a ghost window.
DPI Virtualization
This API does not participate in DPI virtualization. The output is in the mode of the window that the message is
targeting. The calling thread is not taken into consideration.
Examples
For an example, see Creating a Message Loop.
NOTE
The winuser.h header defines GetMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsChild
MSG
Messages and Message Queues
PeekMessage
PostMessage
PostThreadMessage
Reference
WaitMessage
GetMessageExtraInfo function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the extra message information for the current thread. Extra message information is an application- or
driver-defined value associated with the current thread's message queue.
Syntax
LPARAM GetMessageExtraInfo();
Parameters
This function has no parameters.
Return value
Type: LPARAM
The return value specifies the extra information. The meaning of the extra information is device specific.
Remarks
To set a thread's extra message information, use the SetMessageExtraInfo function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
Messages and Message Queues
PeekMessage
Reference
SetMessageExtraInfo
GetMessagePos function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the cursor position for the last message retrieved by the GetMessage function.
To determine the current position of the cursor, use the GetCursorPos function.
Syntax
DWORD GetMessagePos();
Parameters
This function has no parameters.
Return value
Type: DWORD
The return value specifies the x- and y-coordinates of the cursor position. The x-coordinate is the low order
shor t and the y-coordinate is the high-order shor t .
Remarks
As noted above, the x-coordinate is in the low-order shor t of the return value; the y-coordinate is in the high-
order shor t (both represent signed values because they can take negative values on systems with multiple
monitors). If the return value is assigned to a variable, you can use the MAKEPOINTS macro to obtain a POINTS
structure from the return value. You can also use the GET_X_LPARAM or GET_Y_LPARAM macro to extract the x-
or y-coordinate.
Impor tant Do not use the LOWORD or HIWORD macros to extract the x- and y- coordinates of the cursor position because
these macros return incorrect results on systems with multiple monitors. Systems with multiple monitors can have negative x-
and y- coordinates, and LOWORD and HIWORD treat the coordinates as unsigned quantities.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Conceptual
GetCursorPos
GetMessage
GetMessageTime
HIWORD
LOWORD
MAKEPOINTS
Messages and Message Queues
Other Resources
POINTS
Reference
GetMessageTime function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the message time for the last message retrieved by the GetMessage function. The time is a long
integer that specifies the elapsed time, in milliseconds, from the time the system was started to the time the
message was created (that is, placed in the thread's message queue).
Syntax
LONG GetMessageTime();
Parameters
This function has no parameters.
Return value
Type: LONG
The return value specifies the message time.
Remarks
The return value from the GetMessageTime function does not necessarily increase between subsequent
messages, because the value wraps to the minimum value for a long integer if the timer count exceeds the
maximum value for a long integer.
To calculate time delays between messages, subtract the time of the first message from the time of the second
message (ignoring overflow) and compare the result of the subtraction against the desired delay amount.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Retrieves a message from the calling thread's message queue. The function dispatches incoming sent messages
until a posted message is available for retrieval.
Unlike GetMessage , the PeekMessage function does not wait for a message to be posted before returning.
Syntax
BOOL GetMessageW(
LPMSG lpMsg,
HWND hWnd,
UINT wMsgFilterMin,
UINT wMsgFilterMax
);
Parameters
lpMsg
Type: LPMSG
A pointer to an MSG structure that receives message information from the thread's message queue.
hWnd
Type: HWND
A handle to the window whose messages are to be retrieved. The window must belong to the current thread.
If hWnd is NULL , GetMessage retrieves messages for any window that belongs to the current thread, and any
messages on the current thread's message queue whose hwnd value is NULL (see the MSG structure).
Therefore if hWnd is NULL , both window messages and thread messages are processed.
If hWnd is -1, GetMessage retrieves only messages on the current thread's message queue whose hwnd value
is NULL , that is, thread messages as posted by PostMessage (when the hWnd parameter is NULL ) or
PostThreadMessage.
wMsgFilterMin
Type: UINT
The integer value of the lowest message value to be retrieved. Use WM_KEYFIRST (0x0100) to specify the first
keyboard message or WM_MOUSEFIRST (0x0200) to specify the first mouse message.
Use WM_INPUT here and in wMsgFilterMax to specify only the WM_INPUT messages.
If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no
range filtering is performed).
wMsgFilterMax
Type: UINT
The integer value of the highest message value to be retrieved. Use WM_KEYL AST to specify the last keyboard
message or WM_MOUSEL AST to specify the last mouse message.
Use WM_INPUT here and in wMsgFilterMin to specify only the WM_INPUT messages.
If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no
range filtering is performed).
Return value
Type: BOOL
If the function retrieves a message other than WM_QUIT, the return value is nonzero.
If the function retrieves the WM_QUIT message, the return value is zero.
If there is an error, the return value is -1. For example, the function fails if hWnd is an invalid window handle or
lpMsg is an invalid pointer. To get extended error information, call GetLastError.
Because the return value can be nonzero, zero, or -1, avoid code like this:
The possibility of a -1 return value in the case that hWnd is an invalid parameter (such as referring to a window
that has already been destroyed) means that such code can lead to fatal application errors. Instead, use code like
this:
BOOL bRet;
Remarks
An application typically uses the return value to determine whether to end the main message loop and exit the
program.
The GetMessage function retrieves messages associated with the window identified by the hWnd parameter or
any of its children, as specified by the IsChild function, and within the range of message values given by the
wMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low word in the
wMsgFilterMin and wMsgFilterMax parameters; the high word is reserved for the system.
Note that GetMessage always retrieves WM_QUIT messages, no matter which values you specify for
wMsgFilterMin and wMsgFilterMax.
During this call, the system delivers pending, nonqueued messages, that is, messages sent to windows owned
by the calling thread using the SendMessage, SendMessageCallback, SendMessageTimeout, or
SendNotifyMessage function. Then the first queued message that matches the specified filter is retrieved. The
system may also process internal events. If no filter is specified, messages are processed in the following order:
Sent messages
Posted messages
Input (hardware) messages and system internal events
Sent messages (again)
WM_PAINT messages
WM_TIMER messages
To retrieve input messages before posted messages, use the wMsgFilterMin and wMsgFilterMax parameters.
GetMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until
processed.
If a top-level window stops responding to messages for more than several seconds, the system considers the
window to be not responding and replaces it with a ghost window that has the same z-order, location, size, and
visual attributes. This allows the user to move it, resize it, or even close the application. However, these are the
only actions available because the application is actually not responding. When in the debugger mode, the
system does not generate a ghost window.
DPI Virtualization
This API does not participate in DPI virtualization. The output is in the mode of the window that the message is
targeting. The calling thread is not taken into consideration.
Examples
For an example, see Creating a Message Loop.
NOTE
The winuser.h header defines GetMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsChild
MSG
Messages and Message Queues
PeekMessage
PostMessage
PostThreadMessage
Reference
WaitMessage
GetNextWindow macro (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a handle to the next or previous window in the Z-Order. The next window is below the specified
window; the previous window is above.
If the specified window is a topmost window, the function searches for a topmost window. If the specified
window is a top-level window, the function searches for a top-level window. If the specified window is a child
window, the function searches for a child window.
Syntax
void GetNextWindow(
hWnd,
wCmd
);
Parameters
hWnd
Type: HWND
A handle to a window. The window handle retrieved is relative to this window, based on the value of the wCmd
parameter.
wCmd
Type: UINT
Indicates whether the function returns a handle to the next window or the previous window. This parameter can
be either of the following values.
VA L UE M EA N IN G
Return value
None
Remarks
This function is implemented as a call to the GetWindow function.
#define GetNextWindow(hWnd, wCmd) GetWindow(hWnd, wCmd)
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GetTopWindow
GetWindow
Reference
Windows
GetParent function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
HWND GetParent(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window whose parent window handle is to be retrieved.
Return value
Type: HWND
If the window is a child window, the return value is a handle to the parent window. If the window is a top-level
window with the WS_POPUP style, the return value is a handle to the owner window.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
This function typically fails for one of the following reasons:
The window is a top-level window that is unowned or does not have the WS_POPUP style.
The owner window has WS_POPUP style.
Remarks
To obtain a window's owner window, instead of using GetParent , use GetWindow with the GW_OWNER flag.
To obtain the parent window and not the owner, instead of using GetParent , use GetAncestor with the
GA_PARENT flag.
Examples
For an example, see Initializing a Dialog Box.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Target Platform Windows
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetAncestor
GetWindow
Reference
SetParent
Windows
Windows Styles
GetProcessDefaultLayout function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the default layout that is used when windows are created with no parent or owner.
Syntax
BOOL GetProcessDefaultLayout(
DWORD *pdwDefaultLayout
);
Parameters
pdwDefaultLayout
Type: DWORD*
The current default process layout. For a list of values, see SetProcessDefaultLayout.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The layout specifies how text and graphics are laid out in a window; the default is left to right. The
GetProcessDefaultLayout function lets you know if the default layout has changed, from using
SetProcessDefaultLayout.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-window-l1-1-3 (introduced in Windows
10, version 10.0.10240)
See also
Conceptual
Reference
SetProcessDefaultLayout
Windows
GetPropA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a data handle from the property list of the specified window. The character string identifies the handle
to be retrieved. The string and handle must have been added to the property list by a previous call to the
SetProp function.
Syntax
HANDLE GetPropA(
HWND hWnd,
LPCSTR lpString
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list is to be searched.
lpString
Type: LPCTSTR
An atom that identifies a string. If this parameter is an atom, it must have been created by using the
GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of the lpString
parameter; the high-order word must be zero.
Return value
Type: HANDLE
If the property list contains the string, the return value is the associated data handle. Otherwise, the return value
is NULL .
Remarks
NOTE
The winuser.h header defines GetProp 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GlobalAddAtom
Reference
SetProp
Window Properties
ITaskbarList2::MarkFullscreenWindow
GetPropW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a data handle from the property list of the specified window. The character string identifies the handle
to be retrieved. The string and handle must have been added to the property list by a previous call to the
SetProp function.
Syntax
HANDLE GetPropW(
HWND hWnd,
LPCWSTR lpString
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list is to be searched.
lpString
Type: LPCTSTR
An atom that identifies a string. If this parameter is an atom, it must have been created by using the
GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of the lpString
parameter; the high-order word must be zero.
Return value
Type: HANDLE
If the property list contains the string, the return value is the associated data handle. Otherwise, the return value
is NULL .
Remarks
NOTE
The winuser.h header defines GetProp 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GlobalAddAtom
Reference
SetProp
Window Properties
ITaskbarList2::MarkFullscreenWindow
GetQueueStatus function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the type of messages found in the calling thread's message queue.
Syntax
DWORD GetQueueStatus(
UINT flags
);
Parameters
flags
Type: UINT
The types of messages for which to check. This parameter can be one or more of the following values.
VA L UE M EA N IN G
Return value
Type: DWORD
The high-order word of the return value indicates the types of messages currently in the queue. The low-order
word indicates the types of messages that have been added to the queue and that are still in the queue since the
last call to the GetQueueStatus , GetMessage, or PeekMessage function.
Remarks
The presence of a QS_ flag in the return value does not guarantee that a subsequent call to the GetMessage or
PeekMessage function will return a message. GetMessage and PeekMessage perform some internal filtering
that may cause the message to be processed internally. For this reason, the return value from GetQueueStatus
should be considered only a hint as to whether GetMessage or PeekMessage should be called.
The QS_ALLPOSTMESSAGE and QS_POSTMESSAGE flags differ in when they are cleared.
QS_POSTMESSAGE is cleared when you call GetMessage or PeekMessage, whether or not you are filtering
messages. QS_ALLPOSTMESSAGE is cleared when you call GetMessage or PeekMessage without filtering
messages (wMsgFilterMin and wMsgFilterMax are 0). This can be useful when you call PeekMessage multiple
times to get messages in different ranges.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetInputState
GetMessage
Messages and Message Queues
PeekMessage
Reference
GetShellWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
HWND GetShellWindow();
Parameters
This function has no parameters.
Return value
Type: HWND
The return value is the handle of the Shell's desktop window. If no Shell process is present, the return value is
NULL .
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetDesktopWindow
GetWindow
Reference
Windows
GetSysColor function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Retrieves the current color of the specified display element. Display elements are the parts of a window and the
display that appear on the system display screen.
Syntax
DWORD GetSysColor(
int nIndex
);
Parameters
nIndex
Type: int
The display element whose color is to be retrieved. This parameter can be one of the following values.
VA L UE M EA N IN G
Desktop.
COLOR_BACKGROUND
1
Text in caption, size box, and scroll bar arrow box. The
COLOR_CAPTIONTEXT associated background color is COLOR_ACTIVECAPTION.
9
Desktop.
COLOR_DESKTOP
1
Window frame.
COLOR_WINDOWFRAME
6
Return value
Type: DWORD
The function returns the red, green, blue (RGB) color value of the given element.
If the nIndex parameter is out of range, the return value is zero. Because zero is also a valid RGB value, you
cannot use GetSysColor to determine whether a system color is supported by the current platform. Instead,
use the GetSysColorBrush function, which returns NULL if the color is not supported.
Remarks
To display the component of the RGB value, use the GetRValue, GetGValue, and GetBValue macros.
System colors for monochrome displays are usually interpreted as shades of gray.
To paint with a system color brush, an application should use GetSysColorBrush(nIndex) , instead of
CreateSolidBrush(GetSysColor(nIndex)) , because GetSysColorBrush returns a cached brush, instead of allocating
a new one.
Color is an important visual element of most user interfaces. For guidelines about using color in your
applications, see Color.
Examples
For an example, see SetSysColors.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CreateSolidBrush
GetSysColorBrush
SetSysColors
SystemParametersInfo
GetSystemMetrics function (winuser.h)
2/1/2021 • 16 minutes to read • Edit Online
Syntax
int GetSystemMetrics(
int nIndex
);
Parameters
nIndex
Type: int
The system metric or configuration setting to be retrieved. This parameter can be one of the following values.
Note that all SM_CX* values are widths and all SM_CY* values are heights. Also note that all settings designed to
return Boolean data represent TRUE as any nonzero value, and FALSE as a zero value.
VA L UE M EA N IN G
The width of the left and right edges of the focus rectangle
SM_CXFOCUSBORDER that the DrawFocusRect draws. This value is in pixels.
83
Windows 2000: This value is not supported.
The width of a grid cell for items in large icon view, in pixels.
SM_CXICONSPACING Each item fits into a rectangle of size SM_CXICONSPACING
38 by SM_CYICONSPACING when arranged. This value is always
greater than or equal to SM_CXICON.
The height of a grid cell for items in large icon view, in pixels.
SM_CYICONSPACING Each item fits into a rectangle of size SM_CXICONSPACING
39 by SM_CYICONSPACING when arranged. This value is always
greater than or equal to SM_CYICON.
For double byte character set versions of the system, this is
SM_CYKANJIWINDOW the height of the Kanji window at the bottom of the screen,
18 in pixels.
The coordinates for the left side of the virtual screen. The
SM_XVIRTUALSCREEN virtual screen is the bounding rectangle of all display
76 monitors. The SM_CXVIRTUALSCREEN metric is the width of
the virtual screen.
The coordinates for the top of the virtual screen. The virtual
SM_YVIRTUALSCREEN screen is the bounding rectangle of all display monitors. The
77 SM_CYVIRTUALSCREEN metric is the height of the virtual
screen.
Return value
Type: int
If the function succeeds, the return value is the requested system metric or configuration setting.
If the function fails, the return value is 0. GetLastError does not provide extended error information.
Remarks
System metrics can vary from display to display.
GetSystemMetrics (SM_CMONITORS) counts only visible display monitors. This is different from
EnumDisplayMonitors, which enumerates both visible display monitors and invisible pseudo-monitors that are
associated with mirroring drivers. An invisible pseudo-monitor is associated with a pseudo-device used to
mirror application drawing for remoting or other purposes.
The SM_ARRANGE setting specifies how the system arranges minimized windows, and consists of a starting
position and a direction. The starting position can be one of the following values.
VA L UE M EA N IN G
VA L UE M EA N IN G
ARW_HIDE Hide minimized windows by moving them off the visible area
of the screen.
The SM_DIGITIZER setting specifies the type of digitizers that are installed on a device running Windows 7 or
Windows Server 2008 R2. The return value is a bitmask that specifies one or more of the following values.
VA L UE M EA N IN G
This API is not DPI aware, and should not be used if the calling thread is per-monitor DPI aware. For the DPI-
aware version of this API, see GetSystemMetricsForDPI. For more information on DPI awareness, see the
Windows High DPI documentation.
Examples
The following example uses the GetSystemMetrics function to determine whether a mouse is installed and
whether the mouse buttons are swapped. The example also uses the SystemParametersInfo function to retrieve
the mouse threshold and speed. It displays the information in the console.
#include <windows.h>
#include <stdio.h>
#pragma comment(lib, "user32.lib")
void main()
{
BOOL fResult;
int aMouseInfo[3];
fResult = GetSystemMetrics(SM_MOUSEPRESENT);
if (fResult == 0)
printf("No mouse installed.\n");
else
{
printf("Mouse installed.\n");
fResult = GetSystemMetrics(SM_SWAPBUTTON);
if (fResult == 0)
printf("Buttons not swapped.\n");
else printf("Buttons swapped.\n");
fResult = SystemParametersInfo(
SPI_GETMOUSE, // get mouse information
0, // not used
&aMouseInfo, // holds mouse information
0); // not used
if( fResult )
{
printf("Speed: %d\n", aMouseInfo[2]);
printf("Threshold (x,y): %d,%d\n",
aMouseInfo[0], aMouseInfo[1]);
}
}
}
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Syntax
BOOL GetTitleBarInfo(
HWND hwnd,
PTITLEBARINFO pti
);
Parameters
hwnd
Type: HWND
A handle to the title bar whose information is to be retrieved.
pti
Type: PTITLEBARINFO
A pointer to a TITLEBARINFO structure to receive the information. Note that you must set the cbSize member to
sizeof(TITLEBARINFO) before calling this function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-window-l1-1-3 (introduced in Windows
10, version 10.0.10240)
See also
Conceptual
Reference
TITLEBARINFO
Windows
GetTopWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Examines the Z order of the child windows associated with the specified parent window and retrieves a handle
to the child window at the top of the Z order.
Syntax
HWND GetTopWindow(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the parent window whose child windows are to be examined. If this parameter is NULL , the function
returns a handle to the window at the top of the Z order.
Return value
Type: HWND
If the function succeeds, the return value is a handle to the child window at the top of the Z order. If the specified
window has no child windows, the return value is NULL . To get extended error information, use the GetLastError
function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetNextWindow
GetWindow
Reference
Windows
GetWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a handle to a window that has the specified relationship (Z-Order or owner) to the specified window.
Syntax
HWND GetWindow(
HWND hWnd,
UINT uCmd
);
Parameters
hWnd
Type: HWND
A handle to a window. The window handle retrieved is relative to this window, based on the value of the uCmd
parameter.
uCmd
Type: UINT
The relationship between the specified window and the window whose handle is to be retrieved. This parameter
can be one of the following values.
VA L UE M EA N IN G
Return value
Type: HWND
If the function succeeds, the return value is a window handle. If no window exists with the specified relationship
to the specified window, the return value is NULL . To get extended error information, call GetLastError.
Remarks
The EnumChildWindows function is more reliable than calling GetWindow in a loop. An application that calls
GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to a window that
has been destroyed.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Conceptual
EnumChildWindows
Reference
Windows
GetWindowDisplayAffinity function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the current display affinity setting, from any process, for a given window.
Syntax
BOOL GetWindowDisplayAffinity(
HWND hWnd,
DWORD *pdwAffinity
);
Parameters
hWnd
Type: HWND
A handle to the window.
pdwAffinity
Type: DWORD*
A pointer to a variable that receives the display affinity setting. See SetWindowDisplayAffinity for a list of affinity
settings and their meanings.
Return value
Type: BOOL
This function succeeds only when the window is layered and Desktop Windows Manager is composing the
desktop. If this function succeeds, it returns TRUE ; otherwise, it returns FALSE . To get extended error
information, call GetLastError.
Remarks
This function and SetWindowDisplayAffinity are designed to support the window content protection feature
unique to Windows 7. This feature enables applications to protect their own onscreen window content from
being captured or copied via a specific set of public operating system features and APIs. However, it works only
when the Desktop Window Manager (DWM) is composing the desktop.
It is important to note that unlike a security feature or an implementation of Digital Rights Management (DRM),
there is no guarantee that using SetWindowDisplayAffinity and GetWindowDisplayAffinity , and other
necessary functions such as DwmIsCompositionEnabled, will strictly protect windowed content, as in the case
where someone takes a photograph of the screen.
Requirements
Minimum suppor ted client Windows 7 [desktop apps only]
Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Windows
GetWindowInfo function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL GetWindowInfo(
HWND hwnd,
PWINDOWINFO pwi
);
Parameters
hwnd
Type: HWND
A handle to the window whose information is to be retrieved.
pwi
Type: PWINDOWINFO
A pointer to a WINDOWINFO structure to receive the information. Note that you must set the cbSize member
to sizeof(WINDOWINFO) before calling this function.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.
To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
WINDOWINFO
Windows
GetWindowLongA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves information about the specified window. The function also retrieves the 32-bit (DWORD ) value at the
specified offset into the extra window memory.
Note If you are retrieving a pointer or a handle, this function has been superseded by the GetWindowLongPtr function.
(Pointers and handles are 32 bits on 32-bit Windows and 64 bits on 64-bit Windows.) To write code that is compatible with
both 32-bit and 64-bit versions of Windows, use GetWindowLongPtr .
Syntax
LONG GetWindowLongA(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The zero-based offset to the value to be retrieved. Valid values are in the range zero through the number of
bytes of extra window memory, minus four; for example, if you specified 12 or more bytes of extra memory, a
value of 8 would be an index to the third 32-bit integer. To retrieve any other value, specify one of the following
values.
VA L UE M EA N IN G
Retrieves the user data associated with the window. This data
GWL_USERDATA is intended for use by the application that created the
-21 window. Its value is initially zero.
The following values are also available when the hWnd parameter identifies a dialog box.
VA L UE M EA N IN G
Return value
Type: LONG
If the function succeeds, the return value is the requested value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If SetWindowLong has not been called previously, GetWindowLong returns zero for values in the extra
window or class memory.
Remarks
Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the
WNDCLASSEX structure used with the RegisterClassEx function.
Examples
For an example, see Creating, Enumerating, and Sizing Child Windows.
NOTE
The winuser.h header defines GetWindowLong 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CallWindowProc
Conceptual
GetWindowLongPtr
Reference
RegisterClassEx
SetParent
SetWindowLong
WNDCLASS
Window Classes
GetWindowLongPtrA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves information about the specified window. The function also retrieves the value at a specified offset into
the extra window memory.
Note To write code that is compatible with both 32-bit and 64-bit versions of Windows, use GetWindowLongPtr . When
compiling for 32-bit Windows, GetWindowLongPtr is defined as a call to the GetWindowLong function.
Syntax
LONG_PTR GetWindowLongPtrA(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The zero-based offset to the value to be retrieved. Valid values are in the range zero through the number of
bytes of extra window memory, minus the size of a LONG_PTR . To retrieve any other value, specify one of the
following values.
VA L UE M EA N IN G
Retrieves the user data associated with the window. This data
GWLP_USERDATA is intended for use by the application that created the
-21 window. Its value is initially zero.
The following values are also available when the hWnd parameter identifies a dialog box.
VA L UE M EA N IN G
Return value
Type: LONG_PTR
If the function succeeds, the return value is the requested value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If SetWindowLong or SetWindowLongPtr has not been called previously, GetWindowLongPtr returns zero for
values in the extra window or class memory.
Remarks
Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the
WNDCLASSEX structure used with the RegisterClassEx function.
NOTE
The winuser.h header defines GetWindowLongPtr 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CallWindowProc
Conceptual
Reference
RegisterClassEx
SetParent
SetWindowLongPtr
WNDCLASSEX
Window Classes
GetWindowLongPtrW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves information about the specified window. The function also retrieves the value at a specified offset into
the extra window memory.
Note To write code that is compatible with both 32-bit and 64-bit versions of Windows, use GetWindowLongPtr . When
compiling for 32-bit Windows, GetWindowLongPtr is defined as a call to the GetWindowLong function.
Syntax
LONG_PTR GetWindowLongPtrW(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The zero-based offset to the value to be retrieved. Valid values are in the range zero through the number of
bytes of extra window memory, minus the size of a LONG_PTR . To retrieve any other value, specify one of the
following values.
VA L UE M EA N IN G
Retrieves the user data associated with the window. This data
GWLP_USERDATA is intended for use by the application that created the
-21 window. Its value is initially zero.
The following values are also available when the hWnd parameter identifies a dialog box.
VA L UE M EA N IN G
Return value
Type: LONG_PTR
If the function succeeds, the return value is the requested value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If SetWindowLong or SetWindowLongPtr has not been called previously, GetWindowLongPtr returns zero for
values in the extra window or class memory.
Remarks
Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the
WNDCLASSEX structure used with the RegisterClassEx function.
NOTE
The winuser.h header defines GetWindowLongPtr 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CallWindowProc
Conceptual
Reference
RegisterClassEx
SetParent
SetWindowLongPtr
WNDCLASSEX
Window Classes
GetWindowLongW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves information about the specified window. The function also retrieves the 32-bit (DWORD ) value at the
specified offset into the extra window memory.
Note If you are retrieving a pointer or a handle, this function has been superseded by the GetWindowLongPtr function.
(Pointers and handles are 32 bits on 32-bit Windows and 64 bits on 64-bit Windows.) To write code that is compatible with
both 32-bit and 64-bit versions of Windows, use GetWindowLongPtr .
Syntax
LONG GetWindowLongW(
HWND hWnd,
int nIndex
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The zero-based offset to the value to be retrieved. Valid values are in the range zero through the number of
bytes of extra window memory, minus four; for example, if you specified 12 or more bytes of extra memory, a
value of 8 would be an index to the third 32-bit integer. To retrieve any other value, specify one of the following
values.
VA L UE M EA N IN G
Retrieves the user data associated with the window. This data
GWL_USERDATA is intended for use by the application that created the
-21 window. Its value is initially zero.
The following values are also available when the hWnd parameter identifies a dialog box.
VA L UE M EA N IN G
Return value
Type: LONG
If the function succeeds, the return value is the requested value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If SetWindowLong has not been called previously, GetWindowLong returns zero for values in the extra
window or class memory.
Remarks
Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the
WNDCLASSEX structure used with the RegisterClassEx function.
Examples
For an example, see Creating, Enumerating, and Sizing Child Windows.
NOTE
The winuser.h header defines GetWindowLong 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CallWindowProc
Conceptual
GetWindowLongPtr
Reference
RegisterClassEx
SetParent
SetWindowLong
WNDCLASS
Window Classes
GetWindowModuleFileNameA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the full path and file name of the module associated with the specified window handle.
Syntax
UINT GetWindowModuleFileNameA(
HWND hwnd,
LPSTR pszFileName,
UINT cchFileNameMax
);
Parameters
hwnd
Type: HWND
A handle to the window whose module file name is to be retrieved.
pszFileName
Type: LPTSTR
The path and file name.
cchFileNameMax
Type: UINT
The maximum number of characters that can be copied into the lpszFileName buffer.
Return value
Type: UINT
The return value is the total number of characters copied into the buffer.
Remarks
NOTE
The winuser.h header defines GetWindowModuleFileName 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Windows Overview
GetWindowModuleFileNameW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the full path and file name of the module associated with the specified window handle.
Syntax
UINT GetWindowModuleFileNameW(
HWND hwnd,
LPWSTR pszFileName,
UINT cchFileNameMax
);
Parameters
hwnd
Type: HWND
A handle to the window whose module file name is to be retrieved.
pszFileName
Type: LPTSTR
The path and file name.
cchFileNameMax
Type: UINT
The maximum number of characters that can be copied into the lpszFileName buffer.
Return value
Type: UINT
The return value is the total number of characters copied into the buffer.
Remarks
NOTE
The winuser.h header defines GetWindowModuleFileName 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Windows Overview
GetWindowPlacement function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the show state and the restored, minimized, and maximized positions of the specified window.
Syntax
BOOL GetWindowPlacement(
HWND hWnd,
WINDOWPLACEMENT *lpwndpl
);
Parameters
hWnd
Type: HWND
A handle to the window.
lpwndpl
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The flags member of WINDOWPLACEMENT retrieved by this function is always zero. If the window identified
by the hWnd parameter is maximized, the showCmd member is SW_SHOWMAXIMIZED. If the window is
minimized, showCmd is SW_SHOWMINIMIZED. Otherwise, it is SW_SHOWNORMAL.
The length member of WINDOWPLACEMENT must be set to sizeof(WINDOWPL ACEMENT ). If this member is
not set correctly, the function returns FALSE . For additional remarks on the proper use of window placement
coordinates, see WINDOWPL ACEMENT .
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
SetWindowPlacement
WINDOWPLACEMENT
Windows
GetWindowRect function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the dimensions of the bounding rectangle of the specified window. The dimensions are given in screen
coordinates that are relative to the upper-left corner of the screen.
Syntax
BOOL GetWindowRect(
HWND hWnd,
LPRECT lpRect
);
Parameters
hWnd
Type: HWND
A handle to the window.
lpRect
Type: LPRECT
A pointer to a RECT structure that receives the screen coordinates of the upper-left and lower-right corners of
the window.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
In conformance with conventions for the RECT structure, the bottom-right coordinates of the returned rectangle
are exclusive. In other words, the pixel at (right , bottom ) lies immediately outside the rectangle.
GetWindowRect is virtualized for DPI.
In Windows Vista and later, the Window Rect now includes the area occupied by the drop shadow.
Calling GetWindowRect will have different behavior depending on whether the window has ever been shown or
not. If the window has not been shown before, GetWindowRect will not include the area of the drop shadow.
To get the window bounds excluding the drop shadow, use DwmGetWindowAttribute, specifying
DWMWA_EXTENDED_FRAME_BOUNDS . Note that unlike the Window Rect, the DWM Extended Frame
Bounds are not adjusted for DPI. Getting the extended frame bounds can only be done after the window has
been shown at least once.
Examples
For an example, see Initializing a Dialog Box.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClientRect
Reference
ScreenToClient
SetWindowPos
Windows
GetWindowTextA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Copies the text of the specified window's title bar (if it has one) into a buffer. If the specified window is a control,
the text of the control is copied. However, GetWindowText cannot retrieve the text of a control in another
application.
Syntax
int GetWindowTextA(
HWND hWnd,
LPSTR lpString,
int nMaxCount
);
Parameters
hWnd
Type: HWND
A handle to the window or control containing the text.
lpString
Type: LPTSTR
The buffer that will receive the text. If the string is as long or longer than the buffer, the string is truncated and
terminated with a null character.
nMaxCount
Type: int
The maximum number of characters to copy to the buffer, including the null character. If the text exceeds this
limit, it is truncated.
Return value
Type: int
If the function succeeds, the return value is the length, in characters, of the copied string, not including the
terminating null character. If the window has no title bar or text, if the title bar is empty, or if the window or
control handle is invalid, the return value is zero. To get extended error information, call GetLastError.
This function cannot retrieve the text of an edit control in another application.
Remarks
If the target window is owned by the current process, GetWindowText causes a WM_GETTEXT message to be
sent to the specified window or control. If the target window is owned by another process and has a caption,
GetWindowText retrieves the window caption text. If the window does not have a caption, the return value is a
null string. This behavior is by design. It allows applications to call GetWindowText without becoming
unresponsive if the process that owns the target window is not responding. However, if the target window is not
responding and it belongs to the calling application, GetWindowText will cause the calling application to
become unresponsive.
To retrieve the text of a control in another process, send a WM_GETTEXT message directly instead of calling
GetWindowText .
Examples
For an example, see Sending a Message.
NOTE
The winuser.h header defines GetWindowText 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowTextLength
Reference
SetWindowText
WM_GETTEXT
Windows
GetWindowTextLengthA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the length, in characters, of the specified window's title bar text (if the window has a title bar). If the
specified window is a control, the function retrieves the length of the text within the control. However,
GetWindowTextLength cannot retrieve the length of the text of an edit control in another application.
Syntax
int GetWindowTextLengthA(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window or control.
Return value
Type: int
If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this
value might be greater than the length of the text (see Remarks).
If the window has no text, the return value is zero.
Function failure is indicated by a return value of zero and a GetLastError result that is nonzero.
NOTE
This function does not clear the most recent error information. To determine success or failure, clear the most recent error
information by calling SetLastError with 0, then call GetLastError.
Remarks
If the target window is owned by the current process, GetWindowTextLength causes a WM_GETTEXTLENGTH
message to be sent to the specified window or control.
Under certain conditions, the GetWindowTextLength function may return a value that is larger than the actual
length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for
the possible existence of double-byte character set (DBCS) characters within the text. The return value, however,
will always be at least as large as the actual length of the text; you can thus always use it to guide buffer
allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which
use Unicode. It can also occur when an application uses the ANSI version of GetWindowTextLength with a
window whose window procedure is Unicode, or the Unicode version of GetWindowTextLength with a
window whose window procedure is ANSI. For more information on ANSI and ANSI functions, see Conventions
for Function Prototypes.
To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the
GetWindowText function.
NOTE
The winuser.h header defines GetWindowTextLength 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CB_GETLBTEXT
Conceptual
GetWindowText
LB_GETTEXT
Other Resources
Reference
SetWindowText
WM_GETTEXT
WM_GETTEXTLENGTH
Windows
GetWindowTextLengthW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the length, in characters, of the specified window's title bar text (if the window has a title bar). If the
specified window is a control, the function retrieves the length of the text within the control. However,
GetWindowTextLength cannot retrieve the length of the text of an edit control in another application.
Syntax
int GetWindowTextLengthW(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window or control.
Return value
Type: int
If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this
value might be greater than the length of the text (see Remarks).
If the window has no text, the return value is zero.
Function failure is indicated by a return value of zero and a GetLastError result that is nonzero.
NOTE
This function does not clear the most recent error information. To determine success or failure, clear the most recent error
information by calling SetLastError with 0, then call GetLastError.
Remarks
If the target window is owned by the current process, GetWindowTextLength causes a WM_GETTEXTLENGTH
message to be sent to the specified window or control.
Under certain conditions, the GetWindowTextLength function may return a value that is larger than the actual
length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for
the possible existence of double-byte character set (DBCS) characters within the text. The return value, however,
will always be at least as large as the actual length of the text; you can thus always use it to guide buffer
allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which
use Unicode. It can also occur when an application uses the ANSI version of GetWindowTextLength with a
window whose window procedure is Unicode, or the Unicode version of GetWindowTextLength with a
window whose window procedure is ANSI. For more information on ANSI and ANSI functions, see Conventions
for Function Prototypes.
To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the
GetWindowText function.
NOTE
The winuser.h header defines GetWindowTextLength 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CB_GETLBTEXT
Conceptual
GetWindowText
LB_GETTEXT
Other Resources
Reference
SetWindowText
WM_GETTEXT
WM_GETTEXTLENGTH
Windows
GetWindowTextW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Copies the text of the specified window's title bar (if it has one) into a buffer. If the specified window is a control,
the text of the control is copied. However, GetWindowText cannot retrieve the text of a control in another
application.
Syntax
int GetWindowTextW(
HWND hWnd,
LPWSTR lpString,
int nMaxCount
);
Parameters
hWnd
Type: HWND
A handle to the window or control containing the text.
lpString
Type: LPTSTR
The buffer that will receive the text. If the string is as long or longer than the buffer, the string is truncated and
terminated with a null character.
nMaxCount
Type: int
The maximum number of characters to copy to the buffer, including the null character. If the text exceeds this
limit, it is truncated.
Return value
Type: int
If the function succeeds, the return value is the length, in characters, of the copied string, not including the
terminating null character. If the window has no title bar or text, if the title bar is empty, or if the window or
control handle is invalid, the return value is zero. To get extended error information, call GetLastError.
This function cannot retrieve the text of an edit control in another application.
Remarks
If the target window is owned by the current process, GetWindowText causes a WM_GETTEXT message to be
sent to the specified window or control. If the target window is owned by another process and has a caption,
GetWindowText retrieves the window caption text. If the window does not have a caption, the return value is a
null string. This behavior is by design. It allows applications to call GetWindowText without becoming
unresponsive if the process that owns the target window is not responding. However, if the target window is not
responding and it belongs to the calling application, GetWindowText will cause the calling application to
become unresponsive.
To retrieve the text of a control in another process, send a WM_GETTEXT message directly instead of calling
GetWindowText .
Examples
For an example, see Sending a Message.
NOTE
The winuser.h header defines GetWindowText 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowTextLength
Reference
SetWindowText
WM_GETTEXT
Windows
GetWindowThreadProcessId function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves the identifier of the thread that created the specified window and, optionally, the identifier of the
process that created the window.
Syntax
DWORD GetWindowThreadProcessId(
HWND hWnd,
LPDWORD lpdwProcessId
);
Parameters
hWnd
Type: HWND
A handle to the window.
lpdwProcessId
Type: LPDWORD
A pointer to a variable that receives the process identifier. If this parameter is not NULL ,
GetWindowThreadProcessId copies the identifier of the process to the variable; otherwise, it does not.
Return value
Type: DWORD
The return value is the identifier of the thread that created the window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-window-l1-1-0 (introduced in Windows
8)
See also
Windows Overview
GUITHREADINFO structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagGUITHREADINFO {
DWORD cbSize;
DWORD flags;
HWND hwndActive;
HWND hwndFocus;
HWND hwndCapture;
HWND hwndMenuOwner;
HWND hwndMoveSize;
HWND hwndCaret;
RECT rcCaret;
} GUITHREADINFO, *PGUITHREADINFO, *LPGUITHREADINFO;
Members
cbSize
Type: DWORD
The size of this structure, in bytes. The caller must set this member to sizeof(GUITHREADINFO) .
flags
Type: DWORD
The thread state. This member can be one or more of the following values.
VA L UE M EA N IN G
The caret's blink state. This bit is set if the caret is visible.
GUI_CARETBLINKING
0x00000001
The thread's pop-up menu state. This bit is set if the thread
GUI_POPUPMENUMODE has an active pop-up menu.
0x00000010
The thread's system menu state. This bit is set if the thread is
GUI_SYSTEMMENUMODE in a system menu mode.
0x00000008
hwndActive
Type: HWND
A handle to the active window within the thread.
hwndFocus
Type: HWND
A handle to the window that has the keyboard focus.
hwndCapture
Type: HWND
A handle to the window that has captured the mouse.
hwndMenuOwner
Type: HWND
A handle to the window that owns any active menus.
hwndMoveSize
Type: HWND
A handle to the window in a move or size loop.
hwndCaret
Type: HWND
A handle to the window that is displaying the caret.
rcCaret
Type: RECT
The caret's bounding rectangle, in client coordinates, relative to the window specified by the hwndCaret
member.
Remarks
This structure is used with the GetGUIThreadInfo function to retrieve information about the active window or a
specified GUI thread.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Header winuser.h (include Windows.h)
See also
Conceptual
GetGUIThreadInfo
Reference
Windows
HOOKPROC callback function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
An application-defined or library-defined callback function used with the SetWindowsHookEx function. The
system calls this function after the SendMessage function is called. The hook procedure can examine the
message; it cannot modify it.
The HOOKPROC type defines a pointer to this callback function. CallWndRetProc is a placeholder for the
application-defined or library-defined function name.
Syntax
HOOKPROC Hookproc;
LRESULT Hookproc(
int code,
WPARAM wParam,
LPARAM lParam
)
{...}
Parameters
code
wParam
Type: WPARAM
Specifies whether the message is sent by the current process. If the message is sent by the current process, it is
nonzero; otherwise, it is NULL .
lParam
Type: LPARAM
A pointer to a CWPRETSTRUCT structure that contains details about the message.
Return value
Type: LRESULT
If nCode is less than zero, the hook procedure must return the value returned by CallNextHookEx.
If nCode is greater than or equal to zero, it is highly recommended that you call CallNextHookEx and return the
value it returns; otherwise, other applications that have installed WH_CALLWNDPROCRET hooks will not receive
hook notifications and may behave incorrectly as a result. If the hook procedure does not call CallNextHookEx ,
the return value should be zero.
Remarks
An application installs the hook procedure by specifying the WH_CALLWNDPROCRET hook type and a pointer
to the hook procedure in a call to the SetWindowsHookEx function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
CWPRETSTRUCT
CallNextHookEx
CallWndProc
Conceptual
Hooks
Reference
SendMessage
SetWindowsHookEx
InSendMessage function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Determines whether the current window procedure is processing a message that was sent from another thread
(in the same process or a different process) by a call to the SendMessage function.
To obtain additional information about how the message was sent, use the InSendMessageEx function.
Syntax
BOOL InSendMessage();
Parameters
This function has no parameters.
Return value
Type: BOOL
If the window procedure is processing a message sent to it from another thread using the SendMessage
function, the return value is nonzero.
If the window procedure is not processing a message sent to it from another thread using the SendMessage
function, the return value is zero.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
InSendMessageEx
Messages and Message Queues
Reference
SendMessage
InSendMessageEx function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Determines whether the current window procedure is processing a message that was sent from another thread
(in the same process or a different process).
Syntax
DWORD InSendMessageEx(
LPVOID lpReserved
);
Parameters
lpReserved
Type: LPVOID
Reserved; must be NULL .
Return value
Type: DWORD
If the message was not sent, the return value is ISMEX_NOSEND (0x00000000). Otherwise, the return value is
one or more of the following values.
Remarks
To determine if the sender is blocked, use the following test:
fBlocked = ( InSendMessageEx(NULL) & (ISMEX_REPLIED|ISMEX_SEND) ) == ISMEX_SEND;
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Messages and Message Queues
Reference
SendMessage
SendMessageCallback
SendMessageTimeout
SendNotifyMessage
InternalGetWindowText function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
[This function is not intended for general use. It may be altered or unavailable in subsequent versions of
Windows.]
Copies the text of the specified window's title bar (if it has one) into a buffer.
This function is similar to the GetWindowText function. However, it obtains the window text directly from the
window structure associated with the specified window's handle and then always provides the text as a Unicode
string. This is unlike GetWindowText which obtains the text by sending the window a WM_GETTEXT message. If
the specified window is a control, the text of the control is obtained.
Syntax
int InternalGetWindowText(
HWND hWnd,
LPWSTR pString,
int cchMaxCount
);
Parameters
hWnd
Type: HWND
A handle to the window or control containing the text.
pString
Type: LPWSTR
The buffer that is to receive the text.
If the
string is as long or longer than the buffer, the string is truncated and
terminated with a null character.
cchMaxCount
Type: int
The maximum number of characters to be copied to the buffer, including the null character. If the text exceeds
this limit, it is truncated.
Return value
Type: int
If the function succeeds, the return value is the length, in characters, of the copied string, not including the
terminating null character. If the window has no title bar or text, if the title bar is empty, or if the window or
control handle is invalid, the return value is zero. To get extended error information, call GetLastError.
Remarks
This function was not included in the SDK headers and libraries until Windows XP with Service Pack 1 (SP1) and
Windows Server 2003. If you do not have a header file and import library for this function, you can call the
function using LoadLibrary and GetProcAddress.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowText
GetWindowTextLength
Reference
SetWindowText
Using Messages and Message Queues
WM_GETTEXT
Windows
IsChild function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Determines whether a window is a child window or descendant window of a specified parent window. A child
window is the direct descendant of a specified parent window if that parent window is in the chain of parent
windows; the chain of parent windows leads from the original overlapped or pop-up window to the child
window.
Syntax
BOOL IsChild(
HWND hWndParent,
HWND hWnd
);
Parameters
hWndParent
Type: HWND
A handle to the parent window.
hWnd
Type: HWND
A handle to the window to be tested.
Return value
Type: BOOL
If the window is a child or descendant window of the specified parent window, the return value is nonzero.
If the window is not a child or descendant window of the specified parent window, the return value is zero.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsWindow
Reference
SetParent
Windows
IsGUIThread function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Determines whether the calling thread is already a GUI thread. It can also optionally convert the thread to a GUI
thread.
Syntax
BOOL IsGUIThread(
BOOL bConvert
);
Parameters
bConvert
Type: BOOL
If TRUE and the thread is not a GUI thread, convert the thread to a GUI thread.
Return value
Type: BOOL
The function returns a nonzero value in the following situations:
If the calling thread is already a GUI thread.
If bConvert is TRUE and the function successfully converts the thread to a GUI thread.
Otherwise, the function returns zero.
If bConvert is TRUE and the function cannot successfully convert the thread to a GUI thread, IsGUIThread
returns ERROR_NOT_ENOUGH_MEMORY .
Requirements
Minimum suppor ted ser ver Windows Server 2003 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Windows Overview
IsHungAppWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
[This function is not intended for general use. It may be altered or unavailable in subsequent versions of
Windows.]
Determines whether the system considers that a specified application is not responding. An application is
considered to be not responding if it is not waiting for input, is not in startup processing, and has not called
PeekMessage within the internal timeout period of 5 seconds.
Syntax
BOOL IsHungAppWindow(
HWND hwnd
);
Parameters
hwnd
Type: HWND
A handle to the window to be tested.
Return value
Type: BOOL
The return value is TRUE if the window stops responding; otherwise, it is FALSE . Ghost windows always return
TRUE .
Remarks
The Windows timeout criteria of 5 seconds is subject to change.
This function was not included in the SDK headers and libraries until Windows XP Service Pack 1 (SP1) and
Windows Server 2003. If you do not have a header file and import library for this function, you can call the
function using LoadLibrary and GetProcAddress.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Conceptual
IsWindow
Reference
Windows
IsIconic function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL IsIconic(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to be tested.
Return value
Type: BOOL
If the window is iconic, the return value is nonzero.
If the window is not iconic, the return value is zero.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsZoomed
Reference
Windows
IsProcessDPIAware function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
[IsProcessDPIAware is available for use in the operating systems specified in the Requirements section. It may be
altered or unavailable in subsequent versions. Instead, use GetProcessDPIAwareness.]
Determines whether the current process is dots per inch (dpi) aware such that it adjusts the sizes of UI elements
to compensate for the dpi setting.
Syntax
BOOL IsProcessDPIAware();
Parameters
This function has no parameters.
Return value
Type: BOOL
TRUE if the process is dpi aware; otherwise, FALSE .
Requirements
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
Librar y User32.lib
DLL User32.dll
IsWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL IsWindow(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to be tested.
Return value
Type: BOOL
If the window handle identifies an existing window, the return value is nonzero.
If the window handle does not identify an existing window, the return value is zero.
Remarks
A thread should not use IsWindow for a window that it did not create because the window could be destroyed
after this function was called. Further, because window handles are recycled the handle could even point to a
different window.
Examples
For an example, see Creating a Modeless Dialog Box.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsWindowEnabled
IsWindowVisible
Reference
Windows
IsWindowUnicode function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL IsWindowUnicode(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to be tested.
Return value
Type: BOOL
If the window is a native Unicode window, the return value is nonzero.
If the window is not a native Unicode window, the return value is zero. The window is a native ANSI window.
Remarks
The character set of a window is determined by the use of the RegisterClass function. If the window class was
registered with the ANSI version of RegisterClass (RegisterClassA ), the character set of the window is ANSI. If
the window class was registered with the Unicode version of RegisterClass (RegisterClassW ), the character
set of the window is Unicode.
The system does automatic two-way translation (Unicode to ANSI) for window messages. For example, if an
ANSI window message is sent to a window that uses the Unicode character set, the system translates that
message into a Unicode message before calling the window procedure. The system calls IsWindowUnicode to
determine whether to translate the message.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Windows Overview
IsWindowVisible function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL IsWindowVisible(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to be tested.
Return value
Type: BOOL
If the specified window, its parent window, its parent's parent window, and so forth, have the WS_VISIBLE style,
the return value is nonzero. Otherwise, the return value is zero.
Because the return value specifies whether the window has the WS_VISIBLE style, it may be nonzero even if the
window is totally obscured by other windows.
Remarks
The visibility state of a window is indicated by the WS_VISIBLE style bit. When WS_VISIBLE is set, the window
is displayed and subsequent drawing into it is displayed as long as the window has the WS_VISIBLE style.
Any drawing to a window with the WS_VISIBLE style will not be displayed if the window is obscured by other
windows or is clipped by its parent window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
ShowWindow
Windows
IsZoomed function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL IsZoomed(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to be tested.
Return value
Type: BOOL
If the window is zoomed, the return value is nonzero.
If the window is not zoomed, the return value is zero.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsIconic
Reference
Windows
KBDLLHOOKSTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagKBDLLHOOKSTRUCT {
DWORD vkCode;
DWORD scanCode;
DWORD flags;
DWORD time;
ULONG_PTR dwExtraInfo;
} KBDLLHOOKSTRUCT, *LPKBDLLHOOKSTRUCT, *PKBDLLHOOKSTRUCT;
Members
vkCode
Type: DWORD
A virtual-key code. The code must be a value in the range 1 to 254.
scanCode
Type: DWORD
A hardware scan code for the key.
flags
Type: DWORD
The extended-key flag, event-injected flags, context code, and transition-state flag. This member is specified as
follows. An application can use the following values to test the keystroke flags. Testing LLKHF_INJECTED (bit 4)
will tell you whether the event was injected. If it was, then testing LLKHF_LOWER_IL_INJECTED (bit 1) will tell you
whether or not the event was injected from a process running at lower integrity level.
VA L UE M EA N IN G
B IT S DESC RIP T IO N
2-3 Reserved.
6 Reserved.
time
Type: DWORD
The time stamp for this message, equivalent to what GetMessageTime would return for this message.
dwExtraInfo
Type: ULONG_PTR
Additional information associated with the message.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Header winuser.h (include Windows.h)
See also
Conceptual
Hooks
LowLevelKeyboardProc
Reference
SetWindowsHookEx
KillTimer function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL KillTimer(
HWND hWnd,
UINT_PTR uIDEvent
);
Parameters
hWnd
Type: HWND
A handle to the window associated with the specified timer. This value must be the same as the hWnd value
passed to the SetTimer function that created the timer.
uIDEvent
Type: UINT_PTR
The timer to be destroyed. If the window handle passed to SetTimer is valid, this parameter must be the same as
the nIDEvent
value passed to SetTimer . If the application calls SetTimer with hWnd set to NULL , this parameter must be the
timer identifier returned by SetTimer .
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The KillTimer function does not remove WM_TIMER messages already posted to the message queue.
Examples
For an example, see Destroying a Timer.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
SetTimer
Timers
WM_TIMER
LockSetForegroundWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
The foreground process can call the LockSetForegroundWindow function to disable calls to the
SetForegroundWindow function.
Syntax
BOOL LockSetForegroundWindow(
UINT uLockCode
);
Parameters
uLockCode
Type: UINT
Specifies whether to enable or disable calls to SetForegroundWindow. This parameter can be one of the
following values.
VA L UE M EA N IN G
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The system automatically enables calls to SetForegroundWindow if the user presses the ALT key or takes some
action that causes the system itself to change the foreground window (for example, clicking a background
window).
This function is provided so applications can prevent other applications from making a foreground change that
can interrupt its interaction with the user.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AllowSetForegroundWindow
Conceptual
Reference
SetForegroundWindow
Windows
LogicalToPhysicalPoint function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL LogicalToPhysicalPoint(
HWND hWnd,
LPPOINT lpPoint
);
Parameters
hWnd
Type: HWND
A handle to the window whose transform is used for the conversion. Top level windows are fully supported. In
the case of child windows, only the area of overlap between the parent and the child window is converted.
lpPoint
Type: LPPOINT
A pointer to a POINT structure that specifies the logical coordinates to be converted. The new physical
coordinates are copied into this structure if the function succeeds.
Return value
None
Remarks
Windows Vista introduces the concept of physical coordinates. Desktop Window Manager (DWM) scales non-
dots per inch (dpi) aware windows when the display is high dpi. The window seen on the screen corresponds to
the physical coordinates. The application continues to work in logical space. Therefore, the application's view of
the window is different from that which appears on the screen. For scaled windows, logical and physical
coordinates are different.
LogicalToPhysicalPoint is a transformation API that can be called by a process that declares itself as dpi
aware. The function uses the window identified by the hWnd parameter and the logical coordinates given in the
POINT structure to compute the physical coordinates.
The LogicalToPhysicalPoint function replaces the logical coordinates in the POINT structure with the physical
coordinates. The physical coordinates are relative to the upper-left corner of the screen. The coordinates have to
be inside the client area of hWnd.
On all platforms, LogicalToPhysicalPoint will fail on a window that has either 0 width or height; an application
must first establish a non-0 width and height by calling, for example, MoveWindow. On some versions of
Windows (including Windows 7), LogicalToPhysicalPoint will still fail if MoveWindow has been called after a
call to ShowWindow with SH_HIDE has hidden the window.
In Windows 8, system–DPI aware applications translate between physical and logical space using
PhysicalToLogicalPoint and LogicalToPhysicalPoint. In Windows 8.1, the additional virtualization of the system
and inter-process communications means that for the majority of applications, you do not need these APIs. As a
result, in Windows 8.1, PhysicalToLogicalPoint and LogicalToPhysicalPoint no longer transform points. The
system returns all points to an application in its own coordinate space. This behavior preserves functionality for
the majority of applications, but there are some exceptions in which you must make changes to ensure that the
application works as expected. In those cases, use PhysicalToLogicalPointForPerMonitorDPI and
LogicalToPhysicalPointForPerMonitorDPI.
Requirements
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
Librar y User32.lib
DLL User32.dll
Creates a value for use as an lParam parameter in a message. The macro concatenates the specified values.
Syntax
void MAKELPARAM(
l,
h
);
Parameters
l
Return value
None
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
MAKELONG
MAKELRESULT
MAKEWPARAM
Reference
Windows Data Types
MAKELRESULT macro (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Creates a value for use as a return value from a window procedure. The macro concatenates the specified
values.
Syntax
void MAKELRESULT(
l,
h
);
Parameters
l
Return value
None
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
MAKELONG
MAKELPARAM
MAKEWPARAM
Reference
Windows Data Types
MAKEWPARAM macro (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Creates a value for use as a wParam parameter in a message. The macro concatenates the specified values.
Syntax
void MAKEWPARAM(
l,
h
);
Parameters
l
Return value
None
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
MAKELONG
MAKELPARAM
MAKELRESULT
Reference
Windows Data Types
MDICREATESTRUCTA structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information about the class, title, owner, location, and size of a multiple-document interface (MDI) child
window.
Syntax
typedef struct tagMDICREATESTRUCTA {
LPCSTR szClass;
LPCSTR szTitle;
HANDLE hOwner;
int x;
int y;
int cx;
int cy;
DWORD style;
LPARAM lParam;
} MDICREATESTRUCTA, *LPMDICREATESTRUCTA;
Members
szClass
Type: LPCTSTR
The name of the window class of the MDI child window. The class name must have been registered by a
previous call to the RegisterClass function.
szTitle
Type: LPCTSTR
The title of the MDI child window. The system displays the title in the child window's title bar.
hOwner
Type: HANDLE
A handle to the instance of the application creating the MDI client window.
x
Type: int
The initial horizontal position, in client coordinates, of the MDI child window. If this member is
CW_USEDEFAULT , the MDI child window is assigned the default horizontal position.
y
Type: int
The initial vertical position, in client coordinates, of the MDI child window. If this member is CW_USEDEFAULT ,
the MDI child window is assigned the default vertical position.
cx
Type: int
The initial width, in device units, of the MDI child window. If this member is CW_USEDEFAULT , the MDI child
window is assigned the default width.
cy
Type: int
The initial height, in device units, of the MDI child window. If this member is set to CW_USEDEFAULT , the MDI
child window is assigned the default height.
style
Type: DWORD
The style of the MDI child window. If the MDI client window was created with the MDIS_ALLCHILDSTYLES
window style, this member can be any combination of the window styles listed in the Window Styles page.
Otherwise, this member can be one or more of the following values.
VA L UE M EA N IN G
lParam
Type: LPARAM
An application-defined value.
Remarks
When the MDI client window creates an MDI child window by calling CreateWindow, the system sends a
WM_CREATE message to the created window. The lParam member of the WM_CREATE message contains a
pointer to a CREATESTRUCT structure. The lpCreateParams member of this structure contains a pointer to the
MDICREATESTRUCT structure passed with the WM_MDICREATE message that created the MDI child window.
NOTE
The winuser.h header defines MDICREATESTRUCT 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
CLIENTCREATESTRUCT
CREATESTRUCT
Conceptual
Multiple Document Interface
Reference
WM_CREATE
MDICREATESTRUCTW structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information about the class, title, owner, location, and size of a multiple-document interface (MDI) child
window.
Syntax
typedef struct tagMDICREATESTRUCTW {
LPCWSTR szClass;
LPCWSTR szTitle;
HANDLE hOwner;
int x;
int y;
int cx;
int cy;
DWORD style;
LPARAM lParam;
} MDICREATESTRUCTW, *LPMDICREATESTRUCTW;
Members
szClass
Type: LPCTSTR
The name of the window class of the MDI child window. The class name must have been registered by a
previous call to the RegisterClass function.
szTitle
Type: LPCTSTR
The title of the MDI child window. The system displays the title in the child window's title bar.
hOwner
Type: HANDLE
A handle to the instance of the application creating the MDI client window.
x
Type: int
The initial horizontal position, in client coordinates, of the MDI child window. If this member is
CW_USEDEFAULT , the MDI child window is assigned the default horizontal position.
y
Type: int
The initial vertical position, in client coordinates, of the MDI child window. If this member is CW_USEDEFAULT ,
the MDI child window is assigned the default vertical position.
cx
Type: int
The initial width, in device units, of the MDI child window. If this member is CW_USEDEFAULT , the MDI child
window is assigned the default width.
cy
Type: int
The initial height, in device units, of the MDI child window. If this member is set to CW_USEDEFAULT , the MDI
child window is assigned the default height.
style
Type: DWORD
The style of the MDI child window. If the MDI client window was created with the MDIS_ALLCHILDSTYLES
window style, this member can be any combination of the window styles listed in the Window Styles page.
Otherwise, this member can be one or more of the following values.
VA L UE M EA N IN G
lParam
Type: LPARAM
An application-defined value.
Remarks
When the MDI client window creates an MDI child window by calling CreateWindow, the system sends a
WM_CREATE message to the created window. The lParam member of the WM_CREATE message contains a
pointer to a CREATESTRUCT structure. The lpCreateParams member of this structure contains a pointer to the
MDICREATESTRUCT structure passed with the WM_MDICREATE message that created the MDI child window.
NOTE
The winuser.h header defines MDICREATESTRUCT 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
CLIENTCREATESTRUCT
CREATESTRUCT
Conceptual
Multiple Document Interface
Reference
WM_CREATE
MINIMIZEDMETRICS structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains the scalable metrics associated with minimized windows. This structure is used with the
SystemParametersInfo function when the SPI_GETMINIMIZEDMETRICS or SPI_SETMINIMIZEDMETRICS action
value is specified.
Syntax
typedef struct tagMINIMIZEDMETRICS {
UINT cbSize;
int iWidth;
int iHorzGap;
int iVertGap;
int iArrange;
} MINIMIZEDMETRICS, *PMINIMIZEDMETRICS, *LPMINIMIZEDMETRICS;
Members
cbSize
The size of the structure, in bytes. The caller must set this to sizeof(MINIMIZEDMETRICS) .
iWidth
The starting position and direction used when arranging minimized windows. The starting position must be one
of the following values.
VA L UE M EA N IN G
VA L UE M EA N IN G
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
SystemParametersInfo
MINMAXINFO structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information about a window's maximized size and position and its minimum and maximum tracking
size.
Syntax
typedef struct tagMINMAXINFO {
POINT ptReserved;
POINT ptMaxSize;
POINT ptMaxPosition;
POINT ptMinTrackSize;
POINT ptMaxTrackSize;
} MINMAXINFO, *PMINMAXINFO, *LPMINMAXINFO;
Members
ptReserved
Type: POINT
Reserved; do not use.
ptMaxSize
Type: POINT
The maximized width (x member) and the maximized height (y member) of the window. For top-level windows,
this value is based on the width of the primary monitor.
ptMaxPosition
Type: POINT
The position of the left side of the maximized window (x member) and the position of the top of the maximized
window (y member). For top-level windows, this value is based on the position of the primary monitor.
ptMinTrackSize
Type: POINT
The minimum tracking width (x member) and the minimum tracking height (y member) of the window. This
value can be obtained programmatically from the system metrics SM_CXMINTRACK and SM_CYMINTRACK
(see the GetSystemMetrics function).
ptMaxTrackSize
Type: POINT
The maximum tracking width (x member) and the maximum tracking height (y member) of the window. This
value is based on the size of the virtual screen and can be obtained programmatically from the system metrics
SM_CXMAXTRACK and SM_CYMAXTRACK (see the GetSystemMetrics function).
Remarks
For systems with multiple monitors, the ptMaxSize and ptMaxPosition members describe the maximized size
and position of the window on the primary monitor, even if the window ultimately maximizes onto a secondary
monitor. In that case, the window manager adjusts these values to compensate for differences between the
primary monitor and the monitor that displays the window. Thus, if the user leaves ptMaxSize untouched, a
window on a monitor larger than the primary monitor maximizes to the size of the larger monitor.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
POINT
Reference
WM_GETMINMAXINFO
Windows
MOUSEHOOKSTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information about a mouse event passed to a WH_MOUSE hook procedure, MouseProc.
Syntax
typedef struct tagMOUSEHOOKSTRUCT {
POINT pt;
HWND hwnd;
UINT wHitTestCode;
ULONG_PTR dwExtraInfo;
} MOUSEHOOKSTRUCT, *LPMOUSEHOOKSTRUCT, *PMOUSEHOOKSTRUCT;
Members
pt
Type: POINT
The x- and y-coordinates of the cursor, in screen coordinates.
hwnd
Type: HWND
A handle to the window that will receive the mouse message corresponding to the mouse event.
wHitTestCode
Type: UINT
The hit-test value. For a list of hit-test values, see the description of the WM_NCHITTEST message.
dwExtraInfo
Type: ULONG_PTR
Additional information associated with the message.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
Hooks
MouseProc
Reference
SetWindowsHookEx
WM_NCHITTEST
MOUSEHOOKSTRUCTEX structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information about a mouse event passed to a WH_MOUSE hook procedure, MouseProc.
This is an extension of the MOUSEHOOKSTRUCT structure that includes information about wheel movement or
the use of the X button.
Syntax
typedef struct tagMOUSEHOOKSTRUCTEX : tagMOUSEHOOKSTRUCT {
DWORD mouseData;
} MOUSEHOOKSTRUCTEX, *LPMOUSEHOOKSTRUCTEX, *PMOUSEHOOKSTRUCTEX;
Inheritance
The MOUSEHOOKSTRUCTEX structure implements tagMOUSEHOOKSTRUCT.
Members
mouseData
Type: DWORD
If the message is WM_MOUSEWHEEL, the HIWORD of this member is the wheel delta. The LOWORD is
undefined and reserved. A positive value indicates that the wheel was rotated forward, away from the user; a
negative value indicates that the wheel was rotated backward, toward the user. One wheel click is defined as
WHEEL_DELTA, which is 120.
If the message is WM_XBUTTONDOWN, WM_XBUTTONUP, WM_XBUTTONDBLCLK, WM_NCXBUTTONDOWN,
WM_NCXBUTTONUP, or WM_NCXBUTTONDBLCLK, the HIWORD of mouseData specifies which X button was
pressed or released, and the LOWORD is undefined and reserved. This member can be one or more of the
following values. Otherwise, mouseData is not used.
VA L UE M EA N IN G
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
Hooks
MOUSEHOOKSTRUCT
MouseProc
Reference
WM_MOUSEWHEEL
WM_NCXBUTTONDBLCLK
WM_NCXBUTTONDOWN
WM_NCXBUTTONUP
WM_XBUTTONDBLCLK
WM_XBUTTONDOWN
WM_XBUTTONUP
MoveWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Changes the position and dimensions of the specified window. For a top-level window, the position and
dimensions are relative to the upper-left corner of the screen. For a child window, they are relative to the upper-
left corner of the parent window's client area.
Syntax
BOOL MoveWindow(
HWND hWnd,
int X,
int Y,
int nWidth,
int nHeight,
BOOL bRepaint
);
Parameters
hWnd
Type: HWND
A handle to the window.
X
Type: int
The new position of the left side of the window.
Y
Type: int
The new position of the top of the window.
nWidth
Type: int
The new width of the window.
nHeight
Type: int
The new height of the window.
bRepaint
Type: BOOL
Indicates whether the window is to be repainted. If this parameter is TRUE , the window receives a message. If
the parameter is FALSE , no repainting of any kind occurs. This applies to the client area, the nonclient area
(including the title bar and scroll bars), and any part of the parent window uncovered as a result of moving a
child window.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If the bRepaint parameter is TRUE , the system sends the WM_PAINT message to the window procedure
immediately after moving the window (that is, the MoveWindow function calls the UpdateWindow function). If
bRepaint is FALSE , the application must explicitly invalidate or redraw any parts of the window and parent
window that need redrawing.
MoveWindow sends the WM_WINDOWPOSCHANGING, WM_WINDOWPOSCHANGED, WM_MOVE, WM_SIZE,
and WM_NCCALCSIZE messages to the window.
Examples
For an example, see Creating, Enumerating, and Sizing Child Windows.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Other Resources
Reference
SetWindowPos
UpdateWindow
WM_GETMINMAXINFO
WM_PAINT
Windows
MSG structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagMSG {
HWND hwnd;
UINT message;
WPARAM wParam;
LPARAM lParam;
DWORD time;
POINT pt;
DWORD lPrivate;
} MSG, *PMSG, *NPMSG, *LPMSG;
Members
hwnd
Type: HWND
A handle to the window whose window procedure receives the message. This member is NULL when the
message is a thread message.
message
Type: UINT
The message identifier. Applications can only use the low word; the high word is reserved by the system.
wParam
Type: WPARAM
Additional information about the message. The exact meaning depends on the value of the message member.
lParam
Type: LPARAM
Additional information about the message. The exact meaning depends on the value of the message member.
time
Type: DWORD
The time at which the message was posted.
pt
Type: POINT
The cursor position, in screen coordinates, when the message was posted.
lPrivate
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps | UWP apps]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps | UWP apps]
See also
Conceptual
GetMessage
Messages and Message Queues
PeekMessage
PostThreadMessage
Reference
MSLLHOOKSTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagMSLLHOOKSTRUCT {
POINT pt;
DWORD mouseData;
DWORD flags;
DWORD time;
ULONG_PTR dwExtraInfo;
} MSLLHOOKSTRUCT, *LPMSLLHOOKSTRUCT, *PMSLLHOOKSTRUCT;
Members
pt
Type: POINT
The x- and y-coordinates of the cursor, in per-monitor-aware screen coordinates.
mouseData
Type: DWORD
If the message is WM_MOUSEWHEEL, the high-order word of this member is the wheel delta. The low-order
word is reserved. A positive value indicates that the wheel was rotated forward, away from the user; a negative
value indicates that the wheel was rotated backward, toward the user. One wheel click is defined as
WHEEL_DELTA , which is 120.
If the message is WM_XBUTTONDOWN, WM_XBUTTONUP, WM_XBUTTONDBLCLK, WM_NCXBUTTONDOWN,
WM_NCXBUTTONUP, or WM_NCXBUTTONDBLCLK, the high-order word specifies which X button was pressed
or released, and the low-order word is reserved. This value can be one or more of the following values.
Otherwise, mouseData is not used.
VA L UE M EA N IN G
flags
Type: DWORD
The event-injected flags. An application can use the following values to test the flags. Testing LLMHF_INJECTED
(bit 0) will tell you whether the event was injected. If it was, then testing LLMHF_LOWER_IL_INJECTED (bit 1) will
tell you whether or not the event was injected from a process running at lower integrity level.
VA L UE M EA N IN G
time
Type: DWORD
The time stamp for this message.
dwExtraInfo
Type: ULONG_PTR
Additional information associated with the message.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
Hooks
LowLevelMouseProc
Other Resources
POINT
Reference
SetWindowsHookEx
WM_MOUSEWHEEL
WM_NCXBUTTONDBLCLK
WM_NCXBUTTONDOWN
WM_NCXBUTTONUP
WM_XBUTTONDBLCLK
WM_XBUTTONDOWN
WM_XBUTTONUP
NCCALCSIZE_PARAMS structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains information that an application can use while processing the WM_NCCALCSIZE message to calculate
the size, position, and valid contents of the client area of a window.
Syntax
typedef struct tagNCCALCSIZE_PARAMS {
RECT rgrc[3];
PWINDOWPOS lppos;
} NCCALCSIZE_PARAMS, *LPNCCALCSIZE_PARAMS;
Members
rgrc
Type: PWINDOWPOS
A pointer to a WINDOWPOS structure that contains the size and position values specified in the operation that
moved or resized the window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Contains the scalable metrics associated with the nonclient area of a nonminimized window. This structure is
used by the SPI_GETNONCLIENTMETRICS and SPI_SETNONCLIENTMETRICS actions of the
SystemParametersInfo function.
Syntax
typedef struct tagNONCLIENTMETRICSA {
UINT cbSize;
int iBorderWidth;
int iScrollWidth;
int iScrollHeight;
int iCaptionWidth;
int iCaptionHeight;
LOGFONTA lfCaptionFont;
int iSmCaptionWidth;
int iSmCaptionHeight;
LOGFONTA lfSmCaptionFont;
int iMenuWidth;
int iMenuHeight;
LOGFONTA lfMenuFont;
LOGFONTA lfStatusFont;
LOGFONTA lfMessageFont;
int iPaddedBorderWidth;
} NONCLIENTMETRICSA, *PNONCLIENTMETRICSA, *LPNONCLIENTMETRICSA;
Members
cbSize
The size of the structure, in bytes. The caller must set this to sizeof(NONCLIENTMETRICS) . For information about
application compatibility, see Remarks.
iBorderWidth
A LOGFONT structure that contains information about the small caption font.
iMenuWidth
A LOGFONT structure that contains information about the font used in menu bars.
lfStatusFont
A LOGFONT structure that contains information about the font used in status bars and tooltips.
lfMessageFont
A LOGFONT structure that contains information about the font used in message boxes.
iPaddedBorderWidth
The thickness of the padded border, in pixels. The default value is 4 pixels. The iPaddedBorderWidth and
iBorderWidth members are combined for both resizable and nonresizable windows in the Windows Aero
desktop experience. To compile an application that uses this member, define _WIN32_WINNT as 0x0600 or
later. For more information, see Remarks.
Windows Ser ver 2003 and Windows XP/2000: This member is not supported.
Remarks
If the iPaddedBorderWidth member of the NONCLIENTMETRICS structure is present, this structure is 4 bytes
larger than for an application that is compiled with _WIN32_WINNT less than or equal to 0x0502. For more
information about conditional compilation, see Using the Windows Headers.
Windows Ser ver 2003 and Windows XP/2000: If an application that is compiled for Windows
Server 2008 or Windows Vista must also run on Windows Server 2003 or Windows XP/2000, use the
GetVersionEx function to check the operating system version at run time and, if the application is running on
Windows Server 2003 or Windows XP/2000, subtract the size of the iPaddedBorderWidth member from the
cbSize member of the NONCLIENTMETRICS structure before calling the SystemParametersInfo function.
NOTE
The winuser.h header defines NONCLIENTMETRICS 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
LOGFONT
SystemParametersInfo
NONCLIENTMETRICSW structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Contains the scalable metrics associated with the nonclient area of a nonminimized window. This structure is
used by the SPI_GETNONCLIENTMETRICS and SPI_SETNONCLIENTMETRICS actions of the
SystemParametersInfo function.
Syntax
typedef struct tagNONCLIENTMETRICSW {
UINT cbSize;
int iBorderWidth;
int iScrollWidth;
int iScrollHeight;
int iCaptionWidth;
int iCaptionHeight;
LOGFONTW lfCaptionFont;
int iSmCaptionWidth;
int iSmCaptionHeight;
LOGFONTW lfSmCaptionFont;
int iMenuWidth;
int iMenuHeight;
LOGFONTW lfMenuFont;
LOGFONTW lfStatusFont;
LOGFONTW lfMessageFont;
int iPaddedBorderWidth;
} NONCLIENTMETRICSW, *PNONCLIENTMETRICSW, *LPNONCLIENTMETRICSW;
Members
cbSize
The size of the structure, in bytes. The caller must set this to sizeof(NONCLIENTMETRICS) . For information about
application compatibility, see Remarks.
iBorderWidth
A LOGFONT structure that contains information about the small caption font.
iMenuWidth
A LOGFONT structure that contains information about the font used in menu bars.
lfStatusFont
A LOGFONT structure that contains information about the font used in status bars and tooltips.
lfMessageFont
A LOGFONT structure that contains information about the font used in message boxes.
iPaddedBorderWidth
The thickness of the padded border, in pixels. The default value is 4 pixels. The iPaddedBorderWidth and
iBorderWidth members are combined for both resizable and nonresizable windows in the Windows Aero
desktop experience. To compile an application that uses this member, define _WIN32_WINNT as 0x0600 or
later. For more information, see Remarks.
Windows Ser ver 2003 and Windows XP/2000: This member is not supported.
Remarks
If the iPaddedBorderWidth member of the NONCLIENTMETRICS structure is present, this structure is 4 bytes
larger than for an application that is compiled with _WIN32_WINNT less than or equal to 0x0502. For more
information about conditional compilation, see Using the Windows Headers.
Windows Ser ver 2003 and Windows XP/2000: If an application that is compiled for Windows
Server 2008 or Windows Vista must also run on Windows Server 2003 or Windows XP/2000, use the
GetVersionEx function to check the operating system version at run time and, if the application is running on
Windows Server 2003 or Windows XP/2000, subtract the size of the iPaddedBorderWidth member from the
cbSize member of the NONCLIENTMETRICS structure before calling the SystemParametersInfo function.
NOTE
The winuser.h header defines NONCLIENTMETRICS 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
LOGFONT
SystemParametersInfo
OpenIcon function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Restores a minimized (iconic) window to its previous size and position; it then activates the window.
Syntax
BOOL OpenIcon(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window to be restored and activated.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
OpenIcon sends a WM_QUERYOPEN message to the given window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CloseWindow
Conceptual
IsIconic
Reference
ShowWindow
Windows
PeekMessageA function (winuser.h)
2/1/2021 • 4 minutes to read • Edit Online
Dispatches incoming sent messages, checks the thread message queue for a posted message, and retrieves the
message (if any exist).
Syntax
BOOL PeekMessageA(
LPMSG lpMsg,
HWND hWnd,
UINT wMsgFilterMin,
UINT wMsgFilterMax,
UINT wRemoveMsg
);
Parameters
lpMsg
Type: LPMSG
A pointer to an MSG structure that receives message information.
hWnd
Type: HWND
A handle to the window whose messages are to be retrieved. The window must belong to the current thread.
If hWnd is NULL , PeekMessage retrieves messages for any window that belongs to the current thread, and any
messages on the current thread's message queue whose hwnd value is NULL (see the MSG structure).
Therefore if hWnd is NULL , both window messages and thread messages are processed.
If hWnd is -1, PeekMessage retrieves only messages on the current thread's message queue whose hwnd
value is NULL , that is, thread messages as posted by PostMessage (when the hWnd parameter is NULL ) or
PostThreadMessage.
wMsgFilterMin
Type: UINT
The value of the first message in the range of messages to be examined. Use WM_KEYFIRST (0x0100) to
specify the first keyboard message or WM_MOUSEFIRST (0x0200) to specify the first mouse message.
If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (that is, no
range filtering is performed).
wMsgFilterMax
Type: UINT
The value of the last message in the range of messages to be examined. Use WM_KEYL AST to specify the last
keyboard message or WM_MOUSEL AST to specify the last mouse message.
If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (that is, no
range filtering is performed).
wRemoveMsg
Type: UINT
Specifies how messages are to be handled. This parameter can be one or more of the following values.
VA L UE M EA N IN G
By default, all message types are processed. To specify that only certain message should be processed, specify
one or more of the following values.
VA L UE M EA N IN G
Return value
Type: BOOL
If a message is available, the return value is nonzero.
If no messages are available, the return value is zero.
Remarks
PeekMessage retrieves messages associated with the window identified by the hWnd parameter or any of its
children as specified by the IsChild function, and within the range of message values given by the
wMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low word in the
wMsgFilterMin and wMsgFilterMax parameters; the high word is reserved for the system.
Note that PeekMessage always retrieves WM_QUIT messages, no matter which values you specify for
wMsgFilterMin and wMsgFilterMax.
During this call, the system delivers pending, nonqueued messages, that is, messages sent to windows owned
by the calling thread using the SendMessage, SendMessageCallback, SendMessageTimeout, or
SendNotifyMessage function. Then the first queued message that matches the specified filter is retrieved. The
system may also process internal events. If no filter is specified, messages are processed in the following order:
Sent messages
Posted messages
Input (hardware) messages and system internal events
Sent messages (again)
WM_PAINT messages
WM_TIMER messages
To retrieve input messages before posted messages, use the wMsgFilterMin and wMsgFilterMax parameters.
The PeekMessage function normally does not remove WM_PAINT messages from the queue. WM_PAINT
messages remain in the queue until they are processed. However, if a WM_PAINT message has a NULL update
region, PeekMessage does remove it from the queue.
If a top-level window stops responding to messages for more than several seconds, the system considers the
window to be not responding and replaces it with a ghost window that has the same z-order, location, size, and
visual attributes. This allows the user to move it, resize it, or even close the application. However, these are the
only actions available because the application is actually not responding. When an application is being
debugged, the system does not generate a ghost window.
DPI Virtualization
This API does not participate in DPI virtualization. The output is in the mode of the window that the message is
targeting. The calling thread is not taken into consideration.
Examples
For an example, see Examining a Message Queue.
NOTE
The winuser.h header defines PeekMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
IsChild
MSG
Messages and Message Queues
Other Resources
Reference
WaitForInputIdle
WaitMessage
PeekMessageW function (winuser.h)
2/1/2021 • 4 minutes to read • Edit Online
Dispatches incoming sent messages, checks the thread message queue for a posted message, and retrieves the
message (if any exist).
Syntax
BOOL PeekMessageW(
LPMSG lpMsg,
HWND hWnd,
UINT wMsgFilterMin,
UINT wMsgFilterMax,
UINT wRemoveMsg
);
Parameters
lpMsg
Type: LPMSG
A pointer to an MSG structure that receives message information.
hWnd
Type: HWND
A handle to the window whose messages are to be retrieved. The window must belong to the current thread.
If hWnd is NULL , PeekMessage retrieves messages for any window that belongs to the current thread, and any
messages on the current thread's message queue whose hwnd value is NULL (see the MSG structure).
Therefore if hWnd is NULL , both window messages and thread messages are processed.
If hWnd is -1, PeekMessage retrieves only messages on the current thread's message queue whose hwnd
value is NULL , that is, thread messages as posted by PostMessage (when the hWnd parameter is NULL ) or
PostThreadMessage.
wMsgFilterMin
Type: UINT
The value of the first message in the range of messages to be examined. Use WM_KEYFIRST (0x0100) to
specify the first keyboard message or WM_MOUSEFIRST (0x0200) to specify the first mouse message.
If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (that is, no
range filtering is performed).
wMsgFilterMax
Type: UINT
The value of the last message in the range of messages to be examined. Use WM_KEYL AST to specify the last
keyboard message or WM_MOUSEL AST to specify the last mouse message.
If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (that is, no
range filtering is performed).
wRemoveMsg
Type: UINT
Specifies how messages are to be handled. This parameter can be one or more of the following values.
VA L UE M EA N IN G
By default, all message types are processed. To specify that only certain message should be processed, specify
one or more of the following values.
VA L UE M EA N IN G
Return value
Type: BOOL
If a message is available, the return value is nonzero.
If no messages are available, the return value is zero.
Remarks
PeekMessage retrieves messages associated with the window identified by the hWnd parameter or any of its
children as specified by the IsChild function, and within the range of message values given by the
wMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low word in the
wMsgFilterMin and wMsgFilterMax parameters; the high word is reserved for the system.
Note that PeekMessage always retrieves WM_QUIT messages, no matter which values you specify for
wMsgFilterMin and wMsgFilterMax.
During this call, the system delivers pending, nonqueued messages, that is, messages sent to windows owned
by the calling thread using the SendMessage, SendMessageCallback, SendMessageTimeout, or
SendNotifyMessage function. Then the first queued message that matches the specified filter is retrieved. The
system may also process internal events. If no filter is specified, messages are processed in the following order:
Sent messages
Posted messages
Input (hardware) messages and system internal events
Sent messages (again)
WM_PAINT messages
WM_TIMER messages
To retrieve input messages before posted messages, use the wMsgFilterMin and wMsgFilterMax parameters.
The PeekMessage function normally does not remove WM_PAINT messages from the queue. WM_PAINT
messages remain in the queue until they are processed. However, if a WM_PAINT message has a NULL update
region, PeekMessage does remove it from the queue.
If a top-level window stops responding to messages for more than several seconds, the system considers the
window to be not responding and replaces it with a ghost window that has the same z-order, location, size, and
visual attributes. This allows the user to move it, resize it, or even close the application. However, these are the
only actions available because the application is actually not responding. When an application is being
debugged, the system does not generate a ghost window.
DPI Virtualization
This API does not participate in DPI virtualization. The output is in the mode of the window that the message is
targeting. The calling thread is not taken into consideration.
Examples
For an example, see Examining a Message Queue.
NOTE
The winuser.h header defines PeekMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
IsChild
MSG
Messages and Message Queues
Other Resources
Reference
WaitForInputIdle
WaitMessage
PhysicalToLogicalPoint function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL PhysicalToLogicalPoint(
HWND hWnd,
LPPOINT lpPoint
);
Parameters
hWnd
Type: HWND
A handle to the window whose transform is used for the conversion. Top level windows are fully supported. In
the case of child windows, only the area of overlap between the parent and the child window is converted.
lpPoint
Type: LPPOINT
A pointer to a POINT structure that specifies the physical/screen coordinates to be converted. The new logical
coordinates are copied into this structure if the function succeeds.
Return value
None
Remarks
Windows Vista introduces the concept of physical coordinates. Desktop Window Manager (DWM) scales non-
dots per inch (dpi) aware windows when the display is high dpi. The window seen on the screen corresponds to
the physical coordinates. The application continues to work in logical space. Therefore, the application's view of
the window is different from that which appears on the screen. For scaled windows, logical and physical
coordinates are different.
The function uses the window identified by the hWnd parameter and the physical coordinates given in the
POINT structure to compute the logical coordinates. The logical coordinates are the unscaled coordinates that
appear to the application in a programmatic way. In other words, the logical coordinates are the coordinates the
application recognizes, which can be different from the physical coordinates. The API then replaces the physical
coordinates with the logical coordinates. The new coordinates are in the world coordinates whose origin is (0, 0)
on the desktop. The coordinates passed to the API have to be on the hWnd.
The source coordinates are in device units.
On all platforms, PhysicalToLogicalPoint will fail on a window that has either 0 width or height; an application
must first establish a non-0 width and height by calling, for example, MoveWindow. On some versions of
Windows (including Windows 7), PhysicalToLogicalPoint will still fail if MoveWindow has been called after a
call to ShowWindow with SH_HIDE has hidden the window.
In Windows 8, system–DPI aware applications translate between physical and logical space using
PhysicalToLogicalPoint and LogicalToPhysicalPoint. In Windows 8.1, the additional virtualization of the system
and inter-process communications means that for the majority of applications, you do not need these APIs. As a
result, in Windows 8.1, PhysicalToLogicalPoint and LogicalToPhysicalPoint no longer transform points. The
system returns all points to an application in its own coordinate space. This behavior preserves functionality for
the majority of applications, but there are some exceptions in which you must make changes to ensure that the
application works as expected. In those cases, use PhysicalToLogicalPointForPerMonitorDPI and
LogicalToPhysicalPointForPerMonitorDPI.
Requirements
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
Librar y User32.lib
DLL User32.dll
Places (posts) a message in the message queue associated with the thread that created the specified window
and returns without waiting for the thread to process the message.
To post a message in the message queue associated with a thread, use the PostThreadMessage function.
Syntax
BOOL PostMessageA(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure is to receive the message. The following values have special
meanings.
VA L UE M EA N IN G
Starting with Windows Vista, message posting is subject to UIPI. The thread of a process can post messages only
to message queues of threads in processes of lesser or equal integrity level.
Msg
Type: UINT
The message to be posted.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError
returns ERROR_NOT_ENOUGH_QUOTA when the limit is hit.
Remarks
When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied).
Messages in a message queue are retrieved by calls to the GetMessage or PeekMessage function.
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage ,
SendNotifyMessage, and SendMessageCallback), its message parameters cannot include pointers. Otherwise,
the operation will fail. The functions will return before the receiving thread has had a chance to process the
message and the sender will free the memory before it is used.
Do not post the WM_QUIT message using PostMessage ; use the PostQuitMessage function.
An accessibility application can use PostMessage to post WM_APPCOMMAND messages to the shell to launch
applications. This functionality is not guaranteed to work for other types of applications.
A message queue can contain at most 10,000 messages. This limit should be sufficiently large. If your
application exceeds the limit, it should be redesigned to avoid consuming so many system resources. To adjust
this limit, modify the following registry key.
HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
Windows NT
CurrentVersion
Windows
USERPostMessageLimit
NOTE
The winuser.h header defines PostMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
Messages and Message Queues
PeekMessage
PostQuitMessage
PostThreadMessage
Reference
RegisterWindowMessage
SendMessageCallback
SendNotifyMessage
PostMessageW function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Places (posts) a message in the message queue associated with the thread that created the specified window
and returns without waiting for the thread to process the message.
To post a message in the message queue associated with a thread, use the PostThreadMessage function.
Syntax
BOOL PostMessageW(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure is to receive the message. The following values have special
meanings.
VA L UE M EA N IN G
Starting with Windows Vista, message posting is subject to UIPI. The thread of a process can post messages only
to message queues of threads in processes of lesser or equal integrity level.
Msg
Type: UINT
The message to be posted.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError
returns ERROR_NOT_ENOUGH_QUOTA when the limit is hit.
Remarks
When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied).
Messages in a message queue are retrieved by calls to the GetMessage or PeekMessage function.
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage ,
SendNotifyMessage, and SendMessageCallback), its message parameters cannot include pointers. Otherwise,
the operation will fail. The functions will return before the receiving thread has had a chance to process the
message and the sender will free the memory before it is used.
Do not post the WM_QUIT message using PostMessage ; use the PostQuitMessage function.
An accessibility application can use PostMessage to post WM_APPCOMMAND messages to the shell to launch
applications. This functionality is not guaranteed to work for other types of applications.
There is a limit of 10,000 posted messages per message queue. This limit should be sufficiently large. If your
application exceeds the limit, it should be redesigned to avoid consuming so many system resources. To adjust
this limit, modify the following registry key.
HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
Windows NT
CurrentVersion
Windows
USERPostMessageLimit
NOTE
The winuser.h header defines PostMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
Messages and Message Queues
PeekMessage
PostQuitMessage
PostThreadMessage
Reference
RegisterWindowMessage
SendMessageCallback
SendNotifyMessage
PostQuitMessage function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Indicates to the system that a thread has made a request to terminate (quit). It is typically used in response to a
WM_DESTROY message.
Syntax
void PostQuitMessage(
int nExitCode
);
Parameters
nExitCode
Type: int
The application exit code. This value is used as the wParam parameter of the WM_QUIT message.
Return value
None
Remarks
The PostQuitMessage function posts a WM_QUIT message to the thread's message queue and returns
immediately; the function simply indicates to the system that the thread is requesting to quit at some time in the
future.
When the thread retrieves the WM_QUIT message from its message queue, it should exit its message loop and
return control to the system. The exit value returned to the system must be the wParam parameter of the
WM_QUIT message.
Examples
For an example, see Posting a Message.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
Messages and Message Queues
PeekMessage
PostMessage
Reference
WM_DESTROY
WM_QUIT
PostThreadMessageA function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Posts a message to the message queue of the specified thread. It returns without waiting for the thread to
process the message.
Syntax
BOOL PostThreadMessageA(
DWORD idThread,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
idThread
Type: DWORD
The identifier of the thread to which the message is to be posted.
The function fails if the specified thread does not have a message queue. The system creates a thread's message
queue when the thread makes its first call to one of the User or GDI functions. For more information, see the
Remarks section.
Message posting is subject to UIPI. The thread of a process can post messages only to posted-message queues
of threads in processes of lesser or equal integrity level.
This thread must have the SE_TCB_NAME privilege to post a message to a thread that belongs to a process
with the same locally unique identifier (LUID) but is in a different desktop. Otherwise, the function fails and
returns ERROR_INVALID_THREAD_ID .
This thread must either belong to the same desktop as the calling thread or to a process with the same LUID.
Otherwise, the function fails and returns ERROR_INVALID_THREAD_ID .
Msg
Type: UINT
The type of message to be posted.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError
returns ERROR_INVALID_THREAD_ID if idThread is not a valid thread identifier, or if the thread specified by
idThread does not have a message queue. GetLastError returns ERROR_NOT_ENOUGH_QUOTA when the
message limit is hit.
Remarks
When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied).
The thread to which the message is posted must have created a message queue, or else the call to
PostThreadMessage fails. Use the following method to handle this situation.
Create an event object, then create the thread.
Use the WaitForSingleObject function to wait for the event to be set to the signaled state before calling
PostThreadMessage .
In the thread to which the message will be posted, call PeekMessage as shown here to force the system to
create the message queue.
PeekMessage(&msg, NULL, WM_USER, WM_USER, PM_NOREMOVE)
Set the event, to indicate that the thread is ready to receive posted messages.
The thread to which the message is posted retrieves the message by calling the GetMessage or PeekMessage
function. The hwnd member of the returned MSG structure is NULL .
Messages sent by PostThreadMessage are not associated with a window. As a general rule, messages that are
not associated with a window cannot be dispatched by the DispatchMessage function. Therefore, if the recipient
thread is in a modal loop (as used by MessageBox or DialogBox), the messages will be lost. To intercept thread
messages while in a modal loop, use a thread-specific hook.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
There is a limit of 10,000 posted messages per message queue. This limit should be sufficiently large. If your
application exceeds the limit, it should be redesigned to avoid consuming so many system resources. To adjust
this limit, modify the following registry key.
HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
Windows NT
CurrentVersion
Windows
USERPostMessageLimit
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetCurrentThreadId
GetMessage
GetWindowThreadProcessId
MSG
Messages and Message Queues
Other Resources
PeekMessage
PostMessage
Reference
Sleep
WaitForSingleObject
PostThreadMessageW function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Posts a message to the message queue of the specified thread. It returns without waiting for the thread to
process the message.
Syntax
BOOL PostThreadMessageW(
DWORD idThread,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
idThread
Type: DWORD
The identifier of the thread to which the message is to be posted.
The function fails if the specified thread does not have a message queue. The system creates a thread's message
queue when the thread makes its first call to one of the User or GDI functions. For more information, see the
Remarks section.
Message posting is subject to UIPI. The thread of a process can post messages only to posted-message queues
of threads in processes of lesser or equal integrity level.
This thread must have the SE_TCB_NAME privilege to post a message to a thread that belongs to a process
with the same locally unique identifier (LUID) but is in a different desktop. Otherwise, the function fails and
returns ERROR_INVALID_THREAD_ID .
This thread must either belong to the same desktop as the calling thread or to a process with the same LUID.
Otherwise, the function fails and returns ERROR_INVALID_THREAD_ID .
Msg
Type: UINT
The type of message to be posted.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError
returns ERROR_INVALID_THREAD_ID if idThread is not a valid thread identifier, or if the thread specified by
idThread does not have a message queue. GetLastError returns ERROR_NOT_ENOUGH_QUOTA when the
message limit is hit.
Remarks
When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied).
The thread to which the message is posted must have created a message queue, or else the call to
PostThreadMessage fails. Use the following method to handle this situation.
Create an event object, then create the thread.
Use the WaitForSingleObject function to wait for the event to be set to the signaled state before calling
PostThreadMessage .
In the thread to which the message will be posted, call PeekMessage as shown here to force the system to
create the message queue.
PeekMessage(&msg, NULL, WM_USER, WM_USER, PM_NOREMOVE)
Set the event, to indicate that the thread is ready to receive posted messages.
The thread to which the message is posted retrieves the message by calling the GetMessage or PeekMessage
function. The hwnd member of the returned MSG structure is NULL .
Messages sent by PostThreadMessage are not associated with a window. As a general rule, messages that are
not associated with a window cannot be dispatched by the DispatchMessage function. Therefore, if the recipient
thread is in a modal loop (as used by MessageBox or DialogBox), the messages will be lost. To intercept thread
messages while in a modal loop, use a thread-specific hook.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
There is a limit of 10,000 posted messages per message queue. This limit should be sufficiently large. If your
application exceeds the limit, it should be redesigned to avoid consuming so many system resources. To adjust
this limit, modify the following registry key.
HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
Windows NT
CurrentVersion
Windows
USERPostMessageLimit
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetCurrentThreadId
GetMessage
GetWindowThreadProcessId
MSG
Messages and Message Queues
Other Resources
PeekMessage
PostMessage
Reference
Sleep
WaitForSingleObject
PROPENUMPROCA callback function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
An application-defined callback function used with the EnumProps function. The function receives property
entries from a window's property list. The PROPENUMPROC type defines a pointer to this callback function.
PropEnumProc is a placeholder for the application-defined function name.
Syntax
PROPENUMPROCA Propenumproca;
BOOL Propenumproca(
HWND Arg1,
LPCSTR Arg2,
HANDLE Arg3
)
{...}
Parameters
Arg1
Type: HWND
A handle to the window whose property list is being enumerated.
Arg2
Type: LPCTSTR
The string component of a property list entry. This is the string that was specified, along with a data handle,
when the property was added to the window's property list via a call to the SetProp function.
Arg3
Type: HANDLE
A handle to the data. This handle is the data component of a property list entry.
Return value
Type: BOOL
Return TRUE to continue the property list enumeration.
Return FALSE to stop the property list enumeration.
Remarks
The following restrictions apply to this callback function:
The callback function can call the RemoveProp function. However, RemoveProp can remove only the
property passed to the callback function through the callback function's parameters.
The callback function should not attempt to add properties.
NOTE
The winuser.h header defines PROPENUMPROC 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
EnumProps
Reference
RemoveProp
SetProp
Window Properties
PROPENUMPROCEXA callback function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Application-defined callback function used with the EnumPropsEx function. The function receives property
entries from a window's property list. The PROPENUMPROCEX type defines a pointer to this callback function.
PropEnumProcEx is a placeholder for the application-defined function name.
Syntax
PROPENUMPROCEXA Propenumprocexa;
BOOL Propenumprocexa(
HWND Arg1,
LPSTR Arg2,
HANDLE Arg3,
ULONG_PTR Arg4
)
{...}
Parameters
Arg1
Type: HWND
A handle to the window whose property list is being enumerated.
Arg2
Type: LPTSTR
The string component of a property list entry. This is the string that was specified, along with a data handle,
when the property was added to the window's property list via a call to the SetProp function.
Arg3
Type: HANDLE
A handle to the data. This handle is the data component of a property list entry.
Arg4
Type: ULONG_PTR
Application-defined data. This is the value that was specified as the lParam parameter of the call to
EnumPropsEx that initiated the enumeration.
Return value
Type: BOOL
Return TRUE to continue the property list enumeration.
Return FALSE to stop the property list enumeration.
Remarks
The following restrictions apply to this callback function:
The callback function can call the RemoveProp function. However, RemoveProp can remove only the
property passed to the callback function through the callback function's parameters.
The callback function should not attempt to add properties.
NOTE
The winuser.h header defines PROPENUMPROCEX 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
EnumPropsEx
Reference
RemoveProp
SetProp
Window Properties
PROPENUMPROCEXW callback function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Application-defined callback function used with the EnumPropsEx function. The function receives property
entries from a window's property list. The PROPENUMPROCEX type defines a pointer to this callback function.
PropEnumProcEx is a placeholder for the application-defined function name.
Syntax
PROPENUMPROCEXW Propenumprocexw;
BOOL Propenumprocexw(
HWND Arg1,
LPWSTR Arg2,
HANDLE Arg3,
ULONG_PTR Arg4
)
{...}
Parameters
Arg1
Type: HWND
A handle to the window whose property list is being enumerated.
Arg2
Type: LPTSTR
The string component of a property list entry. This is the string that was specified, along with a data handle,
when the property was added to the window's property list via a call to the SetProp function.
Arg3
Type: HANDLE
A handle to the data. This handle is the data component of a property list entry.
Arg4
Type: ULONG_PTR
Application-defined data. This is the value that was specified as the lParam parameter of the call to
EnumPropsEx that initiated the enumeration.
Return value
Type: BOOL
Return TRUE to continue the property list enumeration.
Return FALSE to stop the property list enumeration.
Remarks
The following restrictions apply to this callback function:
The callback function can call the RemoveProp function. However, RemoveProp can remove only the
property passed to the callback function through the callback function's parameters.
The callback function should not attempt to add properties.
NOTE
The winuser.h header defines PROPENUMPROCEX 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
EnumPropsEx
Reference
RemoveProp
SetProp
Window Properties
PROPENUMPROCW callback function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
An application-defined callback function used with the EnumProps function. The function receives property
entries from a window's property list. The PROPENUMPROC type defines a pointer to this callback function.
PropEnumProc is a placeholder for the application-defined function name.
Syntax
PROPENUMPROCW Propenumprocw;
BOOL Propenumprocw(
HWND Arg1,
LPCWSTR Arg2,
HANDLE Arg3
)
{...}
Parameters
Arg1
Type: HWND
A handle to the window whose property list is being enumerated.
Arg2
Type: LPCTSTR
The string component of a property list entry. This is the string that was specified, along with a data handle,
when the property was added to the window's property list via a call to the SetProp function.
Arg3
Type: HANDLE
A handle to the data. This handle is the data component of a property list entry.
Return value
Type: BOOL
Return TRUE to continue the property list enumeration.
Return FALSE to stop the property list enumeration.
Remarks
The following restrictions apply to this callback function:
The callback function can call the RemoveProp function. However, RemoveProp can remove only the
property passed to the callback function through the callback function's parameters.
The callback function should not attempt to add properties.
NOTE
The winuser.h header defines PROPENUMPROC 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
EnumProps
Reference
RemoveProp
SetProp
Window Properties
RealChildWindowFromPoint function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Retrieves a handle to the child window at the specified point. The search is restricted to immediate child
windows; grandchildren and deeper descendant windows are not searched.
Syntax
HWND RealChildWindowFromPoint(
HWND hwndParent,
POINT ptParentClientCoords
);
Parameters
hwndParent
Type: HWND
A handle to the window whose child is to be retrieved.
ptParentClientCoords
Type: POINT
A POINT structure that defines the client coordinates of the point to be checked.
Return value
Type: HWND
The return value is a handle to the child window that contains the specified point.
Remarks
RealChildWindowFromPoint treats HTTRANSPARENT areas of a standard control differently from other
areas of the control; it returns the child window behind a transparent part of a control. In contrast,
ChildWindowFromPoint treats HTTRANSPARENT areas of a control the same as other areas. For example, if the
point is in a transparent area of a groupbox, RealChildWindowFromPoint returns the child window behind a
groupbox, whereas ChildWindowFromPoint returns the groupbox. However, both APIs return a static field,
even though it, too, returns HTTRANSPARENT .
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
ChildWindowFromPoint
Conceptual
Other Resources
POINT
Reference
Windows
RealGetWindowClassW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
UINT RealGetWindowClassW(
HWND hwnd,
LPWSTR ptszClassName,
UINT cchClassNameMax
);
Parameters
hwnd
Type: HWND
A handle to the window whose type will be retrieved.
ptszClassName
Type: LPTSTR
A pointer to a string that receives the window type.
cchClassNameMax
Type: UINT
The length, in characters, of the buffer pointed to by the pszType parameter.
Return value
Type: UINT
If the function succeeds, the return value is the number of characters copied to the specified buffer.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Windows Overview
RegisterClassA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.
Note The RegisterClass function has been superseded by the RegisterClassEx function. You can still use RegisterClass ,
however, if you do not need to set the class small icon.
Syntax
ATOM RegisterClassA(
const WNDCLASSA *lpWndClass
);
Parameters
lpWndClass
Return value
Type: ATOM
If the function succeeds, the return value is a class atom that uniquely identifies the class being registered. This
atom can only be used by the CreateWindow, CreateWindowEx, GetClassInfo, GetClassInfoEx, FindWindow,
FindWindowEx, and UnregisterClass functions and the IActiveIMMap::FilterClientWindows method.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you register the window class by using RegisterClassA , the application tells the system that the windows of
the created class expect messages with text or character parameters to use the ANSI character set; if you register
it by using RegisterClassW , the application requests that the system pass text parameters of messages as
Unicode. The IsWindowUnicode function enables applications to query the nature of each window. For more
information on ANSI and Unicode functions, see Conventions for Function Prototypes.
All window classes that an application registers are unregistered when it terminates.
No window classes registered by a DLL are unregistered when the DLL is unloaded. A DLL must explicitly
unregister its classes when it is unloaded.
Examples
For an example, see Associating a Window Procedure with a Window Class.
NOTE
The winuser.h header defines RegisterClass 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
CreateWindow
CreateWindowEx
FindWindow
FindWindowEx
GetClassInfo
GetClassInfoEx
GetClassName
Reference
RegisterClassEx
UnregisterClass
WNDCLASS
Window Classes
WindowProc
RegisterClassExA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.
Syntax
ATOM RegisterClassExA(
const WNDCLASSEXA *Arg1
);
Parameters
Arg1
Return value
Type: ATOM
If the function succeeds, the return value is a class atom that uniquely identifies the class being registered. This
atom can only be used by the CreateWindow, CreateWindowEx, GetClassInfo, GetClassInfoEx, FindWindow,
FindWindowEx, and UnregisterClass functions and the IActiveIMMap::FilterClientWindows method.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you register the window class by using RegisterClassExA , the application tells the system that the windows
of the created class expect messages with text or character parameters to use the ANSI character set; if you
register it by using RegisterClassExW , the application requests that the system pass text parameters of
messages as Unicode. The IsWindowUnicode function enables applications to query the nature of each window.
For more information on ANSI and Unicode functions, see Conventions for Function Prototypes.
All window classes that an application registers are unregistered when it terminates.
No window classes registered by a DLL are unregistered when the DLL is unloaded. A DLL must explicitly
unregister its classes when it is unloaded.
Examples
For an example, see Using Window Classes.
NOTE
The winuser.h header defines RegisterClassEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
CreateWindow
CreateWindowEx
FindWindow
FindWindowEx
GetClassInfo
GetClassInfoEx
GetClassName
Reference
RegisterClass
UnregisterClass
WNDCLASSEX
Window Classes
WindowProc
RegisterClassExW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.
Syntax
ATOM RegisterClassExW(
const WNDCLASSEXW *Arg1
);
Parameters
Arg1
Return value
Type: ATOM
If the function succeeds, the return value is a class atom that uniquely identifies the class being registered. This
atom can only be used by the CreateWindow, CreateWindowEx, GetClassInfo, GetClassInfoEx, FindWindow,
FindWindowEx, and UnregisterClass functions and the IActiveIMMap::FilterClientWindows method.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you register the window class by using RegisterClassExA , the application tells the system that the windows
of the created class expect messages with text or character parameters to use the ANSI character set; if you
register it by using RegisterClassExW , the application requests that the system pass text parameters of
messages as Unicode. The IsWindowUnicode function enables applications to query the nature of each window.
For more information on ANSI and Unicode functions, see Conventions for Function Prototypes.
All window classes that an application registers are unregistered when it terminates.
No window classes registered by a DLL are unregistered when the DLL is unloaded. A DLL must explicitly
unregister its classes when it is unloaded.
Examples
For an example, see Using Window Classes.
NOTE
The winuser.h header defines RegisterClassEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
CreateWindow
CreateWindowEx
FindWindow
FindWindowEx
GetClassInfo
GetClassInfoEx
GetClassName
Reference
RegisterClass
UnregisterClass
WNDCLASSEX
Window Classes
WindowProc
RegisterClassW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.
Note The RegisterClass function has been superseded by the RegisterClassEx function. You can still use RegisterClass ,
however, if you do not need to set the class small icon.
Syntax
ATOM RegisterClassW(
const WNDCLASSW *lpWndClass
);
Parameters
lpWndClass
Return value
Type: ATOM
If the function succeeds, the return value is a class atom that uniquely identifies the class being registered. This
atom can only be used by the CreateWindow, CreateWindowEx, GetClassInfo, GetClassInfoEx, FindWindow,
FindWindowEx, and UnregisterClass functions and the IActiveIMMap::FilterClientWindows method.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you register the window class by using RegisterClassA , the application tells the system that the windows of
the created class expect messages with text or character parameters to use the ANSI character set; if you register
it by using RegisterClassW , the application requests that the system pass text parameters of messages as
Unicode. The IsWindowUnicode function enables applications to query the nature of each window. For more
information on ANSI and Unicode functions, see Conventions for Function Prototypes.
All window classes that an application registers are unregistered when it terminates.
No window classes registered by a DLL are unregistered when the DLL is unloaded. A DLL must explicitly
unregister its classes when it is unloaded.
Examples
For an example, see Associating a Window Procedure with a Window Class.
NOTE
The winuser.h header defines RegisterClass 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
CreateWindow
CreateWindowEx
FindWindow
FindWindowEx
GetClassInfo
GetClassInfoEx
GetClassName
Reference
RegisterClassEx
UnregisterClass
WNDCLASS
Window Classes
WindowProc
RegisterShellHookWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
[This function is not intended for general use. It may be altered or unavailable in subsequent versions of
Windows.]
Registers a specified Shell window to receive certain messages for events or notifications that are useful to Shell
applications.
The event messages received are only those sent to the Shell window associated with the specified window's
desktop. Many of the messages are the same as those that can be received after calling the SetWindowsHookEx
function and specifying WH_SHELL for the hook type. The difference with RegisterShellHookWindow is that
the messages are received through the specified window's WindowProc and not through a call back procedure.
Syntax
BOOL RegisterShellHookWindow(
HWND hwnd
);
Parameters
hwnd
Type: HWND
A handle to the window to register for Shell hook messages.
Return value
Type: BOOL
TRUE if the function succeeds; otherwise, FALSE .
Remarks
As with normal window messages, the second parameter of the window procedure identifies the message as a
WM_SHELLHOOKMESSAGE . However, for these Shell hook messages, the message value is not a pre-defined
constant like other message IDs such as WM_COMMAND. The value must be obtained dynamically using a call
to RegisterWindowMessage as shown here:
RegisterWindowMessage(TEXT("SHELLHOOK"));
This precludes handling these messages using a traditional switch statement which requires ID values that are
known at compile time. For handling Shell hook messages, the normal practice is to code an If statement in the
default section of your switch statement and then handle the message if the value of the message ID is the same
as the value obtained from the RegisterWindowMessage call.
The following table describes the wParam and lParam parameter values passed to the window procedure for the
Shell hook messages.
W PA RA M L PA RA M
HSHELL_GETMINRECT A pointer to a SHELLHOOKINFO structure.
This function was not included in the SDK headers and libraries until Windows XP with Service Pack 1 (SP1) and
Windows Server 2003. If you do not have a header file and import library for this function, you can call the
function using LoadLibrary and GetProcAddress.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
DeregisterShellHookWindow
Other Resources
Reference
SetWindowsHookEx
ShellProc
Using Messages and Message Queues
WinEvents
WindowProc
Windows
RegisterWindowMessageA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Defines a new window message that is guaranteed to be unique throughout the system. The message value can
be used when sending or posting messages.
Syntax
UINT RegisterWindowMessageA(
LPCSTR lpString
);
Parameters
lpString
Type: LPCTSTR
The message to be registered.
Return value
Type: UINT
If the message is successfully registered, the return value is a message identifier in the range 0xC000 through
0xFFFF.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The RegisterWindowMessage function is typically used to register messages for communicating between two
cooperating applications.
If two different applications register the same message string, the applications return the same message value.
The message remains registered until the session ends.
Only use RegisterWindowMessage when more than one application must process the same message. For
sending private messages within a window class, an application can use any integer in the range WM_USER
through 0x7FFF. (Messages in this range are private to a window class, not to an application. For example,
predefined control classes such as BUTTON , EDIT , LISTBOX , and COMBOBOX may use values in this range.)
Examples
For an example, see Finding Text.
NOTE
The winuser.h header defines RegisterWindowMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Messages and Message Queues
PostMessage
Reference
SendMessage
RegisterWindowMessageW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Defines a new window message that is guaranteed to be unique throughout the system. The message value can
be used when sending or posting messages.
Syntax
UINT RegisterWindowMessageW(
LPCWSTR lpString
);
Parameters
lpString
Type: LPCTSTR
The message to be registered.
Return value
Type: UINT
If the message is successfully registered, the return value is a message identifier in the range 0xC000 through
0xFFFF.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The RegisterWindowMessage function is typically used to register messages for communicating between two
cooperating applications.
If two different applications register the same message string, the applications return the same message value.
The message remains registered until the session ends.
Only use RegisterWindowMessage when more than one application must process the same message. For
sending private messages within a window class, an application can use any integer in the range WM_USER
through 0x7FFF. (Messages in this range are private to a window class, not to an application. For example,
predefined control classes such as BUTTON , EDIT , LISTBOX , and COMBOBOX may use values in this range.)
Examples
For an example, see Finding Text.
NOTE
The winuser.h header defines RegisterWindowMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Messages and Message Queues
PostMessage
Reference
SendMessage
RemovePropA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Removes an entry from the property list of the specified window. The specified character string identifies the
entry to be removed.
Syntax
HANDLE RemovePropA(
HWND hWnd,
LPCSTR lpString
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list is to be changed.
lpString
Type: LPCTSTR
A null-terminated character string or an atom that identifies a string. If this parameter is an atom, it must have
been created using the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word
of lpString; the high-order word must be zero.
Return value
Type: HANDLE
The return value identifies the specified data. If the data cannot be found in the specified property list, the return
value is NULL .
Remarks
The return value is the hData value that was passed to SetProp; it is an application-defined value. Note, this
function only destroys the association between the data and the window. If appropriate, the application must
free the data handles associated with entries removed from a property list. The application can remove only
those properties it has added. It must not remove properties added by other applications or by the system itself.
The RemoveProp function returns the data handle associated with the string so that the application can free
the data associated with the handle.
Starting with Windows Vista, RemoveProp is subject to the restrictions of User Interface Privilege Isolation
(UIPI). A process can only call this function on a window belonging to a process of lesser or equal integrity level.
When UIPI blocks property changes, GetLastError will return 5 .
Examples
For an example, see Deleting a Window Property.
NOTE
The winuser.h header defines RemoveProp 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AddAtom
Conceptual
GetProp
Reference
SetProp
Window Properties
RemovePropW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Removes an entry from the property list of the specified window. The specified character string identifies the
entry to be removed.
Syntax
HANDLE RemovePropW(
HWND hWnd,
LPCWSTR lpString
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list is to be changed.
lpString
Type: LPCTSTR
A null-terminated character string or an atom that identifies a string. If this parameter is an atom, it must have
been created using the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word
of lpString; the high-order word must be zero.
Return value
Type: HANDLE
The return value identifies the specified data. If the data cannot be found in the specified property list, the return
value is NULL .
Remarks
The return value is the hData value that was passed to SetProp; it is an application-defined value. Note, this
function only destroys the association between the data and the window. If appropriate, the application must
free the data handles associated with entries removed from a property list. The application can remove only
those properties it has added. It must not remove properties added by other applications or by the system itself.
The RemoveProp function returns the data handle associated with the string so that the application can free
the data associated with the handle.
Starting with Windows Vista, RemoveProp is subject to the restrictions of User Interface Privilege Isolation
(UIPI). A process can only call this function on a window belonging to a process of lesser or equal integrity level.
When UIPI blocks property changes, GetLastError will return 5 .
Examples
For an example, see Deleting a Window Property.
NOTE
The winuser.h header defines RemoveProp 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AddAtom
Conceptual
GetProp
Reference
SetProp
Window Properties
ReplyMessage function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL ReplyMessage(
LRESULT lResult
);
Parameters
lResult
Type: LRESULT
The result of the message processing. The possible values are based on the message sent.
Return value
Type: BOOL
If the calling thread was processing a message sent from another thread or process, the return value is nonzero.
If the calling thread was not processing a message sent from another thread or process, the return value is zero.
Remarks
By calling this function, the window procedure that receives the message allows the thread that called
SendMessage to continue to run as though the thread receiving the message had returned control. The thread
that calls the ReplyMessage function also continues to run.
If the message was not sent through SendMessage or if the message was sent by the same thread,
ReplyMessage has no effect.
Examples
For an example, see Sending a Message.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Conceptual
InSendMessage
Messages and Message Queues
Reference
SendMessage
SENDASYNCPROC callback function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
An application-defined callback function used with the SendMessageCallback function. The system passes the
message to the callback function after passing the message to the destination window procedure. The
SENDASYNCPROC type defines a pointer to this callback function. SendAsyncProc is a placeholder for the
application-defined function name.
Syntax
SENDASYNCPROC Sendasyncproc;
void Sendasyncproc(
HWND Arg1,
UINT Arg2,
ULONG_PTR Arg3,
LRESULT Arg4
)
{...}
Parameters
Arg1
Type: HWND
A handle to the window whose window procedure received the message.
If the SendMessageCallback function was called with its hwnd parameter set to HWND_BROADCAST , the
system calls the SendAsyncProc function once for each top-level window.
Arg2
Type: UINT
The message.
Arg3
Type: ULONG_PTR
An application-defined value sent from the SendMessageCallback function.
Arg4
Type: LRESULT
The result of the message processing. This value depends on the message.
Return value
None
Remarks
You install a SendAsyncProc application-defined callback function by passing a SENDASYNCPROC pointer to
the SendMessageCallback function.
The callback function is only called when the thread that called SendMessageCallback calls GetMessage,
PeekMessage, or WaitMessage.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GetMessage
Messages and Message Queues
PeekMessage
Reference
SendMessageCallback
WaitMessage
SendMessage function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sends the specified message to a window or windows. The SendMessage function calls the window procedure
for the specified window and does not return until the window procedure has processed the message.
To send a message and return immediately, use the SendMessageCallback or SendNotifyMessage function. To
post a message to a thread's message queue and return immediately, use the PostMessage or
PostThreadMessage function.
Syntax
LRESULT SendMessage(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message. If this parameter is
HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the system, including
disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent
to child windows.
Message sending is subject to UIPI. The thread of a process can send messages only to message queues of
threads in processes of lesser or equal integrity level.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: LRESULT
The return value specifies the result of the message processing; it depends on the message sent.
Remarks
When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied).
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
If the specified window was created by the calling thread, the window procedure is called immediately as a
subroutine. If the specified window was created by a different thread, the system switches to that thread and
calls the appropriate window procedure. Messages sent between threads are processed only when the receiving
thread executes message retrieval code. The sending thread is blocked until the receiving thread processes the
message. However, the sending thread will process incoming nonqueued messages while waiting for its
message to be processed. To prevent this, use SendMessageTimeout with SMTO_BLOCK set. For more
information on nonqueued messages, see Nonqueued Messages.
An accessibility application can use SendMessage to send WM_APPCOMMAND messages to the shell to
launch applications. This functionality is not guaranteed to work for other types of applications.
Examples
For an example, see Displaying Keyboard Input.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
InSendMessage
Messages and Message Queues
PostMessage
PostThreadMessage
Reference
RegisterWindowMessage
SendDlgItemMessage
SendMessageCallback
SendMessageTimeout
SendNotifyMessage
SendMessageA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sends the specified message to a window or windows. The SendMessage function calls the window procedure
for the specified window and does not return until the window procedure has processed the message.
To send a message and return immediately, use the SendMessageCallback or SendNotifyMessage function. To
post a message to a thread's message queue and return immediately, use the PostMessage or
PostThreadMessage function.
Syntax
LRESULT SendMessageA(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message. If this parameter is
HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the system, including
disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent
to child windows.
Message sending is subject to UIPI. The thread of a process can send messages only to message queues of
threads in processes of lesser or equal integrity level.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: LRESULT
The return value specifies the result of the message processing; it depends on the message sent.
Remarks
When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied).
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
If the specified window was created by the calling thread, the window procedure is called immediately as a
subroutine. If the specified window was created by a different thread, the system switches to that thread and
calls the appropriate window procedure. Messages sent between threads are processed only when the receiving
thread executes message retrieval code. The sending thread is blocked until the receiving thread processes the
message. However, the sending thread will process incoming nonqueued messages while waiting for its
message to be processed. To prevent this, use SendMessageTimeout with SMTO_BLOCK set. For more
information on nonqueued messages, see Nonqueued Messages.
An accessibility application can use SendMessage to send WM_APPCOMMAND messages to the shell to
launch applications. This functionality is not guaranteed to work for other types of applications.
Examples
For an example, see Displaying Keyboard Input.
NOTE
The winuser.h header defines SendMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Sends the specified message to a window or windows. It calls the window procedure for the specified window
and returns immediately if the window belongs to another thread. After the window procedure processes the
message, the system calls the specified callback function, passing the result of the message processing and an
application-defined value to the callback function.
Syntax
BOOL SendMessageCallbackA(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam,
SENDASYNCPROC lpResultCallBack,
ULONG_PTR dwData
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message. If this parameter is
HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the system, including
disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent
to child windows.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
lpResultCallBack
Type: SENDASYNCPROC
A pointer to a callback function that the system calls after the window procedure processes the message. For
more information, see SendAsyncProc.
If hWnd is HWND_BROADCAST ((HWND)0xffff), the system calls the SendAsyncProc callback function once
for each top-level window.
dwData
Type: ULONG_PTR
An application-defined value to be sent to the callback function pointed to by the lpCallBack parameter.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If the target window belongs to the same thread as the caller, then the window procedure is called
synchronously, and the callback function is called immediately after the window procedure returns. If the target
window belongs to a different thread from the caller, then the callback function is called only when the thread
that called SendMessageCallback also calls GetMessage, PeekMessage, or WaitMessage.
If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage,
SendNotifyMessage, and SendMessageCallback ), its message parameters cannot include pointers. Otherwise,
the operation will fail. The functions will return before the receiving thread has had a chance to process the
message and the sender will free the memory before it is used.
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
NOTE
The winuser.h header defines SendMessageCallback 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Conceptual
Messages and Message Queues
PostMessage
Reference
RegisterWindowMessage
SendAsyncProc
SendMessageCallback
SendNotifyMessage
SendMessageCallbackW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sends the specified message to a window or windows. It calls the window procedure for the specified window
and returns immediately if the window belongs to another thread. After the window procedure processes the
message, the system calls the specified callback function, passing the result of the message processing and an
application-defined value to the callback function.
Syntax
BOOL SendMessageCallbackW(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam,
SENDASYNCPROC lpResultCallBack,
ULONG_PTR dwData
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message. If this parameter is
HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the system, including
disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent
to child windows.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
lpResultCallBack
Type: SENDASYNCPROC
A pointer to a callback function that the system calls after the window procedure processes the message. For
more information, see SendAsyncProc.
If hWnd is HWND_BROADCAST ((HWND)0xffff), the system calls the SendAsyncProc callback function once
for each top-level window.
dwData
Type: ULONG_PTR
An application-defined value to be sent to the callback function pointed to by the lpCallBack parameter.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If the target window belongs to the same thread as the caller, then the window procedure is called
synchronously, and the callback function is called immediately after the window procedure returns. If the target
window belongs to a different thread from the caller, then the callback function is called only when the thread
that called SendMessageCallback also calls GetMessage, PeekMessage, or WaitMessage.
If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage,
SendNotifyMessage, and SendMessageCallback ), its message parameters cannot include pointers. Otherwise,
the operation will fail. The functions will return before the receiving thread has had a chance to process the
message and the sender will free the memory before it is used.
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
NOTE
The winuser.h header defines SendMessageCallback 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Conceptual
Messages and Message Queues
PostMessage
Reference
RegisterWindowMessage
SendAsyncProc
SendMessageCallback
SendNotifyMessage
SendMessageTimeoutA function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Syntax
LRESULT SendMessageTimeoutA(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam,
UINT fuFlags,
UINT uTimeout,
PDWORD_PTR lpdwResult
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message.
If this parameter is HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the
system, including disabled or invisible unowned windows. The function does not return until each window has
timed out. Therefore, the total wait time can be up to the value of uTimeout multiplied by the number of top-
level windows.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Any additional message-specific information.
lParam
Type: LPARAM
Any additional message-specific information.
fuFlags
Type: UINT
The behavior of this function. This parameter can be one or more of the following values.
VA L UE M EA N IN G
uTimeout
Type: UINT
The duration of the time-out period, in milliseconds. If the message is a broadcast message, each window can
use the full time-out period. For example, if you specify a five second time-out period and there are three top-
level windows that fail to process the message, you could have up to a 15 second delay.
lpdwResult
Type: PDWORD_PTR
The result of the message processing. The value of this parameter depends on the message that is specified.
Return value
Type: LRESULT
If the function succeeds, the return value is nonzero. SendMessageTimeout does not provide information
about individual windows timing out if HWND_BROADCAST is used.
If the function fails or times out, the return value is 0. To get extended error information, call GetLastError. If
GetLastError returns ERROR_TIMEOUT , then the function timed out.
Windows 2000: If GetLastError returns 0, then the function timed out.
Remarks
The function calls the window procedure for the specified window and, if the specified window belongs to a
different thread, does not return until the window procedure has processed the message or the specified time-
out period has elapsed. If the window receiving the message belongs to the same queue as the current thread,
the window procedure is called directly—the time-out value is ignored.
This function considers that a thread is not responding if it has not called GetMessage or a similar function
within five seconds.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
NOTE
The winuser.h header defines SendMessageTimeout 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
InSendMessage
Messages and Message Queues
PostMessage
Reference
SendDlgItemMessage
SendMessage
SendMessageCallback
SendNotifyMessage
SendMessageTimeoutW function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Syntax
LRESULT SendMessageTimeoutW(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam,
UINT fuFlags,
UINT uTimeout,
PDWORD_PTR lpdwResult
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message.
If this parameter is HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the
system, including disabled or invisible unowned windows. The function does not return until each window has
timed out. Therefore, the total wait time can be up to the value of uTimeout multiplied by the number of top-
level windows.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Any additional message-specific information.
lParam
Type: LPARAM
Any additional message-specific information.
fuFlags
Type: UINT
The behavior of this function. This parameter can be one or more of the following values.
VA L UE M EA N IN G
uTimeout
Type: UINT
The duration of the time-out period, in milliseconds. If the message is a broadcast message, each window can
use the full time-out period. For example, if you specify a five second time-out period and there are three top-
level windows that fail to process the message, you could have up to a 15 second delay.
lpdwResult
Type: PDWORD_PTR
The result of the message processing. The value of this parameter depends on the message that is specified.
Return value
Type: LRESULT
If the function succeeds, the return value is nonzero. SendMessageTimeout does not provide information
about individual windows timing out if HWND_BROADCAST is used.
If the function fails or times out, the return value is 0. To get extended error information, call GetLastError. If
GetLastError returns ERROR_TIMEOUT , then the function timed out.
Windows 2000: If GetLastError returns 0, then the function timed out.
Remarks
The function calls the window procedure for the specified window and, if the specified window belongs to a
different thread, does not return until the window procedure has processed the message or the specified time-
out period has elapsed. If the window receiving the message belongs to the same queue as the current thread,
the window procedure is called directly—the time-out value is ignored.
This function considers that a thread is not responding if it has not called GetMessage or a similar function
within five seconds.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
NOTE
The winuser.h header defines SendMessageTimeout 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
InSendMessage
Messages and Message Queues
PostMessage
Reference
SendDlgItemMessage
SendMessage
SendMessageCallback
SendNotifyMessage
SendMessageW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sends the specified message to a window or windows. The SendMessage function calls the window procedure
for the specified window and does not return until the window procedure has processed the message.
To send a message and return immediately, use the SendMessageCallback or SendNotifyMessage function. To
post a message to a thread's message queue and return immediately, use the PostMessage or
PostThreadMessage function.
Syntax
LRESULT SendMessageW(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message. If this parameter is
HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the system, including
disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent
to child windows.
Message sending is subject to UIPI. The thread of a process can send messages only to message queues of
threads in processes of lesser or equal integrity level.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: LRESULT
The return value specifies the result of the message processing; it depends on the message sent.
Remarks
When a message is blocked by UIPI the last error, retrieved with GetLastError, is set to 5 (access denied).
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
If the specified window was created by the calling thread, the window procedure is called immediately as a
subroutine. If the specified window was created by a different thread, the system switches to that thread and
calls the appropriate window procedure. Messages sent between threads are processed only when the receiving
thread executes message retrieval code. The sending thread is blocked until the receiving thread processes the
message. However, the sending thread will process incoming nonqueued messages while waiting for its
message to be processed. To prevent this, use SendMessageTimeout with SMTO_BLOCK set. For more
information on nonqueued messages, see Nonqueued Messages.
An accessibility application can use SendMessage to send WM_APPCOMMAND messages to the shell to
launch applications. This functionality is not guaranteed to work for other types of applications.
Examples
For an example, see Displaying Keyboard Input.
NOTE
The winuser.h header defines SendMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Sends the specified message to a window or windows. If the window was created by the calling thread,
SendNotifyMessage calls the window procedure for the window and does not return until the window
procedure has processed the message. If the window was created by a different thread, SendNotifyMessage
passes the message to the window procedure and returns immediately; it does not wait for the window
procedure to finish processing the message.
Syntax
BOOL SendNotifyMessageA(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message. If this parameter is
HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the system, including
disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent
to child windows.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage,
SendNotifyMessage , and SendMessageCallback), its message parameters cannot include pointers. Otherwise,
the operation will fail. The functions will return before the receiving thread has had a chance to process the
message and the sender will free the memory before it is used.
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
NOTE
The winuser.h header defines SendNotifyMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Messages and Message Queues
PostMessage
PostThreadMessage
Reference
RegisterWindowMessage
SendMessage
SendMessageCallback
SendNotifyMessage
SendNotifyMessageW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sends the specified message to a window or windows. If the window was created by the calling thread,
SendNotifyMessage calls the window procedure for the window and does not return until the window
procedure has processed the message. If the window was created by a different thread, SendNotifyMessage
passes the message to the window procedure and returns immediately; it does not wait for the window
procedure to finish processing the message.
Syntax
BOOL SendNotifyMessageW(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd
Type: HWND
A handle to the window whose window procedure will receive the message. If this parameter is
HWND_BROADCAST ((HWND)0xffff), the message is sent to all top-level windows in the system, including
disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent
to child windows.
Msg
Type: UINT
The message to be sent.
For lists of the system-provided messages, see System-Defined Messages.
wParam
Type: WPARAM
Additional message-specific information.
lParam
Type: LPARAM
Additional message-specific information.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage,
SendNotifyMessage , and SendMessageCallback), its message parameters cannot include pointers. Otherwise,
the operation will fail. The functions will return before the receiving thread has had a chance to process the
message and the sender will free the memory before it is used.
Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage
function to obtain a unique message for inter-application communication.
The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
messages (those >= WM_USER ) to another process, you must do custom marshalling.
NOTE
The winuser.h header defines SendNotifyMessage 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Messages and Message Queues
PostMessage
PostThreadMessage
Reference
RegisterWindowMessage
SendMessage
SendMessageCallback
SendNotifyMessage
SetClassLongA function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Replaces the specified 32-bit (long ) value at the specified offset into the extra class memory or the
WNDCLASSEX structure for the class to which the specified window belongs.
Note This function has been superseded by the SetClassLongPtr function. To write code that is compatible with both 32-bit
and 64-bit versions of Windows, use SetClassLongPtr .
Syntax
DWORD SetClassLongA(
HWND hWnd,
int nIndex,
LONG dwNewLong
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The value to be replaced. To set a 32-bit value in the extra class memory, specify the positive, zero-based byte
offset of the value to be set. Valid values are in the range zero through the number of bytes of extra class
memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would
be an index to the third 32-bit integer. To set any other value from the WNDCLASSEX structure, specify one of
the following values.
VA L UE M EA N IN G
dwNewLong
Type: LONG
The replacement value.
Return value
Type: DWORD
If the function succeeds, the return value is the previous value of the specified 32-bit integer. If the value was not
previously set, the return value is zero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you use the SetClassLong function and the GCL_WNDPROC index to replace the window procedure, the
window procedure must conform to the guidelines specified in the description of the WindowProc callback
function.
Calling SetClassLong with the GCL_WNDPROC index creates a subclass of the window class that affects all
windows subsequently created with the class. An application can subclass a system class, but should not
subclass a window class created by another process.
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASSEX
structure used with the RegisterClassEx function.
Use the SetClassLong function with care. For example, it is possible to change the background color for a class
by using SetClassLong , but this change does not immediately repaint all windows belonging to the class.
Examples
For an example, see Displaying an Icon.
NOTE
The winuser.h header defines SetClassLong 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLong
Reference
RegisterClassEx
SetClassLongPtr
SetWindowLong
WNDCLASSEX
Window Classes
WindowProc
SetClassLongPtrA function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Replaces the specified value at the specified offset in the extra class memory or the WNDCLASSEX structure for
the class to which the specified window belongs.
Note To write code that is compatible with both 32-bit and 64-bit Windows, use SetClassLongPtr . When compiling for 32-
bit Windows, SetClassLongPtr is defined as a call to the SetClassLong function
Syntax
ULONG_PTR SetClassLongPtrA(
HWND hWnd,
int nIndex,
LONG_PTR dwNewLong
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The value to be replaced. To set a value in the extra class memory, specify the positive, zero-based byte offset of
the value to be set. Valid values are in the range zero through the number of bytes of extra class memory, minus
eight; for example, if you specified 24 or more bytes of extra class memory, a value of 16 would be an index to
the third integer. To set a value other than the WNDCLASSEX structure, specify one of the following values.
VA L UE M EA N IN G
dwNewLong
Type: LONG_PTR
The replacement value.
Return value
Type: ULONG_PTR
If the function succeeds, the return value is the previous value of the specified offset. If this was not previously
set, the return value is zero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you use the SetClassLongPtr function and the GCLP_WNDPROC index to replace the window procedure,
the window procedure must conform to the guidelines specified in the description of the WindowProc callback
function.
Calling SetClassLongPtr with the GCLP_WNDPROC index creates a subclass of the window class that affects
all windows subsequently created with the class. An application can subclass a system class, but should not
subclass a window class created by another process.
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASSEX
structure used with the RegisterClassEx function.
Use the SetClassLongPtr function with care. For example, it is possible to change the background color for a
class by using SetClassLongPtr , but this change does not immediately repaint all windows belonging to the
class.
NOTE
The winuser.h header defines SetClassLongPtr 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLongPtr
Reference
RegisterClassEx
SetWindowLongPtr
WNDCLASSEX
Window Classes
WindowProc
SetClassLongPtrW function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Replaces the specified value at the specified offset in the extra class memory or the WNDCLASSEX structure for
the class to which the specified window belongs.
Note To write code that is compatible with both 32-bit and 64-bit Windows, use SetClassLongPtr . When compiling for 32-
bit Windows, SetClassLongPtr is defined as a call to the SetClassLong function
Syntax
ULONG_PTR SetClassLongPtrW(
HWND hWnd,
int nIndex,
LONG_PTR dwNewLong
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The value to be replaced. To set a value in the extra class memory, specify the positive, zero-based byte offset of
the value to be set. Valid values are in the range zero through the number of bytes of extra class memory, minus
eight; for example, if you specified 24 or more bytes of extra class memory, a value of 16 would be an index to
the third integer. To set a value other than the WNDCLASSEX structure, specify one of the following values.
VA L UE M EA N IN G
dwNewLong
Type: LONG_PTR
The replacement value.
Return value
Type: ULONG_PTR
If the function succeeds, the return value is the previous value of the specified offset. If this was not previously
set, the return value is zero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you use the SetClassLongPtr function and the GCLP_WNDPROC index to replace the window procedure,
the window procedure must conform to the guidelines specified in the description of the WindowProc callback
function.
Calling SetClassLongPtr with the GCLP_WNDPROC index creates a subclass of the window class that affects
all windows subsequently created with the class. An application can subclass a system class, but should not
subclass a window class created by another process.
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASSEX
structure used with the RegisterClassEx function.
Use the SetClassLongPtr function with care. For example, it is possible to change the background color for a
class by using SetClassLongPtr , but this change does not immediately repaint all windows belonging to the
class.
NOTE
The winuser.h header defines SetClassLongPtr 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLongPtr
Reference
RegisterClassEx
SetWindowLongPtr
WNDCLASSEX
Window Classes
WindowProc
SetClassLongW function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Replaces the specified 32-bit (long ) value at the specified offset into the extra class memory or the
WNDCLASSEX structure for the class to which the specified window belongs.
Note This function has been superseded by the SetClassLongPtr function. To write code that is compatible with both 32-bit
and 64-bit versions of Windows, use SetClassLongPtr .
Syntax
DWORD SetClassLongW(
HWND hWnd,
int nIndex,
LONG dwNewLong
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The value to be replaced. To set a 32-bit value in the extra class memory, specify the positive, zero-based byte
offset of the value to be set. Valid values are in the range zero through the number of bytes of extra class
memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would
be an index to the third 32-bit integer. To set any other value from the WNDCLASSEX structure, specify one of
the following values.
VA L UE M EA N IN G
dwNewLong
Type: LONG
The replacement value.
Return value
Type: DWORD
If the function succeeds, the return value is the previous value of the specified 32-bit integer. If the value was not
previously set, the return value is zero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If you use the SetClassLong function and the GCL_WNDPROC index to replace the window procedure, the
window procedure must conform to the guidelines specified in the description of the WindowProc callback
function.
Calling SetClassLong with the GCL_WNDPROC index creates a subclass of the window class that affects all
windows subsequently created with the class. An application can subclass a system class, but should not
subclass a window class created by another process.
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASSEX
structure used with the RegisterClassEx function.
Use the SetClassLong function with care. For example, it is possible to change the background color for a class
by using SetClassLong , but this change does not immediately repaint all windows belonging to the class.
Examples
For an example, see Displaying an Icon.
NOTE
The winuser.h header defines SetClassLong 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassLong
Reference
RegisterClassEx
SetClassLongPtr
SetWindowLong
WNDCLASSEX
Window Classes
WindowProc
SetClassWord function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Replaces the 16-bit (WORD ) value at the specified offset into the extra class memory for the window class to
which the specified window belongs.
Note This function is provided only for compatibility with 16-bit versions of Windows. Applications should use the
SetClassLong function.
Syntax
WORD SetClassWord(
HWND hWnd,
int nIndex,
WORD wNewWord
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The zero-based byte offset of the value to be replaced. Valid values are in the range zero through the number of
bytes of class memory minus two; for example, if you specified 10 or more bytes of extra class memory, a value
of 8 would be an index to the fifth 16-bit integer.
wNewWord
Type: WORD
The replacement value.
Return value
Type: WORD
If the function succeeds, the return value is the previous value of the specified 16-bit integer. If the value was not
previously set, the return value is zero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS
structure used with the RegisterClass function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetClassWord
Reference
RegisterClass
SetClassLong
WNDCLASS
Window Classes
SetCoalescableTimer function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Creates a timer with the specified time-out value and coalescing tolerance delay.
Syntax
UINT_PTR SetCoalescableTimer(
HWND hWnd,
UINT_PTR nIDEvent,
UINT uElapse,
TIMERPROC lpTimerFunc,
ULONG uToleranceDelay
);
Parameters
hWnd
Type: HWND
A handle to the window to be associated with the timer. This window must be owned by the calling thread. If a
NULL value for hWnd is passed in along with an nIDEvent of an existing timer, that timer will be replaced in the
same way that an existing non-NULL hWnd timer will be.
nIDEvent
Type: UINT_PTR
A timer identifier. If the hWnd parameter is NULL , and the nIDEvent does not match an existing timer, then the
nIDEvent is ignored and a new timer ID is generated. If the hWnd parameter is not NULL and the window
specified by hWnd already has a timer with the value nIDEvent, then the existing timer is replaced by the new
timer. When SetCoalescableTimer replaces a timer, the timer is reset. Therefore, a message will be sent after
the current time-out value elapses, but the previously set time-out value is ignored. If the call is not intended to
replace an existing timer, nIDEvent should be 0 if the hWnd is NULL .
uElapse
Type: UINT
The time-out value, in milliseconds.
If uElapse is less than USER_TIMER_MINIMUM (0x0000000A), the timeout is set to
USER_TIMER_MINIMUM . If uElapse is greater than USER_TIMER_MAXIMUM (0x7FFFFFFF), the timeout is
set to USER_TIMER_MAXIMUM .
If the sum of uElapse and uToleranceDelay exceeds USER_TIMER_MAXIMUM , an
ERROR_INVALID_PARAMETER exception occurs.
lpTimerFunc
Type: TIMERPROC
A pointer to the function to be notified when the time-out value elapses. For more information about the
function, see TimerProc. If lpTimerFunc is NULL , the system posts a WM_TIMER message to the application
queue. The hwnd member of the message's MSG structure contains the value of the hWnd parameter.
uToleranceDelay
Type: ULONG
It can be one of the following values:
VA L UE M EA N IN G
Note Do not use this value unless you are certain that the
timer requires no coalescing.
Return value
Type: UINT_PTR
If the function succeeds and the hWnd parameter is NULL , the return value is an integer identifying the new
timer. An application can pass this value to the KillTimer function to destroy the timer.
If the function succeeds and the hWnd parameter is not NULL , then the return value is a nonzero integer. An
application can pass the value of the nIDEvent parameter to the KillTimer function to destroy the timer.
If the function fails to create a timer, the return value is zero. To get extended error information, call GetLastError.
Remarks
An application can process WM_TIMER messages by including a WM_TIMER case statement in the window
procedure or by specifying a TimerProc callback function when creating the timer. When you specify a
TimerProc callback function, the default window procedure calls the callback function when it processes
WM_TIMER . Therefore, you need to dispatch messages in the calling thread, even when you use TimerProc
instead of processing WM_TIMER .
The wParam parameter of the WM_TIMER message contains the value of the nIDEvent parameter.
The timer identifier, nIDEvent, is specific to the associated window. Another window can have its own timer
which has the same identifier as a timer owned by another window. The timers are distinct.
SetTimer can reuse timer IDs in the case where hWnd is NULL .
When uToleranceDelay is set to 0, the system default timer coalescing is used and SetCoalescableTimer
behaves the same as SetTimer.
Requirements
Minimum suppor ted ser ver Windows Server 2012 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Coalescing timers sample
Conceptual
KeSetCoalescableTimer
KeSetTimer
KillTimer
MSG
Reference
Sample
SetTimer
TimerProc
Timers
Using Timers
WM_TIMER
SetForegroundWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Brings the thread that created the specified window into the foreground and activates the window. Keyboard
input is directed to the window, and various visual cues are changed for the user. The system assigns a slightly
higher priority to the thread that created the foreground window than it does to other threads.
Syntax
BOOL SetForegroundWindow(
HWND hWnd
);
Parameters
hWnd
Type: HWND
A handle to the window that should be activated and brought to the foreground.
Return value
Type: BOOL
If the window was brought to the foreground, the return value is nonzero.
If the window was not brought to the foreground, the return value is zero.
Remarks
The system restricts which processes can set the foreground window. A process can set the foreground window
only if one of the following conditions is true:
The process is the foreground process.
The process was started by the foreground process.
The process received the last input event.
There is no foreground process.
The process is being debugged.
The foreground process is not a Modern Application or the Start Screen.
The foreground is not locked (see LockSetForegroundWindow).
The foreground lock time-out has expired (see SPI_GETFOREGROUNDLOCKTIMEOUT in
SystemParametersInfo).
No menus are active.
An application cannot force a window to the foreground while the user is working with another window. Instead,
Windows flashes the taskbar button of the window to notify the user.
A process that can set the foreground window can enable another process to set the foreground window by
calling the AllowSetForegroundWindow function. The process specified by dwProcessId loses the ability to set
the foreground window the next time the user generates input, unless the input is directed at that process, or the
next time a process calls AllowSetForegroundWindow , unless that process is specified.
The foreground process can disable calls to SetForegroundWindow by calling the
LockSetForegroundWindow function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AllowSetForegroundWindow
Conceptual
FlashWindowEx
GetForegroundWindow
LockSetForegroundWindow
Other Resources
Reference
SetActiveWindow
Windows
SetLayeredWindowAttributes function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL SetLayeredWindowAttributes(
HWND hwnd,
COLORREF crKey,
BYTE bAlpha,
DWORD dwFlags
);
Parameters
hwnd
Type: HWND
A handle to the layered window. A layered window is created by specifying WS_EX_L AYERED when creating
the window with the CreateWindowEx function or by setting WS_EX_L AYERED via SetWindowLong after the
window has been created.
Windows 8: The WS_EX_L AYERED style is supported for top-level windows and child windows. Previous
Windows versions support WS_EX_L AYERED only for top-level windows.
crKey
Type: COLORREF
A COLORREF structure that specifies the transparency color key to be used when composing the layered
window. All pixels painted by the window in this color will be transparent. To generate a COLORREF , use the
RGB macro.
bAlpha
Type: BYTE
Alpha value used to describe the opacity of the layered window. Similar to the SourceConstantAlpha member
of the BLENDFUNCTION structure. When bAlpha is 0, the window is completely transparent. When bAlpha is
255, the window is opaque.
dwFlags
Type: DWORD
An action to be taken. This parameter can be one or more of the following values.
VA L UE M EA N IN G
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Note that once SetLayeredWindowAttributes has been called for a layered window, subsequent
UpdateLayeredWindow calls will fail until the layering style bit is cleared and set again.
For more information, see Using Layered Windows.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AlphaBlend
COLORREF
Conceptual
CreateWindowEx
Other Resources
RGB
Reference
SetWindowLong
TransparentBlt
UpdateLayeredWindow
Using Windows
Windows
SetMessageExtraInfo function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sets the extra message information for the current thread. Extra message information is an application- or
driver-defined value associated with the current thread's message queue. An application can use the
GetMessageExtraInfo function to retrieve a thread's extra message information.
Syntax
LPARAM SetMessageExtraInfo(
LPARAM lParam
);
Parameters
lParam
Type: LPARAM
The value to be associated with the current thread.
Return value
Type: LPARAM
The return value is the previous value associated with the current thread.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessageExtraInfo
Messages and Message Queues
Reference
SetParent function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
HWND SetParent(
HWND hWndChild,
HWND hWndNewParent
);
Parameters
hWndChild
Type: HWND
A handle to the child window.
hWndNewParent
Type: HWND
A handle to the new parent window. If this parameter is NULL , the desktop window becomes the new parent
window. If this parameter is HWND_MESSAGE , the child window becomes a message-only window.
Return value
Type: HWND
If the function succeeds, the return value is a handle to the previous parent window.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
An application can use the SetParent function to set the parent window of a pop-up, overlapped, or child
window.
If the window identified by the hWndChild parameter is visible, the system performs the appropriate redrawing
and repainting.
For compatibility reasons, SetParent does not modify the WS_CHILD or WS_POPUP window styles of the
window whose parent is being changed. Therefore, if hWndNewParent is NULL , you should also clear the
WS_CHILD bit and set the WS_POPUP style after calling SetParent . Conversely, if hWndNewParent is not
NULL and the window was previously a child of the desktop, you should clear the WS_POPUP style and set the
WS_CHILD style before calling SetParent .
When you change the parent of a window, you should synchronize the UISTATE of both windows. For more
information, see WM_CHANGEUISTATE and WM_UPDATEUISTATE.
Unexpected behavior or errors may occur if hWndNewParent and hWndChild are running in different DPI
awareness modes. The table below outlines this behavior:
SetParent (Cross-Proc) Forced reset (of child Forced reset (of child Forced reset (of child
window's process) window's process) window's process)
For more information on DPI awareness, see the Windows High DPI documentation.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetParent
Reference
Windows
SetProcessDefaultLayout function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Changes the default layout when windows are created with no parent or owner only for the currently running
process.
Syntax
BOOL SetProcessDefaultLayout(
DWORD dwDefaultLayout
);
Parameters
dwDefaultLayout
Type: DWORD
The default process layout. This parameter can be 0 or the following value.
VA L UE M EA N IN G
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The layout specifies how text and graphics are laid out; the default is left to right. The
SetProcessDefaultLayout function changes layout to be right to left, which is the standard in Arabic and
Hebrew cultures.
After the L AYOUT_RTL flag is selected, flags normally specifying right or left are reversed. To avoid confusion,
consider defining alternate words for standard flags, such as those in the following table.
WS_EX_RIGHT WS_EX_TRAILING
WS_EX_RTLREADING WS_EX_REVERSEREADING
WS_EX_LEFTSCROLLBAR WS_EX_LEADSCROLLBAR
ES_LEFT ES_LEAD
ES_RIGHT ES_TRAIL
EC_LEFTMARGIN EC_LEADMARGIN
EC_RIGHTMARGIN EC_TRAILMARGIN
If using this function with a mirrored window, note that the SetProcessDefaultLayout function does not
mirror the whole process and all the device contexts (DCs) created in it. It mirrors only the mirrored window's
DCs. To mirror any DC, use the SetLayout function.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetProcessDefaultLayout
Other Resources
Reference
SetLayout
Windows
SetProcessDPIAware function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Note It is recommended that you set the process-default DPI awareness via application manifest, not an API call. See Setting
the default DPI awareness for a process for more information. Setting the process-default DPI awareness via API call can lead
to unexpected application behavior.
Sets the process-default DPI awareness to system-DPI awareness. This is equivalent to calling
SetProcessDpiAwarenessContext with a DPI_AWARENESS_CONTEXT value of
DPI_AWARENESS_CONTEXT_SYSTEM_AWARE.
Syntax
BOOL SetProcessDPIAware();
Parameters
This function has no parameters.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero. Otherwise, the return value is zero.
Remarks
For more information, see Setting the default DPI awareness for a process.
Requirements
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Setting the default DPI awareness for a process
SetPropA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Adds a new entry or changes an existing entry in the property list of the specified window. The function adds a
new entry to the list if the specified character string does not exist already in the list. The new entry contains the
string and the handle. Otherwise, the function replaces the string's current handle with the specified handle.
Syntax
BOOL SetPropA(
HWND hWnd,
LPCSTR lpString,
HANDLE hData
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list receives the new entry.
lpString
Type: LPCTSTR
A null-terminated string or an atom that identifies a string. If this parameter is an atom, it must be a global atom
created by a previous call to the GlobalAddAtom function. The atom must be placed in the low-order word of
lpString; the high-order word must be zero.
hData
Type: HANDLE
A handle to the data to be copied to the property list. The data handle can identify any value useful to the
application.
Return value
Type: BOOL
If the data handle and string are added to the property list, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Before a window is destroyed (that is, before it returns from processing the WM_NCDESTROY message), an
application must remove all entries it has added to the property list. The application must use the RemoveProp
function to remove the entries.
SetProp is subject to the restrictions of User Interface Privilege Isolation (UIPI). A process can only call this
function on a window belonging to a process of lesser or equal integrity level. When UIPI blocks property
changes, GetLastError will return 5.
Examples
For an example, see Adding a Window Property.
NOTE
The winuser.h header defines SetProp 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GlobalAddAtom
Reference
RemoveProp
WM_NCDESTROY
Window Properties
ITaskbarList2::MarkFullscreenWindow
SetPropW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Adds a new entry or changes an existing entry in the property list of the specified window. The function adds a
new entry to the list if the specified character string does not exist already in the list. The new entry contains the
string and the handle. Otherwise, the function replaces the string's current handle with the specified handle.
Syntax
BOOL SetPropW(
HWND hWnd,
LPCWSTR lpString,
HANDLE hData
);
Parameters
hWnd
Type: HWND
A handle to the window whose property list receives the new entry.
lpString
Type: LPCTSTR
A null-terminated string or an atom that identifies a string. If this parameter is an atom, it must be a global atom
created by a previous call to the GlobalAddAtom function. The atom must be placed in the low-order word of
lpString; the high-order word must be zero.
hData
Type: HANDLE
A handle to the data to be copied to the property list. The data handle can identify any value useful to the
application.
Return value
Type: BOOL
If the data handle and string are added to the property list, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Before a window is destroyed (that is, before it returns from processing the WM_NCDESTROY message), an
application must remove all entries it has added to the property list. The application must use the RemoveProp
function to remove the entries.
SetProp is subject to the restrictions of User Interface Privilege Isolation (UIPI). A process can only call this
function on a window belonging to a process of lesser or equal integrity level. When UIPI blocks property
changes, GetLastError will return 5.
Examples
For an example, see Adding a Window Property.
NOTE
The winuser.h header defines SetProp 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GlobalAddAtom
Reference
RemoveProp
WM_NCDESTROY
Window Properties
ITaskbarList2::MarkFullscreenWindow
SetSysColors function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sets the colors for the specified display elements. Display elements are the various parts of a window and the
display that appear on the system display screen.
Syntax
BOOL SetSysColors(
int cElements,
const INT *lpaElements,
const COLORREF *lpaRgbValues
);
Parameters
cElements
Type: int
The number of display elements in the lpaElements array.
lpaElements
Return value
Type: BOOL
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The SetSysColors function sends a WM_SYSCOLORCHANGE message to all windows to inform them of the
change in color. It also directs the system to repaint the affected portions of all currently visible windows.
It is best to respect the color settings specified by the user. If you are writing an application to enable the user to
change the colors, then it is appropriate to use this function. However, this function affects only the current
session. The new colors are not saved when the system terminates.
Examples
The following example demonstrates the use of the GetSysColor and SetSysColors functions. First, the
example uses GetSysColor to retrieve the colors of the window background and active caption and displays
the red, green, blue (RGB) values in hexadecimal notation. Next, example uses SetSysColors to change the
color of the window background to light gray and the active title bars to dark purple. After a 10-second delay,
the example restores the previous colors for these elements using SetSysColors.
#include <windows.h>
#include <stdio.h>
#pragma comment(lib, "user32.lib")
void main()
{
int aElements[2] = {COLOR_WINDOW, COLOR_ACTIVECAPTION};
DWORD aOldColors[2];
DWORD aNewColors[2];
aOldColors[0] = GetSysColor(aElements[0]);
aOldColors[1] = GetSysColor(aElements[1]);
Sleep(10000);
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
COLORREF
GetSysColor
RGB
SetTimer function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
UINT_PTR SetTimer(
HWND hWnd,
UINT_PTR nIDEvent,
UINT uElapse,
TIMERPROC lpTimerFunc
);
Parameters
hWnd
Type: HWND
A handle to the window to be associated with the timer. This window must be owned by the calling thread. If a
NULL value for hWnd is passed in along with an nIDEvent of an existing timer, that timer will be replaced in the
same way that an existing non-NULL hWnd timer will be.
nIDEvent
Type: UINT_PTR
A nonzero timer identifier. If the hWnd parameter is NULL , and the nIDEvent does not match an existing timer
then it is ignored and a new timer ID is generated. If the hWnd parameter is not NULL and the window specified
by hWnd already has a timer with the value nIDEvent, then the existing timer is replaced by the new timer. When
SetTimer replaces a timer, the timer is reset. Therefore, a message will be sent after the current time-out value
elapses, but the previously set time-out value is ignored. If the call is not intended to replace an existing timer,
nIDEvent should be 0 if the hWnd is NULL .
uElapse
Type: UINT
The time-out value, in milliseconds.
If uElapse is less than USER_TIMER_MINIMUM (0x0000000A), the timeout is set to
USER_TIMER_MINIMUM . If uElapse is greater than USER_TIMER_MAXIMUM (0x7FFFFFFF), the timeout is
set to USER_TIMER_MAXIMUM .
lpTimerFunc
Type: TIMERPROC
A pointer to the function to be notified when the time-out value elapses. For more information about the
function, see TimerProc. If lpTimerFunc is NULL , the system posts a WM_TIMER message to the application
queue. The hwnd member of the message's MSG structure contains the value of the hWnd parameter.
Return value
Type: UINT_PTR
If the function succeeds and the hWnd parameter is NULL , the return value is an integer identifying the new
timer. An application can pass this value to the KillTimer function to destroy the timer.
If the function succeeds and the hWnd parameter is not NULL , then the return value is a nonzero integer. An
application can pass the value of the nIDEvent parameter to the KillTimer function to destroy the timer.
If the function fails to create a timer, the return value is zero. To get extended error information, call GetLastError.
Remarks
An application can process WM_TIMER messages by including a WM_TIMER case statement in the window
procedure or by specifying a TimerProc callback function when creating the timer. When you specify a
TimerProc callback function, the default window procedure calls the callback function when it processes
WM_TIMER . Therefore, you need to dispatch messages in the calling thread, even when you use TimerProc
instead of processing WM_TIMER .
The wParam parameter of the WM_TIMER message contains the value of the nIDEvent parameter.
The timer identifier, nIDEvent, is specific to the associated window. Another window can have its own timer
which has the same identifier as a timer owned by another window. The timers are distinct.
SetTimer can reuse timer IDs in the case where hWnd is NULL .
Examples
For an example, see Creating a Timer.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
KillTimer
MSG
Reference
SetWaitableTimer
TimerProc
Timers
WM_TIMER
SetWindowDisplayAffinity function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL SetWindowDisplayAffinity(
HWND hWnd,
DWORD dwAffinity
);
Parameters
hWnd
Type: HWND
A handle to the top-level window. The window must belong to the current process.
dwAffinity
Type: DWORD
The display affinity setting that specifies where the content of the window can be displayed.
This parameter can be one of the following values.
VA L UE M EA N IN G
Return value
Type: BOOL
If the function succeeds, it returns TRUE ; otherwise, it returns FALSE when, for example, the function call is
made on a non top-level window. To get extended error information, call GetLastError.
Remarks
This function and GetWindowDisplayAffinity are designed to support the window content protection feature
that is new to Windows 7. This feature enables applications to protect their own onscreen window content from
being captured or copied through a specific set of public operating system features and APIs. However, it works
only when the Desktop Window Manager(DWM) is composing the desktop.
It is important to note that unlike a security feature or an implementation of Digital Rights Management (DRM),
there is no guarantee that using SetWindowDisplayAffinity and GetWindowDisplayAffinity, and other
necessary functions such as DwmIsCompositionEnabled, will strictly protect windowed content, for example
where someone takes a photograph of the screen.
Starting in Windows 10 Version 2004, WDA_EXCLUDEFROMCAPTURE is a supported value. Setting the display
affinity to WDA_EXCLUDEFROMCAPTURE on previous version of Windows will behave as if WDA_MONITOR is
applied.
Requirements
Minimum suppor ted ser ver Windows Server 2008 R2 [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
SetWindowDisplayAffinity, Windows
SetWindowLongA function (winuser.h)
2/1/2021 • 4 minutes to read • Edit Online
Changes an attribute of the specified window. The function also sets the 32-bit (long) value at the specified
offset into the extra window memory.
Note This function has been superseded by the SetWindowLongPtr function. To write code that is compatible with both 32-
bit and 64-bit versions of Windows, use the SetWindowLongPtr function.
Syntax
LONG SetWindowLongA(
HWND hWnd,
int nIndex,
LONG dwNewLong
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The zero-based offset to the value to be set. Valid values are in the range zero through the number of bytes of
extra window memory, minus the size of an integer. To set any other value, specify one of the following values.
VA L UE M EA N IN G
The following values are also available when the hWnd parameter identifies a dialog box.
VA L UE M EA N IN G
dwNewLong
Type: LONG
The replacement value.
Return value
Type: LONG
If the function succeeds, the return value is the previous value of the specified 32-bit integer.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If the previous value of the specified 32-bit integer is zero, and the function succeeds, the return value is zero,
but the function does not clear the last error information. This makes it difficult to determine success or failure.
To deal with this, you should clear the last error information by calling SetLastError with 0 before calling
SetWindowLong . Then, function failure will be indicated by a return value of zero and a GetLastError result
that is nonzero.
Remarks
Certain window data is cached, so changes you make using SetWindowLong will not take effect until you call
the SetWindowPos function. Specifically, if you change any of the frame styles, you must call SetWindowPos
with the SWP_FRAMECHANGED flag for the cache to be updated properly.
If you use SetWindowLong with the GWL_WNDPROC index to replace the window procedure, the window
procedure must conform to the guidelines specified in the description of the WindowProc callback function.
If you use SetWindowLong with the DWL_MSGRESULT index to set the return value for a message
processed by a dialog procedure, you should return TRUE directly afterward. Otherwise, if you call any function
that results in your dialog procedure receiving a window message, the nested window message could overwrite
the return value you set using DWL_MSGRESULT .
Calling SetWindowLong with the GWL_WNDPROC index creates a subclass of the window class used to
create the window. An application can subclass a system class, but should not subclass a window class created
by another process. The SetWindowLong function creates the window subclass by changing the window
procedure associated with a particular window class, causing the system to call the new window procedure
instead of the previous one. An application must pass any messages not processed by the new window
procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a
chain of window procedures.
Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the
WNDCLASSEX structure used with the RegisterClassEx function.
You must not call SetWindowLong with the GWL_HWNDPARENT index to change the parent of a child
window. Instead, use the SetParent function.
If the window has a class style of CS_CL ASSDC or CS_OWNDC , do not set the extended window styles
WS_EX_COMPOSITED or WS_EX_L AYERED .
Calling SetWindowLong to set the style on a progressbar will reset its position.
Examples
For an example, see Subclassing a Window.
NOTE
The winuser.h header defines SetWindowLong 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Changes an attribute of the specified window. The function also sets a value at the specified offset in the extra
window memory.
Note To write code that is compatible with both 32-bit and 64-bit versions of Windows, use SetWindowLongPtr . When
compiling for 32-bit Windows, SetWindowLongPtr is defined as a call to the SetWindowLong function.
Syntax
LONG_PTR SetWindowLongPtrA(
HWND hWnd,
int nIndex,
LONG_PTR dwNewLong
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs. The SetWindowLongPtr
function fails if the process that owns the window specified by the hWnd parameter is at a higher process
privilege in the UIPI hierarchy than the process the calling thread resides in.
Windows XP/2000: The SetWindowLongPtr function fails if the window specified by the hWnd parameter
does not belong to the same process as the calling thread.
nIndex
Type: int
The zero-based offset to the value to be set. Valid values are in the range zero through the number of bytes of
extra window memory, minus the size of a LONG_PTR . To set any other value, specify one of the following
values.
VA L UE M EA N IN G
Sets the user data associated with the window. This data is
GWLP_USERDATA intended for use by the application that created the window.
-21 Its value is initially zero.
The following values are also available when the hWnd parameter identifies a dialog box.
VA L UE M EA N IN G
dwNewLong
Type: LONG_PTR
The replacement value.
Return value
Type: LONG_PTR
If the function succeeds, the return value is the previous value of the specified offset.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If the previous value is zero and the function succeeds, the return value is zero, but the function does not clear
the last error information. To determine success or failure, clear the last error information by calling SetLastError
with 0, then call SetWindowLongPtr . Function failure will be indicated by a return value of zero and a
GetLastError result that is nonzero.
Remarks
Certain window data is cached, so changes you make using SetWindowLongPtr will not take effect until you
call the SetWindowPos function.
If you use SetWindowLongPtr with the GWLP_WNDPROC index to replace the window procedure, the
window procedure must conform to the guidelines specified in the description of the WindowProc callback
function.
If you use SetWindowLongPtr with the DWLP_MSGRESULT index to set the return value for a message
processed by a dialog box procedure, the dialog box procedure should return TRUE directly afterward.
Otherwise, if you call any function that results in your dialog box procedure receiving a window message, the
nested window message could overwrite the return value you set by using DWLP_MSGRESULT .
Calling SetWindowLongPtr with the GWLP_WNDPROC index creates a subclass of the window class used to
create the window. An application can subclass a system class, but should not subclass a window class created
by another process. The SetWindowLongPtr function creates the window subclass by changing the window
procedure associated with a particular window class, causing the system to call the new window procedure
instead of the previous one. An application must pass any messages not processed by the new window
procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a
chain of window procedures.
Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the
WNDCLASSEX structure used with the RegisterClassEx function.
Do not call SetWindowLongPtr with the GWLP_HWNDPARENT index to change the parent of a child
window. Instead, use the SetParent function.
If the window has a class style of CS_CL ASSDC or CS_PARENTDC , do not set the extended window styles
WS_EX_COMPOSITED or WS_EX_L AYERED .
Calling SetWindowLongPtr to set the style on a progressbar will reset its position.
NOTE
The winuser.h header defines SetWindowLongPtr 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Changes an attribute of the specified window. The function also sets a value at the specified offset in the extra
window memory.
Note To write code that is compatible with both 32-bit and 64-bit versions of Windows, use SetWindowLongPtr . When
compiling for 32-bit Windows, SetWindowLongPtr is defined as a call to the SetWindowLong function.
Syntax
LONG_PTR SetWindowLongPtrW(
HWND hWnd,
int nIndex,
LONG_PTR dwNewLong
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs. The SetWindowLongPtr
function fails if the process that owns the window specified by the hWnd parameter is at a higher process
privilege in the UIPI hierarchy than the process the calling thread resides in.
Windows XP/2000: The SetWindowLongPtr function fails if the window specified by the hWnd parameter
does not belong to the same process as the calling thread.
nIndex
Type: int
The zero-based offset to the value to be set. Valid values are in the range zero through the number of bytes of
extra window memory, minus the size of a LONG_PTR . To set any other value, specify one of the following
values.
VA L UE M EA N IN G
Sets the user data associated with the window. This data is
GWLP_USERDATA intended for use by the application that created the window.
-21 Its value is initially zero.
The following values are also available when the hWnd parameter identifies a dialog box.
VA L UE M EA N IN G
dwNewLong
Type: LONG_PTR
The replacement value.
Return value
Type: LONG_PTR
If the function succeeds, the return value is the previous value of the specified offset.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If the previous value is zero and the function succeeds, the return value is zero, but the function does not clear
the last error information. To determine success or failure, clear the last error information by calling SetLastError
with 0, then call SetWindowLongPtr . Function failure will be indicated by a return value of zero and a
GetLastError result that is nonzero.
Remarks
Certain window data is cached, so changes you make using SetWindowLongPtr will not take effect until you
call the SetWindowPos function.
If you use SetWindowLongPtr with the GWLP_WNDPROC index to replace the window procedure, the
window procedure must conform to the guidelines specified in the description of the WindowProc callback
function.
If you use SetWindowLongPtr with the DWLP_MSGRESULT index to set the return value for a message
processed by a dialog box procedure, the dialog box procedure should return TRUE directly afterward.
Otherwise, if you call any function that results in your dialog box procedure receiving a window message, the
nested window message could overwrite the return value you set by using DWLP_MSGRESULT .
Calling SetWindowLongPtr with the GWLP_WNDPROC index creates a subclass of the window class used to
create the window. An application can subclass a system class, but should not subclass a window class created
by another process. The SetWindowLongPtr function creates the window subclass by changing the window
procedure associated with a particular window class, causing the system to call the new window procedure
instead of the previous one. An application must pass any messages not processed by the new window
procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a
chain of window procedures.
Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the
WNDCLASSEX structure used with the RegisterClassEx function.
Do not call SetWindowLongPtr with the GWLP_HWNDPARENT index to change the parent of a child
window. Instead, use the SetParent function.
If the window has a class style of CS_CL ASSDC or CS_PARENTDC , do not set the extended window styles
WS_EX_COMPOSITED or WS_EX_L AYERED .
Calling SetWindowLongPtr to set the style on a progressbar will reset its position.
NOTE
The winuser.h header defines SetWindowLongPtr 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Changes an attribute of the specified window. The function also sets the 32-bit (long) value at the specified
offset into the extra window memory.
Note This function has been superseded by the SetWindowLongPtr function. To write code that is compatible with both 32-
bit and 64-bit versions of Windows, use the SetWindowLongPtr function.
Syntax
LONG SetWindowLongW(
HWND hWnd,
int nIndex,
LONG dwNewLong
);
Parameters
hWnd
Type: HWND
A handle to the window and, indirectly, the class to which the window belongs.
nIndex
Type: int
The zero-based offset to the value to be set. Valid values are in the range zero through the number of bytes of
extra window memory, minus the size of an integer. To set any other value, specify one of the following values.
VA L UE M EA N IN G
The following values are also available when the hWnd parameter identifies a dialog box.
VA L UE M EA N IN G
dwNewLong
Type: LONG
The replacement value.
Return value
Type: LONG
If the function succeeds, the return value is the previous value of the specified 32-bit integer.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If the previous value of the specified 32-bit integer is zero, and the function succeeds, the return value is zero,
but the function does not clear the last error information. This makes it difficult to determine success or failure.
To deal with this, you should clear the last error information by calling SetLastError with 0 before calling
SetWindowLong . Then, function failure will be indicated by a return value of zero and a GetLastError result
that is nonzero.
Remarks
Certain window data is cached, so changes you make using SetWindowLong will not take effect until you call
the SetWindowPos function. Specifically, if you change any of the frame styles, you must call SetWindowPos
with the SWP_FRAMECHANGED flag for the cache to be updated properly.
If you use SetWindowLong with the GWL_WNDPROC index to replace the window procedure, the window
procedure must conform to the guidelines specified in the description of the WindowProc callback function.
If you use SetWindowLong with the DWL_MSGRESULT index to set the return value for a message
processed by a dialog procedure, you should return TRUE directly afterward. Otherwise, if you call any function
that results in your dialog procedure receiving a window message, the nested window message could overwrite
the return value you set using DWL_MSGRESULT .
Calling SetWindowLong with the GWL_WNDPROC index creates a subclass of the window class used to
create the window. An application can subclass a system class, but should not subclass a window class created
by another process. The SetWindowLong function creates the window subclass by changing the window
procedure associated with a particular window class, causing the system to call the new window procedure
instead of the previous one. An application must pass any messages not processed by the new window
procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a
chain of window procedures.
Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the
WNDCLASSEX structure used with the RegisterClassEx function.
You must not call SetWindowLong with the GWL_HWNDPARENT index to change the parent of a child
window. Instead, use the SetParent function.
If the window has a class style of CS_CL ASSDC or CS_OWNDC , do not set the extended window styles
WS_EX_COMPOSITED or WS_EX_L AYERED .
Calling SetWindowLong to set the style on a progressbar will reset its position.
Examples
For an example, see Subclassing a Window.
NOTE
The winuser.h header defines SetWindowLong 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Sets the show state and the restored, minimized, and maximized positions of the specified window.
Syntax
BOOL SetWindowPlacement(
HWND hWnd,
const WINDOWPLACEMENT *lpwndpl
);
Parameters
hWnd
Type: HWND
A handle to the window.
lpwndpl
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If the information specified in WINDOWPLACEMENT would result in a window that is completely off the screen,
the system will automatically adjust the coordinates so that the window is visible, taking into account changes in
screen resolution and multiple monitor configuration.
The length member of WINDOWPLACEMENT must be set to sizeof(WINDOWPLACEMENT) . If this member is not set
correctly, the function returns FALSE . For additional remarks on the proper use of window placement
coordinates, see WINDOWPL ACEMENT .
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowPlacement
Reference
WINDOWPLACEMENT
Windows
SetWindowPos function (winuser.h)
2/1/2021 • 5 minutes to read • Edit Online
Changes the size, position, and Z order of a child, pop-up, or top-level window. These windows are ordered
according to their appearance on the screen. The topmost window receives the highest rank and is the first
window in the Z order.
Syntax
BOOL SetWindowPos(
HWND hWnd,
HWND hWndInsertAfter,
int X,
int Y,
int cx,
int cy,
UINT uFlags
);
Parameters
hWnd
Type: HWND
A handle to the window.
hWndInsertAfter
Type: HWND
A handle to the window to precede the positioned window in the Z order. This parameter must be a window
handle or one of the following values.
VA L UE M EA N IN G
Type: int
The new position of the left side of the window, in client coordinates.
Y
Type: int
The new position of the top of the window, in client coordinates.
cx
Type: int
The new width of the window, in pixels.
cy
Type: int
The new height of the window, in pixels.
uFlags
Type: UINT
The window sizing and positioning flags. This parameter can be a combination of the following values.
VA L UE M EA N IN G
If the calling thread and the thread that owns the window
SWP_ASYNCWINDOWPOS are attached to different input queues, the system posts the
0x4000 request to the thread that owns the window. This prevents
the calling thread from blocking its execution while other
threads process the request.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
As part of the Vista re-architecture, all services were moved off the interactive desktop into Session 0. hwnd and
window manager operations are only effective inside a session and cross-session attempts to manipulate the
hwnd will fail. For more information, see The Windows Vista Developer Story: Application Compatibility
Cookbook.
If you have changed certain window data using SetWindowLong, you must call SetWindowPos for the changes
to take effect. Use the following combination for uFlags:
SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED .
A window can be made a topmost window either by setting the hWndInsertAfter parameter to
HWND_TOPMOST and ensuring that the SWP_NOZORDER flag is not set, or by setting a window's position
in the Z order so that it is above any existing topmost windows. When a non-topmost window is made topmost,
its owned windows are also made topmost. Its owners, however, are not changed.
If neither the SWP_NOACTIVATE nor SWP_NOZORDER flag is specified (that is, when the application
requests that a window be simultaneously activated and its position in the Z order changed), the value specified
in hWndInsertAfter is used only in the following circumstances.
Neither the HWND_TOPMOST nor HWND_NOTOPMOST flag is specified in hWndInsertAfter.
The window identified by hWnd is not the active window.
An application cannot activate an inactive window without also bringing it to the top of the Z order. Applications can
change an activated window's position in the Z order without restrictions, or it can activate a window and then
move it to the top of the topmost or non-topmost windows.
If a topmost window is repositioned to the bottom (HWND_BOTTOM ) of the Z order or after any non-topmost
window, it is no longer topmost. When a topmost window is made non-topmost, its owners and its owned
windows are also made non-topmost windows.
A non-topmost window can own a topmost window, but the reverse cannot occur. Any window (for example, a
dialog box) owned by a topmost window is itself made a topmost window, to ensure that all owned windows
stay above their owner.
If an application is not in the foreground, and should be in the foreground, it must call the
SetForegroundWindow function.
To use SetWindowPos to bring a window to the top, the process that owns the window must have
SetForegroundWindow permission.
Examples
For an example, see Initializing a Dialog Box.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
MoveWindow
Reference
SetActiveWindow
SetForegroundWindow
Windows
SetWindowsHookExA function (winuser.h)
2/1/2021 • 7 minutes to read • Edit Online
Installs an application-defined hook procedure into a hook chain. You would install a hook procedure to monitor
the system for certain types of events. These events are associated either with a specific thread or with all
threads in the same desktop as the calling thread.
Syntax
HHOOK SetWindowsHookExA(
int idHook,
HOOKPROC lpfn,
HINSTANCE hmod,
DWORD dwThreadId
);
Parameters
idHook
Type: int
The type of hook procedure to be installed. This parameter can be one of the following values.
VA L UE M EA N IN G
lpfn
Type: HOOKPROC
A pointer to the hook procedure. If the dwThreadId parameter is zero or specifies the identifier of a thread
created by a different process, the lpfn parameter must point to a hook procedure in a DLL. Otherwise, lpfn can
point to a hook procedure in the code associated with the current process.
hmod
Type: HINSTANCE
A handle to the DLL containing the hook procedure pointed to by the lpfn parameter. The hMod parameter must
be set to NULL if the dwThreadId parameter specifies a thread created by the current process and if the hook
procedure is within the code associated with the current process.
dwThreadId
Type: DWORD
The identifier of the thread with which the hook procedure is to be associated. For desktop apps, if this
parameter is zero, the hook procedure is associated with all existing threads running in the same desktop as the
calling thread. For Windows Store apps, see the Remarks section.
Return value
Type: HHOOK
If the function succeeds, the return value is the handle to the hook procedure.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
SetWindowsHookEx can be used to inject a DLL into another process. A 32-bit DLL cannot be injected into a
64-bit process, and a 64-bit DLL cannot be injected into a 32-bit process. If an application requires the use of
hooks in other processes, it is required that a 32-bit application call SetWindowsHookEx to inject a 32-bit DLL
into 32-bit processes, and a 64-bit application call SetWindowsHookEx to inject a 64-bit DLL into 64-bit
processes. The 32-bit and 64-bit DLLs must have different names.
Because hooks run in the context of an application, they must match the "bitness" of the application. If a 32-bit
application installs a global hook on 64-bit Windows, the 32-bit hook is injected into each 32-bit process (the
usual security boundaries apply). In a 64-bit process, the threads are still marked as "hooked." However, because
a 32-bit application must run the hook code, the system executes the hook in the hooking app's context;
specifically, on the thread that called SetWindowsHookEx . This means that the hooking application must
continue to pump messages or it might block the normal functioning of the 64-bit processes.
If a 64-bit application installs a global hook on 64-bit Windows, the 64-bit hook is injected into each 64-bit
process, while all 32-bit processes use a callback to the hooking application.
To hook all applications on the desktop of a 64-bit Windows installation, install a 32-bit global hook and a 64-bit
global hook, each from appropriate processes, and be sure to keep pumping messages in the hooking
application to avoid blocking normal functioning. If you already have a 32-bit global hooking application and it
doesn't need to run in each application's context, you may not need to create a 64-bit version.
An error may occur if the hMod parameter is NULL and the dwThreadId parameter is zero or specifies the
identifier of a thread created by another process.
Calling the CallNextHookEx function to chain to the next hook procedure is optional, but it is highly
recommended; otherwise, other applications that have installed hooks will not receive hook notifications and
may behave incorrectly as a result. You should call CallNextHookEx unless you absolutely need to prevent the
notification from being seen by other applications.
Before terminating, an application must call the UnhookWindowsHookEx function to free system resources
associated with the hook.
The scope of a hook depends on the hook type. Some hooks can be set only with global scope; others can also
be set for only a specific thread, as shown in the following table.
H OOK SC O P E
For a specified hook type, thread hooks are called first, then global hooks. Be aware that the WH_MOUSE,
WH_KEYBOARD, WH_JOURNAL*, WH_SHELL, and low-level hooks can be called on the thread that installed the
hook rather than the thread processing the hook. For these hooks, it is possible that both the 32-bit and 64-bit
hooks will be called if a 32-bit hook is ahead of a 64-bit hook in the hook chain.
The global hooks are a shared resource, and installing one affects all applications in the same desktop as the
calling thread. All global hook functions must be in libraries. Global hooks should be restricted to special-
purpose applications or to use as a development aid during application debugging. Libraries that no longer
need a hook should remove its hook procedure.
Windows Store app development If dwThreadId is zero, then window hook DLLs are not loaded in-process
for the Windows Store app processes and the Windows Runtime broker process unless they are installed by
either UIAccess processes (accessibility tools). The notification is delivered on the installer's thread for these
hooks:
WH_JOURNALPLAYBACK
WH_JOURNALRECORD
WH_KEYBOARD
WH_KEYBOARD_LL
WH_MOUSE
WH_MOUSE_LL
This behavior is similar to what happens when there is an architecture mismatch between the hook DLL and the
target application process, for example, when the hook DLL is 32-bit and the application process 64-bit.
Examples
For an example, see Installing and Releasing Hook Procedures.
NOTE
The winuser.h header defines SetWindowsHookEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CBTProc
CallNextHookEx
CallWndProc
CallWndRetProc
Conceptual
DebugProc
ForegroundIdleProc
GetMsgProc
Hooks
JournalPlaybackProc
JournalRecordProc
KeyboardProc
LowLevelKeyboardProc
LowLevelMouseProc
MessageProc
MouseProc
Reference
ShellProc
SysMsgProc
UnhookWindowsHookEx
SetWindowsHookExW function (winuser.h)
2/1/2021 • 7 minutes to read • Edit Online
Installs an application-defined hook procedure into a hook chain. You would install a hook procedure to monitor
the system for certain types of events. These events are associated either with a specific thread or with all
threads in the same desktop as the calling thread.
Syntax
HHOOK SetWindowsHookExW(
int idHook,
HOOKPROC lpfn,
HINSTANCE hmod,
DWORD dwThreadId
);
Parameters
idHook
Type: int
The type of hook procedure to be installed. This parameter can be one of the following values.
VA L UE M EA N IN G
lpfn
Type: HOOKPROC
A pointer to the hook procedure. If the dwThreadId parameter is zero or specifies the identifier of a thread
created by a different process, the lpfn parameter must point to a hook procedure in a DLL. Otherwise, lpfn can
point to a hook procedure in the code associated with the current process.
hmod
Type: HINSTANCE
A handle to the DLL containing the hook procedure pointed to by the lpfn parameter. The hMod parameter must
be set to NULL if the dwThreadId parameter specifies a thread created by the current process and if the hook
procedure is within the code associated with the current process.
dwThreadId
Type: DWORD
The identifier of the thread with which the hook procedure is to be associated. For desktop apps, if this
parameter is zero, the hook procedure is associated with all existing threads running in the same desktop as the
calling thread. For Windows Store apps, see the Remarks section.
Return value
Type: HHOOK
If the function succeeds, the return value is the handle to the hook procedure.
If the function fails, the return value is NULL . To get extended error information, call GetLastError.
Remarks
SetWindowsHookEx can be used to inject a DLL into another process. A 32-bit DLL cannot be injected into a
64-bit process, and a 64-bit DLL cannot be injected into a 32-bit process. If an application requires the use of
hooks in other processes, it is required that a 32-bit application call SetWindowsHookEx to inject a 32-bit DLL
into 32-bit processes, and a 64-bit application call SetWindowsHookEx to inject a 64-bit DLL into 64-bit
processes. The 32-bit and 64-bit DLLs must have different names.
Because hooks run in the context of an application, they must match the "bitness" of the application. If a 32-bit
application installs a global hook on 64-bit Windows, the 32-bit hook is injected into each 32-bit process (the
usual security boundaries apply). In a 64-bit process, the threads are still marked as "hooked." However, because
a 32-bit application must run the hook code, the system executes the hook in the hooking app's context;
specifically, on the thread that called SetWindowsHookEx . This means that the hooking application must
continue to pump messages or it might block the normal functioning of the 64-bit processes.
If a 64-bit application installs a global hook on 64-bit Windows, the 64-bit hook is injected into each 64-bit
process, while all 32-bit processes use a callback to the hooking application.
To hook all applications on the desktop of a 64-bit Windows installation, install a 32-bit global hook and a 64-bit
global hook, each from appropriate processes, and be sure to keep pumping messages in the hooking
application to avoid blocking normal functioning. If you already have a 32-bit global hooking application and it
doesn't need to run in each application's context, you may not need to create a 64-bit version.
An error may occur if the hMod parameter is NULL and the dwThreadId parameter is zero or specifies the
identifier of a thread created by another process.
Calling the CallNextHookEx function to chain to the next hook procedure is optional, but it is highly
recommended; otherwise, other applications that have installed hooks will not receive hook notifications and
may behave incorrectly as a result. You should call CallNextHookEx unless you absolutely need to prevent the
notification from being seen by other applications.
Before terminating, an application must call the UnhookWindowsHookEx function to free system resources
associated with the hook.
The scope of a hook depends on the hook type. Some hooks can be set only with global scope; others can also
be set for only a specific thread, as shown in the following table.
H OOK SC O P E
For a specified hook type, thread hooks are called first, then global hooks. Be aware that the WH_MOUSE,
WH_KEYBOARD, WH_JOURNAL*, WH_SHELL, and low-level hooks can be called on the thread that installed the
hook rather than the thread processing the hook. For these hooks, it is possible that both the 32-bit and 64-bit
hooks will be called if a 32-bit hook is ahead of a 64-bit hook in the hook chain.
The global hooks are a shared resource, and installing one affects all applications in the same desktop as the
calling thread. All global hook functions must be in libraries. Global hooks should be restricted to special-
purpose applications or to use as a development aid during application debugging. Libraries that no longer
need a hook should remove its hook procedure.
Windows Store app development If dwThreadId is zero, then window hook DLLs are not loaded in-process
for the Windows Store app processes and the Windows Runtime broker process unless they are installed by
either UIAccess processes (accessibility tools). The notification is delivered on the installer's thread for these
hooks:
WH_JOURNALPLAYBACK
WH_JOURNALRECORD
WH_KEYBOARD
WH_KEYBOARD_LL
WH_MOUSE
WH_MOUSE_LL
This behavior is similar to what happens when there is an architecture mismatch between the hook DLL and the
target application process, for example, when the hook DLL is 32-bit and the application process 64-bit.
Examples
For an example, see Installing and Releasing Hook Procedures.
NOTE
The winuser.h header defines SetWindowsHookEx 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CBTProc
CallNextHookEx
CallWndProc
CallWndRetProc
Conceptual
DebugProc
ForegroundIdleProc
GetMsgProc
Hooks
JournalPlaybackProc
JournalRecordProc
KeyboardProc
LowLevelKeyboardProc
LowLevelMouseProc
MessageProc
MouseProc
Reference
ShellProc
SysMsgProc
UnhookWindowsHookEx
SetWindowTextA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Changes the text of the specified window's title bar (if it has one). If the specified window is a control, the text of
the control is changed. However, SetWindowText cannot change the text of a control in another application.
Syntax
BOOL SetWindowTextA(
HWND hWnd,
LPCSTR lpString
);
Parameters
hWnd
Type: HWND
A handle to the window or control whose text is to be changed.
lpString
Type: LPCTSTR
The new title or control text.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If the target window is owned by the current process, SetWindowText causes a WM_SETTEXT message to be
sent to the specified window or control. If the control is a list box control created with the WS_CAPTION style,
however, SetWindowText sets the text for the control, not for the list box entries.
To set the text of a control in another process, send the WM_SETTEXT message directly instead of calling
SetWindowText .
The SetWindowText function does not expand tab characters (ASCII code 0x09). Tab characters are displayed as
vertical bar (|) characters.
Examples
For an example, see Sending a Message.
NOTE
The winuser.h header defines SetWindowText 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowText
Reference
WM_SETTEXT
Windows
SetWindowTextW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Changes the text of the specified window's title bar (if it has one). If the specified window is a control, the text of
the control is changed. However, SetWindowText cannot change the text of a control in another application.
Syntax
BOOL SetWindowTextW(
HWND hWnd,
LPCWSTR lpString
);
Parameters
hWnd
Type: HWND
A handle to the window or control whose text is to be changed.
lpString
Type: LPCTSTR
The new title or control text.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
If the target window is owned by the current process, SetWindowText causes a WM_SETTEXT message to be
sent to the specified window or control. If the control is a list box control created with the WS_CAPTION style,
however, SetWindowText sets the text for the control, not for the list box entries.
To set the text of a control in another process, send the WM_SETTEXT message directly instead of calling
SetWindowText .
The SetWindowText function does not expand tab characters (ASCII code 0x09). Tab characters are displayed as
vertical bar (|) characters.
Examples
For an example, see Sending a Message.
NOTE
The winuser.h header defines SetWindowText 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetWindowText
Reference
WM_SETTEXT
Windows
ShowOwnedPopups function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL ShowOwnedPopups(
HWND hWnd,
BOOL fShow
);
Parameters
hWnd
Type: HWND
A handle to the window that owns the pop-up windows to be shown or hidden.
fShow
Type: BOOL
If this parameter is TRUE , all hidden pop-up windows are shown. If this parameter is FALSE , all visible pop-up
windows are hidden.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
ShowOwnedPopups shows only windows hidden by a previous call to ShowOwnedPopups . For example, if
a pop-up window is hidden by using the ShowWindow function, subsequently calling ShowOwnedPopups
with the fShow parameter set to TRUE does not cause the window to be shown.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsWindowVisible
Reference
ShowWindow
Windows
ShowWindow function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Syntax
BOOL ShowWindow(
HWND hWnd,
int nCmdShow
);
Parameters
hWnd
Type: HWND
A handle to the window.
nCmdShow
Type: int
Controls how the window is to be shown. This parameter is ignored the first time an application calls
ShowWindow , if the program that launched the application provides a STARTUPINFO structure. Otherwise, the
first time ShowWindow is called, the value should be the value obtained by the WinMain function in its
nCmdShow parameter. In subsequent calls, this parameter can be one of the following values.
VA L UE M EA N IN G
Sets the show state based on the SW_ value specified in the
SW_SHOWDEFAULT STARTUPINFO structure passed to the CreateProcess
10 function by the program that started the application.
Return value
Type: BOOL
If the window was previously visible, the return value is nonzero.
If the window was previously hidden, the return value is zero.
Remarks
To perform certain special effects when showing or hiding a window, use AnimateWindow.
The first time an application calls ShowWindow , it should use the WinMain function's nCmdShow parameter as
its nCmdShow parameter. Subsequent calls to ShowWindow must use one of the values in the given list,
instead of the one specified by the WinMain function's nCmdShow parameter.
As noted in the discussion of the nCmdShow parameter, the nCmdShow value is ignored in the first call to
ShowWindow if the program that launched the application specifies startup information in the structure. In
this case, ShowWindow uses the information specified in the STARTUPINFO structure to show the window. On
subsequent calls, the application must call ShowWindow with nCmdShow set to SW_SHOWDEFAULT to use
the startup information provided by the program that launched the application. This behavior is designed for
the following situations:
Applications create their main window by calling CreateWindow with the WS_VISIBLE flag set.
Applications create their main window by calling CreateWindow with the WS_VISIBLE flag cleared, and later
call ShowWindow with the SW_SHOW flag set to make it visible.
Examples
For an example, see Creating a Main Window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AnimateWindow
Conceptual
CreateProcess
CreateWindow
Other Resources
Reference
STARTUPINFO
ShowOwnedPopups
ShowWindowAsync
WinMain
Windows
ShowWindowAsync function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Sets the show state of a window without waiting for the operation to complete.
Syntax
BOOL ShowWindowAsync(
HWND hWnd,
int nCmdShow
);
Parameters
hWnd
Type: HWND
A handle to the window.
nCmdShow
Type: int
Controls how the window is to be shown. For a list of possible values, see the description of the ShowWindow
function.
Return value
Type: BOOL
If the operation was successfully started, the return value is nonzero.
Remarks
This function posts a show-window event to the message queue of the given window. An application can use
this function to avoid becoming nonresponsive while waiting for a nonresponsive application to finish
processing a show-window event.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
DLL User32.dll
See also
Conceptual
Reference
ShowWindow
Windows
SoundSentry function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL SoundSentry();
Parameters
This function has no parameters.
Return value
Type: BOOL
This function returns one of the following values.
Remarks
Set the notification behavior by calling SystemParametersInfo with the SPI_SETSOUNDSENTRY value.
Requirements
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
Librar y User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-window-l1-1-0 (introduced in Windows
8)
See also
Reference
SOUNDSENTRY
SoundSentryProc
STYLESTRUCT structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagSTYLESTRUCT {
DWORD styleOld;
DWORD styleNew;
} STYLESTRUCT, *LPSTYLESTRUCT;
Members
styleOld
Type: DWORD
The previous styles for a window. For more information, see the Remarks.
styleNew
Type: DWORD
The new styles for a window. For more information, see the Remarks.
Remarks
The styles in styleOld and styleNew can be either the window styles (WS_ ) or the extended window styles
(WS_EX_ ), depending on the wParam of the message that includes STYLESTRUCT .
The styleOld and styleNew members indicate the styles through their bit pattern. Note that several styles are
equal to zero; to detect these styles, test for the negation of their inverse style. For example, to see if
WS_EX_LEFT is set, you test for ~WS_EX_RIGHT .
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
Reference
WM_STYLECHANGED
WM_STYLECHANGING
Windows
SwitchToThisWindow function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
[This function is not intended for general use. It may be altered or unavailable in subsequent versions of
Windows.]
Switches focus to the specified window and brings it to the foreground.
Syntax
void SwitchToThisWindow(
HWND hwnd,
BOOL fUnknown
);
Parameters
hwnd
Type: HWND
A handle to the window.
fUnknown
Type: BOOL
A TRUE for this parameter indicates that the window is being switched to using the Alt/Ctl+Tab key sequence.
This parameter should be FALSE otherwise.
Return value
None
Remarks
This function is typically called to maintain window z-ordering.
This function was not included in the SDK headers and libraries until Windows XP with Service Pack 1 (SP1) and
Windows Server 2003. If you do not have a header file and import library for this function, you can call the
function using LoadLibrary and GetProcAddress.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
IsWindowVisible
Reference
ShowWindow
Windows
SystemParametersInfoA function (winuser.h)
2/1/2021 • 55 minutes to read • Edit Online
Retrieves or sets the value of one of the system-wide parameters. This function can also update the user profile
while setting a parameter.
Syntax
BOOL SystemParametersInfoA(
UINT uiAction,
UINT uiParam,
PVOID pvParam,
UINT fWinIni
);
Parameters
uiAction
Type: UINT
The system-wide parameter to be retrieved or set. The possible values are organized in the following tables of
related parameters:
Accessibility parameters
Desktop parameters
Icon parameters
Input parameters
Menu parameters
Power parameters
Screen saver parameters
Time-out parameters
UI effect parameters
Window parameters
The following are the accessibility parameters.
A C C ESSIB IL IT Y PA RA M ET ER M EA N IN G
Sets the height of the top and bottom edges of the focus
SPI_SETFOCUSBORDERHEIGHT rectangle drawn with DrawFocusRect to the value of the
0x2011 pvParam parameter.
Windows 2000: This parameter is not supported.
Sets the height of the left and right edges of the focus
SPI_SETFOCUSBORDERWIDTH rectangle drawn with DrawFocusRect to the value of the
0x200F pvParam parameter.
Windows 2000: This parameter is not supported.
Do not use.
SPI_SETLOGICALDPIOVERRIDE
0x009F
DESK TO P PA RA M ET ER M EA N IN G
Retrieves the full path of the bitmap file for the desktop
SPI_GETDESKWALLPAPER wallpaper. The pvParam parameter must point to a buffer to
0x0073 receive the null-terminated path string. Set the uiParam
parameter to the size, in characters, of the pvParam buffer.
The returned string will not exceed MAX_PATH characters. If
there is no desktop wallpaper, the returned string is empty.
Sets the size of the work area. The work area is the portion
SPI_SETWORKAREA of the screen not obscured by the system taskbar or by
0x002F application desktop toolbars. The pvParam parameter is a
pointer to a RECT structure that specifies the new work area
rectangle, expressed in virtual screen coordinates. In a
system with multiple display monitors, the function sets the
work area of the monitor that contains the specified
rectangle.
IC O N PA RA M ET ER M EA N IN G
Sets the font that is used for icon titles. The uiParam
SPI_SETICONTITLELOGFONT parameter specifies the size of a LOGFONT structure, and
0x0022 the pvParam parameter must point to a LOGFONT
structure.
The following are the input parameters. They include parameters related to the keyboard, mouse, pen, input
language, and the warning beeper.
IN P UT PA RA M ET ER M EA N IN G
Sets the default input language for the system shell and
SPI_SETDEFAULTINPUTL ANG applications. The specified language must be displayable
0x005A using the current system character set. The pvParam
parameter must point to an HKL variable that contains the
input locale identifier for the default language. For more
information, see Languages, Locales, and Keyboard Layouts.
Sets the double-click time for the mouse to the value of the
SPI_SETDOUBLECLICKTIME uiParam parameter. If the uiParam value is greater than
0x0020 5000 milliseconds, the system sets the double-click time to
5000 milliseconds.
The double-click time is the maximum number of
milliseconds that can occur between the first and second
clicks of a double-click. You can also call the
SetDoubleClickTime function to set the double-click
time. To get the current double-click time, call the
GetDoubleClickTime function.
Sets the hot key set for switching between input languages.
SPI_SETL ANGTOGGLE The uiParam and pvParam parameters are not used. The
0x005B value sets the shortcut keys in the keyboard property sheets
by reading the registry again. The registry must be set
before this flag is used. the path in the registry is
HKEY_CURRENT_USER\Keyboard Layout \Toggle
. Valid values are "1" = ALT+SHIFT, "2" = CTRL+SHIFT,
and "3" = none.
<b>Windows
Server 2003 and Windows XP: </b>The operating
system does not enforce the use of
<b>USER_TIMER_MAXIMUM</b> and
<b>USER_TIMER_MINIMUM</b> until Windows
Server 2003 with SP1 and Windows XP with SP2.
Sets the routing setting for wheel button input. The routing
SPI_SETMOUSEWHEELROUTING setting determines whether wheel button input is sent to
0x201D the app with focus (foreground) or the app under the mouse
cursor.
The pvParam parameter must point to a DWORD
variable that receives the routing option. If the value is
zero or MOUSEWHEEL_ROUTING_FOCUS, mouse wheel
input is delivered to the app with focus. If the value is 1
or MOUSEWHEEL_ROUTING_HYBRID (default), mouse
wheel input is delivered to the app with focus (desktop
apps) or the app under the mouse cursor (Windows
Store apps). Set the uiParam parameter to zero.
Sets the current pen gesture visualization setting. The
SPI_SETPENVISUALIZATION pvParam parameter must point to a ULONG variable that
0x201F identifies the setting. For more information, see Pen
Visualization.
M EN U PA RA M ET ER M EA N IN G
P O W ER PA RA M ET ER M EA N IN G
SC REEN SAVER PA RA M ET ER M EA N IN G
The following are the time-out parameters for applications and services.
T IM E- O UT PA RA M ET ER M EA N IN G
The following are the UI effects. The SPI_SETUIEFFECTS value is used to enable or disable all UI effects at once.
This table contains the complete list of UI effect values.
UI EF F EC T S PA RA M ET ER M EA N IN G
Same as SPI_GETKEYBOARDCUES.
SPI_GETMENUUNDERLINES
0x100A
If SPI_SETTOOLTIPANIMATION is enabled,
SPI_GETTOOLTIPFADE SPI_GETTOOLTIPFADE indicates whether ToolTip
0x1018 animation uses a fade effect or a slide effect. The pvParam
parameter must point to a BOOL variable that receives
TRUE for fade animation or FALSE for slide animation. For
more information on slide and fade effects, see
AnimateWindow.
Same as SPI_SETKEYBOARDCUES.
SPI_SETMENUUNDERLINES
0x100B
W IN DO W PA RA M ET ER M EA N IN G
uiParam
Type: UINT
A parameter whose usage and format depends on the system parameter being queried or set. For more
information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must
specify zero for this parameter.
pvParam
Type: PVOID
A parameter whose usage and format depends on the system parameter being queried or set. For more
information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must
specify NULL for this parameter. For information on the PVOID datatype, see Windows Data Types.
fWinIni
Type: UINT
If a system parameter is being set, specifies whether the user profile is to be updated, and if so, whether the
WM_SETTINGCHANGE message is to be broadcast to all top-level windows to notify them of the change.
This parameter can be zero if you do not want to update the user profile or broadcast the WM_SETTINGCHANGE
message, or it can be one or more of the following values.
VA L UE M EA N IN G
Same as SPIF_SENDCHANGE .
SPIF_SENDWININICHANGE
Return value
Type: BOOL
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
This function is intended for use with applications that allow the user to customize the environment.
A keyboard layout name should be derived from the hexadecimal value of the language identifier corresponding
to the layout. For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is
named "00000409". Variants of U.S. English layout, such as the Dvorak layout, are named "00010409",
"00020409" and so on. For a list of the primary language identifiers and sublanguage identifiers that make up a
language identifier, see the MAKEL ANGID macro.
There is a difference between the High Contrast color scheme and the High Contrast Mode. The High Contrast
color scheme changes the system colors to colors that have obvious contrast; you switch to this color scheme by
using the Display Options in the control panel. The High Contrast Mode, which uses SPI_GETHIGHCONTRAST
and SPI_SETHIGHCONTRAST , advises applications to modify their appearance for visually-impaired users. It
involves such things as audible warning to users and customized color scheme (using the Accessibility Options
in the control panel). For more information, see HIGHCONTRAST. For more information on general accessibility
features, see Accessibility.
During the time that the primary button is held down to activate the Mouse ClickLock feature, the user can
move the mouse. After the primary button is locked down, releasing the primary button does not result in a
WM_LBUTTONUP message. Thus, it will appear to an application that the primary button is still down. Any
subsequent button message releases the primary button, sending a WM_LBUTTONUP message to the
application, thus the button can be unlocked programmatically or through the user clicking any button.
This API is not DPI aware, and should not be used if the calling thread is per-monitor DPI aware. For the DPI-
aware version of this API, see SystemParametersInfoForDPI. For more information on DPI awareness, see the
Windows High DPI documentation.
Examples
The following example uses SystemParametersInfo to double the mouse speed.
#include <windows.h>
#include <stdio.h>
#pragma comment(lib, "user32.lib")
void main()
{
BOOL fResult;
int aMouseInfo[3]; // Array for mouse information
// Double it.
if( fResult )
{
aMouseInfo[2] = 2 * aMouseInfo[2];
NOTE
The winuser.h header defines SystemParametersInfo 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
ACCESSTIMEOUT
ANIMATIONINFO
AUDIODESCRIPTION
FILTERKEYS
HIGHCONTRAST
ICONMETRICS
LOGFONT
MAKELANGID
MINIMIZEDMETRICS
MOUSEKEYS
NONCLIENTMETRICS
RECT
SERIALKEYS
SOUNDSENTRY
STICKYKEYS
SystemParametersInfoForDPI
TOGGLEKEYS
WM_SETTINGCHANGE
Windows Data Types
SystemParametersInfoW function (winuser.h)
2/1/2021 • 55 minutes to read • Edit Online
Retrieves or sets the value of one of the system-wide parameters. This function can also update the user profile
while setting a parameter.
Syntax
BOOL SystemParametersInfoW(
UINT uiAction,
UINT uiParam,
PVOID pvParam,
UINT fWinIni
);
Parameters
uiAction
Type: UINT
The system-wide parameter to be retrieved or set. The possible values are organized in the following tables of
related parameters:
Accessibility parameters
Desktop parameters
Icon parameters
Input parameters
Menu parameters
Power parameters
Screen saver parameters
Time-out parameters
UI effect parameters
Window parameters
The following are the accessibility parameters.
A C C ESSIB IL IT Y PA RA M ET ER M EA N IN G
Sets the height of the top and bottom edges of the focus
SPI_SETFOCUSBORDERHEIGHT rectangle drawn with DrawFocusRect to the value of the
0x2011 pvParam parameter.
Windows 2000: This parameter is not supported.
Sets the height of the left and right edges of the focus
SPI_SETFOCUSBORDERWIDTH rectangle drawn with DrawFocusRect to the value of the
0x200F pvParam parameter.
Windows 2000: This parameter is not supported.
Do not use.
SPI_SETLOGICALDPIOVERRIDE
0x009F
DESK TO P PA RA M ET ER M EA N IN G
Retrieves the full path of the bitmap file for the desktop
SPI_GETDESKWALLPAPER wallpaper. The pvParam parameter must point to a buffer to
0x0073 receive the null-terminated path string. Set the uiParam
parameter to the size, in characters, of the pvParam buffer.
The returned string will not exceed MAX_PATH characters. If
there is no desktop wallpaper, the returned string is empty.
Sets the size of the work area. The work area is the portion
SPI_SETWORKAREA of the screen not obscured by the system taskbar or by
0x002F application desktop toolbars. The pvParam parameter is a
pointer to a RECT structure that specifies the new work area
rectangle, expressed in virtual screen coordinates. In a
system with multiple display monitors, the function sets the
work area of the monitor that contains the specified
rectangle.
IC O N PA RA M ET ER M EA N IN G
Sets the font that is used for icon titles. The uiParam
SPI_SETICONTITLELOGFONT parameter specifies the size of a LOGFONT structure, and
0x0022 the pvParam parameter must point to a LOGFONT
structure.
The following are the input parameters. They include parameters related to the keyboard, mouse, pen, input
language, and the warning beeper.
IN P UT PA RA M ET ER M EA N IN G
Sets the default input language for the system shell and
SPI_SETDEFAULTINPUTL ANG applications. The specified language must be displayable
0x005A using the current system character set. The pvParam
parameter must point to an HKL variable that contains the
input locale identifier for the default language. For more
information, see Languages, Locales, and Keyboard Layouts.
Sets the double-click time for the mouse to the value of the
SPI_SETDOUBLECLICKTIME uiParam parameter. If the uiParam value is greater than
0x0020 5000 milliseconds, the system sets the double-click time to
5000 milliseconds.
The double-click time is the maximum number of
milliseconds that can occur between the first and second
clicks of a double-click. You can also call the
SetDoubleClickTime function to set the double-click
time. To get the current double-click time, call the
GetDoubleClickTime function.
Sets the hot key set for switching between input languages.
SPI_SETL ANGTOGGLE The uiParam and pvParam parameters are not used. The
0x005B value sets the shortcut keys in the keyboard property sheets
by reading the registry again. The registry must be set
before this flag is used. the path in the registry is
HKEY_CURRENT_USER\Keyboard Layout \Toggle
. Valid values are "1" = ALT+SHIFT, "2" = CTRL+SHIFT,
and "3" = none.
<b>Windows
Server 2003 and Windows XP: </b>The operating
system does not enforce the use of
<b>USER_TIMER_MAXIMUM</b> and
<b>USER_TIMER_MINIMUM</b> until Windows
Server 2003 with SP1 and Windows XP with SP2.
Sets the routing setting for wheel button input. The routing
SPI_SETMOUSEWHEELROUTING setting determines whether wheel button input is sent to
0x201D the app with focus (foreground) or the app under the mouse
cursor.
The pvParam parameter must point to a DWORD
variable that receives the routing option. If the value is
zero or MOUSEWHEEL_ROUTING_FOCUS, mouse wheel
input is delivered to the app with focus. If the value is 1
or MOUSEWHEEL_ROUTING_HYBRID (default), mouse
wheel input is delivered to the app with focus (desktop
apps) or the app under the mouse cursor (Windows
Store apps). Set the uiParam parameter to zero.
Sets the current pen gesture visualization setting. The
SPI_SETPENVISUALIZATION pvParam parameter must point to a ULONG variable that
0x201F identifies the setting. For more information, see Pen
Visualization.
M EN U PA RA M ET ER M EA N IN G
P O W ER PA RA M ET ER M EA N IN G
SC REEN SAVER PA RA M ET ER M EA N IN G
The following are the time-out parameters for applications and services.
T IM E- O UT PA RA M ET ER M EA N IN G
The following are the UI effects. The SPI_SETUIEFFECTS value is used to enable or disable all UI effects at once.
This table contains the complete list of UI effect values.
UI EF F EC T S PA RA M ET ER M EA N IN G
Same as SPI_GETKEYBOARDCUES.
SPI_GETMENUUNDERLINES
0x100A
If SPI_SETTOOLTIPANIMATION is enabled,
SPI_GETTOOLTIPFADE SPI_GETTOOLTIPFADE indicates whether ToolTip
0x1018 animation uses a fade effect or a slide effect. The pvParam
parameter must point to a BOOL variable that receives
TRUE for fade animation or FALSE for slide animation. For
more information on slide and fade effects, see
AnimateWindow.
Same as SPI_SETKEYBOARDCUES.
SPI_SETMENUUNDERLINES
0x100B
W IN DO W PA RA M ET ER M EA N IN G
uiParam
Type: UINT
A parameter whose usage and format depends on the system parameter being queried or set. For more
information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must
specify zero for this parameter.
pvParam
Type: PVOID
A parameter whose usage and format depends on the system parameter being queried or set. For more
information about system-wide parameters, see the uiAction parameter. If not otherwise indicated, you must
specify NULL for this parameter. For information on the PVOID datatype, see Windows Data Types.
fWinIni
Type: UINT
If a system parameter is being set, specifies whether the user profile is to be updated, and if so, whether the
WM_SETTINGCHANGE message is to be broadcast to all top-level windows to notify them of the change.
This parameter can be zero if you do not want to update the user profile or broadcast the WM_SETTINGCHANGE
message, or it can be one or more of the following values.
VA L UE M EA N IN G
Same as SPIF_SENDCHANGE .
SPIF_SENDWININICHANGE
Return value
Type: BOOL
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
This function is intended for use with applications that allow the user to customize the environment.
A keyboard layout name should be derived from the hexadecimal value of the language identifier corresponding
to the layout. For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is
named "00000409". Variants of U.S. English layout, such as the Dvorak layout, are named "00010409",
"00020409" and so on. For a list of the primary language identifiers and sublanguage identifiers that make up a
language identifier, see the MAKEL ANGID macro.
There is a difference between the High Contrast color scheme and the High Contrast Mode. The High Contrast
color scheme changes the system colors to colors that have obvious contrast; you switch to this color scheme by
using the Display Options in the control panel. The High Contrast Mode, which uses SPI_GETHIGHCONTRAST
and SPI_SETHIGHCONTRAST , advises applications to modify their appearance for visually-impaired users. It
involves such things as audible warning to users and customized color scheme (using the Accessibility Options
in the control panel). For more information, see HIGHCONTRAST. For more information on general accessibility
features, see Accessibility.
During the time that the primary button is held down to activate the Mouse ClickLock feature, the user can
move the mouse. After the primary button is locked down, releasing the primary button does not result in a
WM_LBUTTONUP message. Thus, it will appear to an application that the primary button is still down. Any
subsequent button message releases the primary button, sending a WM_LBUTTONUP message to the
application, thus the button can be unlocked programmatically or through the user clicking any button.
This API is not DPI aware, and should not be used if the calling thread is per-monitor DPI aware. For the DPI-
aware version of this API, see SystemParametersInfoForDPI. For more information on DPI awareness, see the
Windows High DPI documentation.
Examples
The following example uses SystemParametersInfo to double the mouse speed.
#include <windows.h>
#include <stdio.h>
#pragma comment(lib, "user32.lib")
void main()
{
BOOL fResult;
int aMouseInfo[3]; // Array for mouse information
// Double it.
if( fResult )
{
aMouseInfo[2] = 2 * aMouseInfo[2];
NOTE
The winuser.h header defines SystemParametersInfo 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
ACCESSTIMEOUT
ANIMATIONINFO
AUDIODESCRIPTION
FILTERKEYS
HIGHCONTRAST
ICONMETRICS
LOGFONT
MAKELANGID
MINIMIZEDMETRICS
MOUSEKEYS
NONCLIENTMETRICS
RECT
SERIALKEYS
SOUNDSENTRY
STICKYKEYS
SystemParametersInfoForDPI
TOGGLEKEYS
WM_SETTINGCHANGE
Windows Data Types
TileWindows function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
WORD TileWindows(
HWND hwndParent,
UINT wHow,
const RECT *lpRect,
UINT cKids,
const HWND *lpKids
);
Parameters
hwndParent
Type: HWND
A handle to the parent window. If this parameter is NULL , the desktop window is assumed.
wHow
Type: UINT
The tiling flags. This parameter can be one of the following values—optionally combined with
MDITILE_SKIPDISABLED to prevent disabled MDI child windows from being tiled.
VA L UE M EA N IN G
lpRect
Type: UINT
The number of elements in the array specified by the lpKids parameter. This parameter is ignored if lpKids is
NULL .
lpKids
Return value
Type: WORD
If the function succeeds, the return value is the number of windows arranged.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Calling TileWindows causes all maximized windows to be restored to their previous size.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
CascadeWindows
Conceptual
Other Resources
RECT
Reference
Windows
TIMERPROC callback function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
An application-defined callback function that processes WM_TIMER messages. The TIMERPROC type defines a
pointer to this callback function. TimerProc is a placeholder for the application-defined function name.
Syntax
TIMERPROC Timerproc;
void Timerproc(
HWND Arg1,
UINT Arg2,
UINT_PTR Arg3,
DWORD Arg4
)
{...}
Parameters
Arg1
Type: HWND
A handle to the window associated with the timer.
Arg2
Type: UINT
The WM_TIMER message.
Arg3
Type: UINT_PTR
The timer's identifier.
Arg4
Type: DWORD
The number of milliseconds that have elapsed since the system was started. This is the value returned by the
GetTickCount function.
Return value
None
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
KillTimer
Reference
SetTimer
Timers
WM_TIMER
TITLEBARINFO structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagTITLEBARINFO {
DWORD cbSize;
RECT rcTitleBar;
DWORD rgstate[CCHILDREN_TITLEBAR + 1];
} TITLEBARINFO, *PTITLEBARINFO, *LPTITLEBARINFO;
Members
cbSize
Type: DWORD
The size, in bytes, of the structure. The caller must set this member to sizeof(TITLEBARINFO) .
rcTitleBar
Type: RECT
The coordinates of the title bar. These coordinates include all title-bar elements except the window menu.
rgstate
Type: DWORD[CCHILDREN_TITLEBAR+1]
An array that receives a value for each element of the title bar. The following are the title bar elements
represented by the array.
IN DEX T IT L E B A R EL EM EN T
1 Reserved.
2 Minimize button.
3 Maximize button.
4 Help button.
5 Close button.
VA L UE M EA N IN G
The element can accept the focus.
STATE_SYSTEM_FOCUSABLE
0x00100000
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GetTitleBarInfo
Reference
Windows
TITLEBARINFOEX structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Expands on the information described in the TITLEBARINFO structure by including the coordinates of each
element of the title bar.
This structure is sent with the WM_GETTITLEBARINFOEX message.
Syntax
typedef struct tagTITLEBARINFOEX {
DWORD cbSize;
RECT rcTitleBar;
DWORD rgstate[CCHILDREN_TITLEBAR + 1];
RECT rgrect[CCHILDREN_TITLEBAR + 1];
} TITLEBARINFOEX, *PTITLEBARINFOEX, *LPTITLEBARINFOEX;
Members
cbSize
Type: DWORD
The size of the structure, in bytes. Set this member to sizeof(TITLEBARINFOEX) before sending with the
WM_GETTITLEBARINFOEX message.
rcTitleBar
Type: RECT
The bounding rectangle of the title bar. The rectangle is expressed in screen coordinates and includes all titlebar
elements except the window menu.
rgstate
Type: DWORD[CCHILDREN_TITLEBAR+1]
An array that receives a DWORD value for each element of the title bar. The following are the title bar elements
represented by the array.
IN DEX T IT L E B A R EL EM EN T
1 Reserved.
2 Minimize button.
3 Maximize button.
4 Help button.
5 Close button.
VA L UE M EA N IN G
rgrect
IN DEX T IT L E B A R EL EM EN T
0 Reserved.
1 Reserved.
2 Minimize button.
3 Maximize button.
4 Help button.
5 Close button.
Requirements
See also
Conceptual
Reference
WM_GETTITLEBARINFOEX
Windows
TranslateMDISysAccel function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Processes accelerator keystrokes for window menu commands of the multiple-document interface (MDI) child
windows associated with the specified MDI client window. The function translates WM_KEYUP and
WM_KEYDOWN messages to WM_SYSCOMMAND messages and sends them to the appropriate MDI child
windows.
Syntax
BOOL TranslateMDISysAccel(
HWND hWndClient,
LPMSG lpMsg
);
Parameters
hWndClient
Type: HWND
A handle to the MDI client window.
lpMsg
Type: LPMSG
A pointer to a message retrieved by using the GetMessage or PeekMessage function. The message must be an
MSG structure and contain message information from the application's message queue.
Return value
Type: BOOL
If the message is translated into a system command, the return value is nonzero.
If the message is not translated into a system command, the return value is zero.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
MSG
Multiple Document Interface
PeekMessage
Reference
TranslateAccelerator
WM_KEYDOWN
WM_KEYUP
WM_SYSCOMMAND
TranslateMessage function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Translates virtual-key messages into character messages. The character messages are posted to the calling
thread's message queue, to be read the next time the thread calls the GetMessage or PeekMessage function.
Syntax
BOOL TranslateMessage(
const MSG *lpMsg
);
Parameters
lpMsg
Return value
Type: BOOL
If the message is translated (that is, a character message is posted to the thread's message queue), the return
value is nonzero.
If the message is WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, or WM_SYSKEYUP, the return value is
nonzero, regardless of the translation.
If the message is not translated (that is, a character message is not posted to the thread's message queue), the
return value is zero.
Remarks
The TranslateMessage function does not modify the message pointed to by the lpMsg parameter.
WM_KEYDOWN and WM_KEYUP combinations produce a WM_CHAR or WM_DEADCHAR message.
WM_SYSKEYDOWN and WM_SYSKEYUP combinations produce a WM_SYSCHAR or WM_SYSDEADCHAR
message.
TranslateMessage produces WM_CHAR messages only for keys that are mapped to ASCII characters by the
keyboard driver.
If applications process virtual-key messages for some other purpose, they should not call TranslateMessage .
For instance, an application should not call TranslateMessage if the TranslateAccelerator function returns a
nonzero value. Note that the application is responsible for retrieving and dispatching input messages to the
dialog box. Most applications use the main message loop for this. However, to permit the user to move to and to
select controls by using the keyboard, the application must call IsDialogMessage. For more information, see
Dialog Box Keyboard Interface.
Examples
For an example, see Creating a Message Loop.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
GetMessage
IsDialogMessage
Messages and Message Queues
PeekMessage
Reference
TranslateAccelerator
WM_CHAR
WM_DEADCHAR
WM_KEYDOWN
WM_KEYUP
WM_SYSCHAR
WM_SYSDEADCHAR
WM_SYSKEYDOWN
WM_SYSKEYUP
UnhookWindowsHookEx function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
BOOL UnhookWindowsHookEx(
HHOOK hhk
);
Parameters
hhk
Type: HHOOK
A handle to the hook to be removed. This parameter is a hook handle obtained by a previous call to
SetWindowsHookEx.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The hook procedure can be in the state of being called by another thread even after UnhookWindowsHookEx
returns. If the hook procedure is not being called concurrently, the hook procedure is removed immediately
before UnhookWindowsHookEx returns.
Examples
For an example, see Monitoring System Events.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Hooks
Reference
SetWindowsHookEx
UnregisterClassA function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Unregisters a window class, freeing the memory required for the class.
Syntax
BOOL UnregisterClassA(
LPCSTR lpClassName,
HINSTANCE hInstance
);
Parameters
lpClassName
Type: LPCTSTR
A null-terminated string or a class atom. If lpClassName is a string, it specifies the window class name. This class
name must have been registered by a previous call to the RegisterClass or RegisterClassEx function. System
classes, such as dialog box controls, cannot be unregistered. If this parameter is an atom, it must be a class atom
created by a previous call to the RegisterClass or RegisterClassEx function. The atom must be in the low-
order word of lpClassName; the high-order word must be zero.
hInstance
Type: HINSTANCE
A handle to the instance of the module that created the class.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the class could not be found or if a window still exists that was created with the class, the return value is zero.
To get extended error information, call GetLastError.
Remarks
Before calling this function, an application must destroy all windows created with the specified class.
All window classes that an application registers are unregistered when it terminates.
Class atoms are special atoms returned only by RegisterClass and RegisterClassEx.
No window classes registered by a DLL are unregistered when the .dll is unloaded.
NOTE
The winuser.h header defines UnregisterClass 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
RegisterClass
RegisterClassEx
Window Classes
UnregisterClassW function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Unregisters a window class, freeing the memory required for the class.
Syntax
BOOL UnregisterClassW(
LPCWSTR lpClassName,
HINSTANCE hInstance
);
Parameters
lpClassName
Type: LPCTSTR
A null-terminated string or a class atom. If lpClassName is a string, it specifies the window class name. This class
name must have been registered by a previous call to the RegisterClass or RegisterClassEx function. System
classes, such as dialog box controls, cannot be unregistered. If this parameter is an atom, it must be a class atom
created by a previous call to the RegisterClass or RegisterClassEx function. The atom must be in the low-
order word of lpClassName; the high-order word must be zero.
hInstance
Type: HINSTANCE
A handle to the instance of the module that created the class.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the class could not be found or if a window still exists that was created with the class, the return value is zero.
To get extended error information, call GetLastError.
Remarks
Before calling this function, an application must destroy all windows created with the specified class.
All window classes that an application registers are unregistered when it terminates.
Class atoms are special atoms returned only by RegisterClass and RegisterClassEx.
No window classes registered by a DLL are unregistered when the .dll is unloaded.
NOTE
The winuser.h header defines UnregisterClass 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
Conceptual
Reference
RegisterClass
RegisterClassEx
Window Classes
UpdateLayeredWindow function (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Updates the position, size, shape, content, and translucency of a layered window.
Syntax
BOOL UpdateLayeredWindow(
HWND hWnd,
HDC hdcDst,
POINT *pptDst,
SIZE *psize,
HDC hdcSrc,
POINT *pptSrc,
COLORREF crKey,
BLENDFUNCTION *pblend,
DWORD dwFlags
);
Parameters
hWnd
Type: HWND
A handle to a layered window. A layered window is created by specifying WS_EX_L AYERED when creating the
window with the CreateWindowEx function.
Windows 8: The WS_EX_L AYERED style is supported for top-level windows and child windows. Previous
Windows versions support WS_EX_L AYERED only for top-level windows.
hdcDst
Type: HDC
A handle to a DC for the screen. This handle is obtained by specifying NULL when calling the function. It is used
for palette color matching when the window contents are updated. If hdcDst isNULL , the default palette will be
used.
If hdcSrc is NULL , hdcDst must be NULL .
pptDst
Type: POINT *
A pointer to a structure that specifies the new screen position of the layered window. If the current position is
not changing, pptDst can be NULL .
psize
Type: SIZE *
A pointer to a structure that specifies the new size of the layered window. If the size of the window is not
changing, psize can be NULL . If hdcSrc is NULL , psize must be NULL .
hdcSrc
Type: HDC
A handle to a DC for the surface that defines the layered window. This handle can be obtained by calling the
CreateCompatibleDC function. If the shape and visual context of the window are not changing, hdcSrc can be
NULL .
pptSrc
Type: POINT *
A pointer to a structure that specifies the location of the layer in the device context. If hdcSrc is NULL , pptSrc
should be NULL .
crKey
Type: COLORREF
A structure that specifies the color key to be used when composing the layered window. To generate a
COLORREF, use the RGB macro.
pblend
Type: BLENDFUNCTION *
A pointer to a structure that specifies the transparency value to be used when composing the layered window.
dwFlags
Type: DWORD
This parameter can be one of the following values.
VA L UE M EA N IN G
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The source DC should contain the surface that defines the visible contents of the layered window. For example,
you can select a bitmap into a device context obtained by calling the CreateCompatibleDC function.
An application should call SetLayout on the hdcSrc device context to properly set the mirroring mode.
SetLayout will properly mirror all drawing into an HDC while properly preserving text glyph and (optionally)
bitmap direction order. It cannot modify drawing directly into the bits of a device-independent bitmap (DIB). For
more information, see Window Layout and Mirroring.
The UpdateLayeredWindow function maintains the window's appearance on the screen. The windows
underneath a layered window do not need to be repainted when they are uncovered due to a call to
UpdateLayeredWindow , because the system will automatically repaint them. This permits seamless animation
of the layered window.
UpdateLayeredWindow always updates the entire window. To update part of a window, use the traditional
WM_PAINT and set the blend value using SetLayeredWindowAttributes.
For best drawing performance by the layered window and any underlying windows, the layered window should
be as small as possible. An application should also process the message and re-create its layered windows when
the display's color depth changes.
For more information, see Layered Windows.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
See also
AlphaBlend
Conceptual
CreateCompatibleBitmap
Other Resources
Reference
SetWindowLong
SetWindowPos
TransparentBlt
UpdateLayeredWindowIndirect
Windows
UPDATELAYEREDWINDOWINFO structure
(winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Used by UpdateLayeredWindowIndirect to provide position, size, shape, content, and translucency information
for a layered window.
Syntax
typedef struct tagUPDATELAYEREDWINDOWINFO {
DWORD cbSize;
HDC hdcDst;
const POINT *pptDst;
const SIZE *psize;
HDC hdcSrc;
const POINT *pptSrc;
COLORREF crKey;
const BLENDFUNCTION *pblend;
DWORD dwFlags;
const RECT *prcDirty;
} UPDATELAYEREDWINDOWINFO, *PUPDATELAYEREDWINDOWINFO;
Members
cbSize
Type: DWORD
The size, in bytes, of this structure.
hdcDst
Type: HDC
A handle to a DC for the screen. This handle is obtained by specifying NULL in this member when calling
UpdateLayeredWindowIndirect. The handle is used for palette color matching when the window contents are
updated. If hdcDst is NULL , the default palette is used.
If hdcSrc is NULL , hdcDst must be NULL .
pptDst
Type: COLORREF
The color key to be used when composing the layered window. To generate a COLORREF, use the RGB macro.
pblend
Type: DWORD
This parameter can be one of the following values.
VA L UE M EA N IN G
Requirements
Minimum suppor ted client Windows Vista [desktop apps only]
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
See also
Conceptual
Reference
UpdateLayeredWindow
Window Features
WaitMessage function (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Yields control to other threads when a thread has no other messages in its message queue. The WaitMessage
function suspends the thread and does not return until a new message is placed in the thread's message queue.
Syntax
BOOL WaitMessage();
Parameters
This function has no parameters.
Return value
Type: BOOL
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Note that WaitMessage does not return if there is unread input in the message queue after the thread has
called a function to check the queue. This is because functions such as PeekMessage, GetMessage,
GetQueueStatus, WaitMessage , MsgWaitForMultipleObjects, and MsgWaitForMultipleObjectsEx check the
queue and then change the state information for the queue so that the input is no longer considered new. A
subsequent call to WaitMessage will not return until new input of the specified type arrives. The existing
unread input (received prior to the last time the thread checked the queue) is ignored.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
Retrieves a handle to the window that contains the specified physical point.
Syntax
HWND WindowFromPhysicalPoint(
POINT Point
);
Parameters
Point
Type: POINT
The physical coordinates of the point.
Return value
Type: HWND
A handle to the window that contains the given physical point. If no window exists at the point, this value is
NULL .
Remarks
The WindowFromPhysicalPoint function does not retrieve a handle to a hidden or disabled window, even if
the point is within the window.
Requirements
Minimum suppor ted ser ver Windows Server 2008 [desktop apps only]
Librar y User32.lib
DLL User32.dll
Syntax
HWND WindowFromPoint(
POINT Point
);
Parameters
Point
Type: POINT
The point to be checked.
Return value
Type: HWND
The return value is a handle to the window that contains the point. If no window exists at the given point, the
return value is NULL . If the point is over a static text control, the return value is a handle to the window under
the static text control.
Remarks
The WindowFromPoint function does not retrieve a handle to a hidden or disabled window, even if the point is
within the window. An application should use the ChildWindowFromPoint function for a nonrestrictive search.
Examples
For an example, see "Interface from Running Object Table" in About Text Object Model.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
Librar y User32.lib
DLL User32.dll
API set ext-ms-win-ntuser-window-l1-1-1 (introduced in Windows
8.1)
See also
ChildWindowFromPoint
Conceptual
Other Resources
POINT
Reference
WindowFromDC
Windows
WINDOWINFO structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagWINDOWINFO {
DWORD cbSize;
RECT rcWindow;
RECT rcClient;
DWORD dwStyle;
DWORD dwExStyle;
DWORD dwWindowStatus;
UINT cxWindowBorders;
UINT cyWindowBorders;
ATOM atomWindowType;
WORD wCreatorVersion;
} WINDOWINFO, *PWINDOWINFO, *LPWINDOWINFO;
Members
cbSize
Type: DWORD
The size of the structure, in bytes. The caller must set this member to sizeof(WINDOWINFO) .
rcWindow
Type: RECT
The coordinates of the window.
rcClient
Type: RECT
The coordinates of the client area.
dwStyle
Type: DWORD
The window styles. For a table of window styles, see Window Styles.
dwExStyle
Type: DWORD
The extended window styles. For a table of extended window styles, see Extended Window Styles.
dwWindowStatus
Type: DWORD
The window status. If this member is WS_ACTIVECAPTION (0x0001), the window is active. Otherwise, this
member is zero.
cxWindowBorders
Type: UINT
The width of the window border, in pixels.
cyWindowBorders
Type: UINT
The height of the window border, in pixels.
atomWindowType
Type: ATOM
The window class atom (see RegisterClass).
wCreatorVersion
Type: WORD
The Windows version of the application that created the window.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
CreateWindowEx
GetWindowInfo
Reference
RegisterClass
Windows
WINDOWPLACEMENT structure (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Syntax
typedef struct tagWINDOWPLACEMENT {
UINT length;
UINT flags;
UINT showCmd;
POINT ptMinPosition;
POINT ptMaxPosition;
RECT rcNormalPosition;
RECT rcDevice;
} WINDOWPLACEMENT;
Members
length
Type: UINT
The length of the structure, in bytes. Before calling the GetWindowPlacement or SetWindowPlacement functions,
set this member to sizeof(WINDOWPLACEMENT) .
GetWindowPlacement and SetWindowPlacement fail if this member is not set correctly.
flags
Type: UINT
The flags that control the position of the minimized window and the method by which the window is restored.
This member can be one or more of the following values.
VA L UE M EA N IN G
If the calling thread and the thread that owns the window
WPF_ASYNCWINDOWPL ACEMENT are attached to different input queues, the system posts the
0x0004 request to the thread that owns the window. This prevents
the calling thread from blocking its execution while other
threads process the request.
Type: UINT
The current show state of the window. This member can be one of the following values.
VA L UE M EA N IN G
Type: POINT
The coordinates of the window's upper-left corner when the window is minimized.
ptMaxPosition
Type: POINT
The coordinates of the window's upper-left corner when the window is maximized.
rcNormalPosition
Type: RECT
The window's coordinates when the window is in the restored position.
rcDevice
Remarks
If the window is a top-level window that does not have the WS_EX_TOOLWINDOW window style, then the
coordinates represented by the following members are in workspace coordinates: ptMinPosition ,
ptMaxPosition , and rcNormalPosition . Otherwise, these members are in screen coordinates.
Workspace coordinates differ from screen coordinates in that they take the locations and sizes of application
toolbars (including the taskbar) into account. Workspace coordinate (0,0) is the upper-left corner of the
workspace area, the area of the screen not being used by application toolbars.
The coordinates used in a WINDOWPL ACEMENT structure should be used only by the GetWindowPlacement
and SetWindowPlacement functions. Passing workspace coordinates to functions which expect screen
coordinates (such as SetWindowPos) will result in the window appearing in the wrong location. For example, if
the taskbar is at the top of the screen, saving window coordinates using GetWindowPlacement and restoring
them using SetWindowPos causes the window to appear to "creep" up the screen.
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GetWindowPlacement
POINT
RECT
Reference
SetWindowPlacement
SetWindowPos
ShowWindow
Windows
WINDOWPOS structure (winuser.h)
2/1/2021 • 2 minutes to read • Edit Online
Syntax
typedef struct tagWINDOWPOS {
HWND hwnd;
HWND hwndInsertAfter;
int x;
int y;
int cx;
int cy;
UINT flags;
} WINDOWPOS, *LPWINDOWPOS, *PWINDOWPOS;
Members
hwnd
Type: HWND
A handle to the window.
hwndInsertAfter
Type: HWND
The position of the window in Z order (front-to-back position). This member can be a handle to the window
behind which this window is placed, or can be one of the special values listed with the SetWindowPos function.
x
Type: int
The position of the left edge of the window.
y
Type: int
The position of the top edge of the window.
cx
Type: int
The window width, in pixels.
cy
Type: int
The window height, in pixels.
flags
Type: UINT
The window position. This member can be one or more of the following values.
VA L UE M EA N IN G
Does not activate the window. If this flag is not set, the
SWP_NOACTIVATE window is activated and moved to the top of either the
0x0010 topmost or non-topmost group (depending on the setting
of the hwndInser tAfter member).
Requirements
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
EndDeferWindowPos
Reference
SetWindowPos
WM_NCCALCSIZE
Windows
WNDCLASSA structure (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Contains the window class attributes that are registered by the RegisterClass function.
This structure has been superseded by the WNDCLASSEX structure used with the RegisterClassEx function. You
can still use WNDCL ASS and RegisterClass if you do not need to set the small icon associated with the window
class.
Syntax
typedef struct tagWNDCLASSA {
UINT style;
WNDPROC lpfnWndProc;
int cbClsExtra;
int cbWndExtra;
HINSTANCE hInstance;
HICON hIcon;
HCURSOR hCursor;
HBRUSH hbrBackground;
LPCSTR lpszMenuName;
LPCSTR lpszClassName;
} WNDCLASSA, *PWNDCLASSA, *NPWNDCLASSA, *LPWNDCLASSA;
Members
style
Type: UINT
The class style(s). This member can be any combination of the Class Styles.
lpfnWndProc
Type: WNDPROC
A pointer to the window procedure. You must use the CallWindowProc function to call the window procedure.
For more information, see WindowProc.
cbClsExtra
Type: int
The number of extra bytes to allocate following the window-class structure. The system initializes the bytes to
zero.
cbWndExtra
Type: int
The number of extra bytes to allocate following the window instance. The system initializes the bytes to zero. If
an application uses WNDCL ASS to register a dialog box created by using the CL ASS directive in the resource
file, it must set this member to DLGWINDOWEXTRA .
hInstance
Type: HINSTANCE
A handle to the instance that contains the window procedure for the class.
hIcon
Type: HICON
A handle to the class icon. This member must be a handle to an icon resource. If this member is NULL , the
system provides a default icon.
hCursor
Type: HCURSOR
A handle to the class cursor. This member must be a handle to a cursor resource. If this member is NULL , an
application must explicitly set the cursor shape whenever the mouse moves into the application's window.
hbrBackground
Type: HBRUSH
A handle to the class background brush. This member can be a handle to the physical brush to be used for
painting the background, or it can be a color value. A color value must be one of the following standard system
colors (the value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the
following HBRUSH types:
COLOR_ACTIVEBORDER
COLOR_ACTIVECAPTION
COLOR_APPWORKSPACE
COLOR_BACKGROUND
COLOR_BTNFACE
COLOR_BTNSHADOW
COLOR_BTNTEXT
COLOR_CAPTIONTEXT
COLOR_GRAYTEXT
COLOR_HIGHLIGHT
COLOR_HIGHLIGHTTEXT
COLOR_INACTIVEBORDER
COLOR_INACTIVECAPTION
COLOR_MENU
COLOR_MENUTEXT
COLOR_SCROLLBAR
COLOR_WINDOW
COLOR_WINDOWFRAME
COLOR_WINDOWTEXT
The system automatically deletes class background brushes when the class is unregistered by using
UnregisterClass. An application should not delete these brushes.
When this member is NULL , an application must paint its own background whenever it is requested to paint in
its client area. To determine whether the background must be painted, an application can either process the
WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint
function.
lpszMenuName
Type: LPCTSTR
The resource name of the class menu, as the name appears in the resource file. If you use an integer to identify
the menu, use the MAKEINTRESOURCE macro. If this member is NULL , windows belonging to this class have no
default menu.
lpszClassName
Type: LPCTSTR
A pointer to a null-terminated string or is an atom. If this parameter is an atom, it must be a class atom created
by a previous call to the RegisterClass or RegisterClassEx function. The atom must be in the low-order word of
lpszClassName ; the high-order word must be zero.
If lpszClassName 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.
The maximum length for lpszClassName is 256. If lpszClassName is greater than the maximum length, the
RegisterClass function will fail.
Remarks
NOTE
The winuser.h header defines WNDCLASS 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
BeginPaint
Conceptual
CreateWindow
CreateWindowEx
GetDC
MAKEINTRESOURCE
Other Resources
PAINTSTRUCT
Reference
RegisterClass
UnregisterClass
WM_PAINT
WNDCLASSEX
Window Classes
WindowProc
WNDCLASSEXA structure (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Contains window class information. It is used with the RegisterClassEx and GetClassInfoEx functions.
The WNDCL ASSEX structure is similar to the WNDCLASS structure. There are two differences. WNDCL ASSEX
includes the cbSize member, which specifies the size of the structure, and the hIconSm member, which
contains a handle to a small icon associated with the window class.
Syntax
typedef struct tagWNDCLASSEXA {
UINT cbSize;
UINT style;
WNDPROC lpfnWndProc;
int cbClsExtra;
int cbWndExtra;
HINSTANCE hInstance;
HICON hIcon;
HCURSOR hCursor;
HBRUSH hbrBackground;
LPCSTR lpszMenuName;
LPCSTR lpszClassName;
HICON hIconSm;
} WNDCLASSEXA, *PWNDCLASSEXA, *NPWNDCLASSEXA, *LPWNDCLASSEXA;
Members
cbSize
Type: UINT
The size, in bytes, of this structure. Set this member to sizeof(WNDCLASSEX) . Be sure to set this member before
calling the GetClassInfoEx function.
style
Type: UINT
The class style(s). This member can be any combination of the Class Styles.
lpfnWndProc
Type: WNDPROC
A pointer to the window procedure. You must use the CallWindowProc function to call the window procedure.
For more information, see WindowProc.
cbClsExtra
Type: int
The number of extra bytes to allocate following the window-class structure. The system initializes the bytes to
zero.
cbWndExtra
Type: int
The number of extra bytes to allocate following the window instance. The system initializes the bytes to zero. If
an application uses WNDCL ASSEX to register a dialog box created by using the CL ASS directive in the
resource file, it must set this member to DLGWINDOWEXTRA .
hInstance
Type: HINSTANCE
A handle to the instance that contains the window procedure for the class.
hIcon
Type: HICON
A handle to the class icon. This member must be a handle to an icon resource. If this member is NULL , the
system provides a default icon.
hCursor
Type: HCURSOR
A handle to the class cursor. This member must be a handle to a cursor resource. If this member is NULL , an
application must explicitly set the cursor shape whenever the mouse moves into the application's window.
hbrBackground
Type: HBRUSH
A handle to the class background brush. This member can be a handle to the brush to be used for painting the
background, or it can be a color value. A color value must be one of the following standard system colors (the
value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the following
HBRUSH types:
COLOR_ACTIVEBORDER
COLOR_ACTIVECAPTION
COLOR_APPWORKSPACE
COLOR_BACKGROUND
COLOR_BTNFACE
COLOR_BTNSHADOW
COLOR_BTNTEXT
COLOR_CAPTIONTEXT
COLOR_GRAYTEXT
COLOR_HIGHLIGHT
COLOR_HIGHLIGHTTEXT
COLOR_INACTIVEBORDER
COLOR_INACTIVECAPTION
COLOR_MENU
COLOR_MENUTEXT
COLOR_SCROLLBAR
COLOR_WINDOW
COLOR_WINDOWFRAME
COLOR_WINDOWTEXT
The system automatically deletes class background brushes when the class is unregistered by using
UnregisterClass. An application should not delete these brushes.
When this member is NULL , an application must paint its own background whenever it is requested to paint in
its client area. To determine whether the background must be painted, an application can either process the
WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint
function.
lpszMenuName
Type: LPCTSTR
Pointer to a null-terminated character string that specifies the resource name of the class menu, as the name
appears in the resource file. If you use an integer to identify the menu, use the MAKEINTRESOURCE macro. If
this member is NULL , windows belonging to this class have no default menu.
lpszClassName
Type: LPCTSTR
A pointer to a null-terminated string or is an atom. If this parameter is an atom, it must be a class atom created
by a previous call to the RegisterClass or RegisterClassEx function. The atom must be in the low-order word of
lpszClassName ; the high-order word must be zero.
If lpszClassName 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.
The maximum length for lpszClassName is 256. If lpszClassName is greater than the maximum length, the
RegisterClassEx function will fail.
hIconSm
Type: HICON
A handle to a small icon that is associated with the window class. If this member is NULL , the system searches
the icon resource specified by the hIcon member for an icon of the appropriate size to use as the small icon.
Remarks
NOTE
The winuser.h header defines WNDCLASSEX 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GetClassInfoEx
Reference
RegisterClassEx
UnregisterClass
Window Classes
WNDCLASSEXW structure (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Contains window class information. It is used with the RegisterClassEx and GetClassInfoEx functions.
The WNDCL ASSEX structure is similar to the WNDCLASS structure. There are two differences. WNDCL ASSEX
includes the cbSize member, which specifies the size of the structure, and the hIconSm member, which
contains a handle to a small icon associated with the window class.
Syntax
typedef struct tagWNDCLASSEXW {
UINT cbSize;
UINT style;
WNDPROC lpfnWndProc;
int cbClsExtra;
int cbWndExtra;
HINSTANCE hInstance;
HICON hIcon;
HCURSOR hCursor;
HBRUSH hbrBackground;
LPCWSTR lpszMenuName;
LPCWSTR lpszClassName;
HICON hIconSm;
} WNDCLASSEXW, *PWNDCLASSEXW, *NPWNDCLASSEXW, *LPWNDCLASSEXW;
Members
cbSize
Type: UINT
The size, in bytes, of this structure. Set this member to sizeof(WNDCLASSEX) . Be sure to set this member before
calling the GetClassInfoEx function.
style
Type: UINT
The class style(s). This member can be any combination of the Class Styles.
lpfnWndProc
Type: WNDPROC
A pointer to the window procedure. You must use the CallWindowProc function to call the window procedure.
For more information, see WindowProc.
cbClsExtra
Type: int
The number of extra bytes to allocate following the window-class structure. The system initializes the bytes to
zero.
cbWndExtra
Type: int
The number of extra bytes to allocate following the window instance. The system initializes the bytes to zero. If
an application uses WNDCL ASSEX to register a dialog box created by using the CL ASS directive in the
resource file, it must set this member to DLGWINDOWEXTRA .
hInstance
Type: HINSTANCE
A handle to the instance that contains the window procedure for the class.
hIcon
Type: HICON
A handle to the class icon. This member must be a handle to an icon resource. If this member is NULL , the
system provides a default icon.
hCursor
Type: HCURSOR
A handle to the class cursor. This member must be a handle to a cursor resource. If this member is NULL , an
application must explicitly set the cursor shape whenever the mouse moves into the application's window.
hbrBackground
Type: HBRUSH
A handle to the class background brush. This member can be a handle to the brush to be used for painting the
background, or it can be a color value. A color value must be one of the following standard system colors (the
value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the following
HBRUSH types:
COLOR_ACTIVEBORDER
COLOR_ACTIVECAPTION
COLOR_APPWORKSPACE
COLOR_BACKGROUND
COLOR_BTNFACE
COLOR_BTNSHADOW
COLOR_BTNTEXT
COLOR_CAPTIONTEXT
COLOR_GRAYTEXT
COLOR_HIGHLIGHT
COLOR_HIGHLIGHTTEXT
COLOR_INACTIVEBORDER
COLOR_INACTIVECAPTION
COLOR_MENU
COLOR_MENUTEXT
COLOR_SCROLLBAR
COLOR_WINDOW
COLOR_WINDOWFRAME
COLOR_WINDOWTEXT
The system automatically deletes class background brushes when the class is unregistered by using
UnregisterClass. An application should not delete these brushes.
When this member is NULL , an application must paint its own background whenever it is requested to paint in
its client area. To determine whether the background must be painted, an application can either process the
WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint
function.
lpszMenuName
Type: LPCTSTR
Pointer to a null-terminated character string that specifies the resource name of the class menu, as the name
appears in the resource file. If you use an integer to identify the menu, use the MAKEINTRESOURCE macro. If
this member is NULL , windows belonging to this class have no default menu.
lpszClassName
Type: LPCTSTR
A pointer to a null-terminated string or is an atom. If this parameter is an atom, it must be a class atom created
by a previous call to the RegisterClass or RegisterClassEx function. The atom must be in the low-order word of
lpszClassName ; the high-order word must be zero.
If lpszClassName 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.
The maximum length for lpszClassName is 256. If lpszClassName is greater than the maximum length, the
RegisterClassEx function will fail.
hIconSm
Type: HICON
A handle to a small icon that is associated with the window class. If this member is NULL , the system searches
the icon resource specified by the hIcon member for an icon of the appropriate size to use as the small icon.
Remarks
NOTE
The winuser.h header defines WNDCLASSEX 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
Conceptual
GetClassInfoEx
Reference
RegisterClassEx
UnregisterClass
Window Classes
WNDCLASSW structure (winuser.h)
2/1/2021 • 3 minutes to read • Edit Online
Contains the window class attributes that are registered by the RegisterClass function.
This structure has been superseded by the WNDCLASSEX structure used with the RegisterClassEx function. You
can still use WNDCL ASS and RegisterClass if you do not need to set the small icon associated with the window
class.
Syntax
typedef struct tagWNDCLASSW {
UINT style;
WNDPROC lpfnWndProc;
int cbClsExtra;
int cbWndExtra;
HINSTANCE hInstance;
HICON hIcon;
HCURSOR hCursor;
HBRUSH hbrBackground;
LPCWSTR lpszMenuName;
LPCWSTR lpszClassName;
} WNDCLASSW, *PWNDCLASSW, *NPWNDCLASSW, *LPWNDCLASSW;
Members
style
Type: UINT
The class style(s). This member can be any combination of the Class Styles.
lpfnWndProc
Type: WNDPROC
A pointer to the window procedure. You must use the CallWindowProc function to call the window procedure.
For more information, see WindowProc.
cbClsExtra
Type: int
The number of extra bytes to allocate following the window-class structure. The system initializes the bytes to
zero.
cbWndExtra
Type: int
The number of extra bytes to allocate following the window instance. The system initializes the bytes to zero. If
an application uses WNDCL ASS to register a dialog box created by using the CL ASS directive in the resource
file, it must set this member to DLGWINDOWEXTRA .
hInstance
Type: HINSTANCE
A handle to the instance that contains the window procedure for the class.
hIcon
Type: HICON
A handle to the class icon. This member must be a handle to an icon resource. If this member is NULL , the
system provides a default icon.
hCursor
Type: HCURSOR
A handle to the class cursor. This member must be a handle to a cursor resource. If this member is NULL , an
application must explicitly set the cursor shape whenever the mouse moves into the application's window.
hbrBackground
Type: HBRUSH
A handle to the class background brush. This member can be a handle to the physical brush to be used for
painting the background, or it can be a color value. A color value must be one of the following standard system
colors (the value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the
following HBRUSH types:
COLOR_ACTIVEBORDER
COLOR_ACTIVECAPTION
COLOR_APPWORKSPACE
COLOR_BACKGROUND
COLOR_BTNFACE
COLOR_BTNSHADOW
COLOR_BTNTEXT
COLOR_CAPTIONTEXT
COLOR_GRAYTEXT
COLOR_HIGHLIGHT
COLOR_HIGHLIGHTTEXT
COLOR_INACTIVEBORDER
COLOR_INACTIVECAPTION
COLOR_MENU
COLOR_MENUTEXT
COLOR_SCROLLBAR
COLOR_WINDOW
COLOR_WINDOWFRAME
COLOR_WINDOWTEXT
The system automatically deletes class background brushes when the class is unregistered by using
UnregisterClass. An application should not delete these brushes.
When this member is NULL , an application must paint its own background whenever it is requested to paint in
its client area. To determine whether the background must be painted, an application can either process the
WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint
function.
lpszMenuName
Type: LPCTSTR
The resource name of the class menu, as the name appears in the resource file. If you use an integer to identify
the menu, use the MAKEINTRESOURCE macro. If this member is NULL , windows belonging to this class have no
default menu.
lpszClassName
Type: LPCTSTR
A pointer to a null-terminated string or is an atom. If this parameter is an atom, it must be a class atom created
by a previous call to the RegisterClass or RegisterClassEx function. The atom must be in the low-order word of
lpszClassName ; the high-order word must be zero.
If lpszClassName 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.
The maximum length for lpszClassName is 256. If lpszClassName is greater than the maximum length, the
RegisterClass function will fail.
Remarks
NOTE
The winuser.h header defines WNDCLASS 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
Minimum suppor ted client Windows 2000 Professional [desktop apps only]
Minimum suppor ted ser ver Windows 2000 Server [desktop apps only]
See also
BeginPaint
Conceptual
CreateWindow
CreateWindowEx
GetDC
MAKEINTRESOURCE
Other Resources
PAINTSTRUCT
Reference
RegisterClass
UnregisterClass
WM_PAINT
WNDCLASSEX
Window Classes
WindowProc