windows_programming_notes.nbk: Home | Index | Next Page: POINT | Previous Page: PBRANGE

 PeekMessage

The PeekMessage function dispatches incoming sent messages, checks the thread message queue for a posted message, and retrieves the message (if any exist).

Syntax

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

Parameters

• lpMsg
  [out] Pointer to an MSG structure that receives message information.
• hWnd
  [in] 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
  [in] Specifies the value of the first message in the range of messages to be examined. Use WM_KEYFIRST to specify the first keyboard message or WM_MOUSEFIRST 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
  [in] Specifies the value of the last message in the range of messages to be examined. Use WM_KEYLAST to specify the last keyboard message or WM_MOUSELAST 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
  [in] Specifies how messages are handled. This parameter can be one of the following values.
  • PM_NOREMOVE
  Messages are not removed from the queue after processing by PeekMessage.
  • PM_REMOVE
  Messages are removed from the queue after processing by PeekMessage. You can optionally combine the value PM_NOYIELD with either PM_NOREMOVE or PM_REMOVE. This flag prevents the system from releasing any thread that is waiting for the caller to go idle (see WaitForInputIdle). By default, all message types are processed. To specify that only certain message should be processed, specify one or more of the following values.
  • PM_QS_INPUT
  Windows 98/Me, Windows 2000/XP: Process mouse and keyboard messages.
  • PM_QS_PAINT
  Windows 98/Me, Windows 2000/XP: Process paint messages.
  • PM_QS_POSTMESSAGE
  Windows 98/Me, Windows 2000/XP: Process all posted messages, including timers and hotkeys.
  • PM_QS_SENDMESSAGE
  Windows 98/Me, Windows 2000/XP: Process all sent messages.

Return Value

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.

Windows XP: 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.

Windows 95/98/Me: PeekMessageW is supported by the Microsoft Layer for Unicode (MSLU). To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems .

Example

For an example, see Examining a Message Queue.

Function Information

• Minimum DLL Version user32.dll
• Header Declared in Winuser.h, include Windows.h
• Import library User32.lib
• Minimum operating systems Windows 95, Windows NT 3.1
• Unicode Implemented as ANSI and Unicode versions.

windows_programming_notes.nbk: Home | Index | Next Page: POINT | Previous Page: PBRANGE

Notebook exported on Monday, 7 July 2008, 18:56:50 PM Eastern Daylight Time