PeekMessage Function (Win32) - Windows API Reference

PeekMessage Function

The PeekMessage function checks for messages in the calling thread's message queue (specified by the thread's thread ID) without removing the message from the queue. If a message is available, it is copied into the MSG structure pointed to by the lpMsg parameter. Otherwise, no message is retrieved.

BOOL PeekMessage(
        LPMSG lpMsg,
        HWND hWnd,
        UINT wMsgFilterMin,
        UINT wMsgFilterMax,
        UINT wRemoveMsg
);

Parameters

Parameter	Type	Description
lpMsg	LPMSG	A pointer to a MSG structure that receives message information.
hWnd	HWND	A handle to the window whose messages are to be retrieved. This parameter can be NULL. If it is NULL, PeekMessage retrieves messages for any window that belongs to the calling thread.
wMsgFilterMin	`UINT`	The minimum value in the range of messages to be retrieved.
wMsgFilterMax	`UINT`	The maximum value in the range of messages to be retrieved.
wRemoveMsg	`UINT`	Specifies whether messages are removed from the queue after processing. This parameter can be one or more of the following values: PM_NOREMOVE: Messages are removed from the queue after PeekMessage retrieves them. PM_REMOVE: Messages are not removed from the queue after PeekMessage retrieves them. PM_QS_INPUT: Retrieves any input message (keyboard or mouse) that is waiting in the queue. PM_QS_PAINT: Retrieves any WM_PAINT messages waiting in the queue. PM_QS_POSTMESSAGE: Retrieves any messages posted to the queue (not keyboard or mouse input). PM_QS_SENDMESSAGE: Retrieves any messages sent to the queue (including messages sent by SendMessage).

Return Value

Type	Description
`TRUE`	A message is available.
`FALSE`	No messages are available, and either hWnd is NULL and there are no window messages, or hWnd is not NULL and there are no messages for the specified window.

Remarks

The PeekMessage function is typically used in a loop to process the message queue of an application. Unlike GetMessage, PeekMessage does not block if no messages are available; it returns immediately. This allows an application to perform other tasks while waiting for messages.

If hWnd is NULL, PeekMessage retrieves messages for any window associated with the calling thread. If wMsgFilterMin and wMsgFilterMax are both 0, all messages are returned.

When using PM_NOREMOVE, you must explicitly remove messages from the queue after processing them using GetMessage or another call to PeekMessage with PM_REMOVE.

Example Usage

A typical message loop that uses PeekMessage to check for messages:


#include <windows.h>

// ...

MSG msg;
BOOL bRet;

// Non-blocking message retrieval loop
while ( (bRet = PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) != 0 )
{
    if (bRet == -1) // Handle error
    {
        // Handle error
        break;
    }

    // If it's a quit message, exit the loop
    if (msg.message == WM_QUIT)
    {
        PostQuitMessage(0); // Post a quit message to exit the application
        break;
    }

    // Translate virtual-key messages into character messages
    TranslateMessage(&msg);

    // Dispatch message to the appropriate window procedure
    DispatchMessage(&msg);
}

// If the loop exited because of WM_QUIT, the application will terminate.
// Otherwise, continue with other processing.

MSDN Documentation