PeekMessage

2.x

The PeekMessage function checks the application's message queue for a message and places the message (if any) in the specified MSG structure.

Parameters

lpmsg

Points to an MSG structure that will receive message information from the application's message queue. The MSG structure has the following form:

typedef struct tagMSG {     /* msg */
    HWND   hwnd;
    UINT   message;
    WPARAM wParam;
    LPARAM lParam;
    DWORD  time;
    POINT  pt;
} MSG;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

hwnd

Identifies the window whose messages are to be examined.

uFilterFirst

Specifies the value of the first message in the range of messages to be examined.

uFilterLast

Specifies the value of the last message in the range of messages to be examined.

fuRemove

Specifies how messages are handled. This parameter can be a combination of the following values (PM_NOYIELD can be combined with either PM_NOREMOVE or PM_REMOVE):

Return Value

The return value is nonzero if a message is available. Otherwise, it is zero.

Comments

Unlike the GetMessage function, the PeekMessage function does not wait for a message to be placed in the queue before returning. It does, however, yield control to other tasks (if the PM_NOYIELD flag is not set).

PeekMessage retrieves only 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 uFilterFirst and uFilterLast parameters. If hwnd is NULL, PeekMessage retrieves messages for any window that belongs to the application making the call. (PeekMessage does not retrieve messages for windows that belong to other applications.) If uFilterFirst and uFilterLast are both zero, PeekMessage returns all available messages (no range filtering is performed).

The WM_KEYFIRST and WM_KEYLAST flags can be used as filter values to retrieve all key messages; the WM_MOUSEFIRST and WM_MOUSELAST flags can be used to retrieve all mouse messages.

PeekMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until processed. The GetMessage, PeekMessage, and WaitMessage functions yield control to other applications. These calls provide the only way to let other applications run. If your application does not call any of these functions for long periods of time, other applications cannot run.

As long as an application is in a PeekMessage loop, Windows cannot become idle. Therefore, an application should not remain in a PeekMessage loop after the application's background processing has completed.

When an application uses the PeekMessage function without removing the message and then calls the WaitMessage function, WaitMessage does not return until the message is received. Applications that use the PeekMessage function should remove any retrieved messages from the queue before calling WaitMessage.

Example

The following example checks the message queue for keystrokes that have special meaning to the application. Note that the CheckSpecialKeys function is application-defined.

MSG msg;
BOOL fRetVal = TRUE;

while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {

    if (msg.message == WM_QUIT)
        fRetVal = FALSE;

    if (CheckSpecialKeys(&msg)) /* application defined */
        continue;

    TranslateMessage(&msg);
    DispatchMessage(&msg);
}
return fRetVal;

See Also

GetMessage, IsChild, PostAppMessage, SetMessageQueue, WaitMessage