Função PeekMessageW (winuser.h)

Despacha mensagens de entrada não enfileiradas, verifica a fila de mensagens de thread de uma mensagem postada e recupera a mensagem (se houver alguma).

Sintaxe

BOOL PeekMessageW(
  [out]          LPMSG lpMsg,
  [in, optional] HWND  hWnd,
  [in]           UINT  wMsgFilterMin,
  [in]           UINT  wMsgFilterMax,
  [in]           UINT  wRemoveMsg
);

Parâmetros

[out] lpMsg

Tipo: LPMSG

Um ponteiro para uma estrutura MSG que recebe informações de mensagem.

[in, optional] hWnd

Digite: HWND

Um identificador para a janela cujas mensagens devem ser recuperadas. A janela deve pertencer ao thread atual.

Se hWnd for NULL, PeekMessage recuperará mensagens para qualquer janela que pertença ao thread atual e quaisquer mensagens na fila de mensagens do thread atual cujo valor hwnd seja NULL (consulte a estrutura MSG ). Portanto, se hWnd for NULL, as mensagens de janela e as mensagens de thread serão processadas.

Se hWnd for -1, PeekMessage recuperará apenas mensagens na fila de mensagens do thread atual cujo valor hwnd é NULL, ou seja, mensagens de thread, conforme postado por PostMessage (quando o parâmetro hWnd é NULL) ou PostThreadMessage.

[in] wMsgFilterMin

Tipo: UINT

O valor da primeira mensagem no intervalo de mensagens a ser examinada. Use WM_KEYFIRST (0x0100) para especificar a primeira mensagem de teclado ou WM_MOUSEFIRST (0x0200) para especificar a primeira mensagem do mouse.

Se wMsgFilterMin e wMsgFilterMax forem zero, PeekMessage retornará todas as mensagens disponíveis (ou seja, nenhuma filtragem de intervalo será executada).

[in] wMsgFilterMax

Tipo: UINT

O valor da última mensagem no intervalo de mensagens a serem examinadas. Use WM_KEYLAST para especificar a última mensagem de teclado ou WM_MOUSELAST para especificar a última mensagem do mouse.

Se wMsgFilterMin e wMsgFilterMax forem zero, PeekMessage retornará todas as mensagens disponíveis (ou seja, nenhuma filtragem de intervalo será executada).

[in] wRemoveMsg

Tipo: UINT

Especifica como as mensagens devem ser tratadas. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
PM_NOREMOVE
0x0000
As mensagens não são removidas da fila após o processamento por PeekMessage.
PM_REMOVE
0x0001
As mensagens são removidas da fila após o processamento por PeekMessage.
PM_NOYIELD
0x0002
Impede que o sistema libere qualquer thread que esteja aguardando o chamador ficar ocioso (consulte WaitForInputIdle).

Combine esse valor com PM_NOREMOVE ou PM_REMOVE.

 

Por padrão, todos os tipos de mensagem são processados. Para especificar que apenas determinada mensagem deve ser processada, especifique um ou mais dos valores a seguir.

Valor Significado
PM_QS_INPUT
(QS_INPUT << 16)
Processar mensagens de mouse e teclado.
PM_QS_PAINT
(QS_PAINT << 16)
Processar mensagens de pintura.
PM_QS_POSTMESSAGE
((QS_POSTMESSAGE | QS_HOTKEY | QS_TIMER) << 16)
Processe todas as mensagens postadas, incluindo temporizadores e teclas de acesso.
PM_QS_SENDMESSAGE
(QS_SENDMESSAGE << 16)
Processar todas as mensagens enviadas.

Retornar valor

Tipo: BOOL

Se uma mensagem estiver disponível, o valor retornado será diferente de zero.

Se nenhuma mensagem estiver disponível, o valor retornado será zero.

Comentários

PeekMessage recupera mensagens associadas à janela identificada pelo parâmetro hWnd ou qualquer um de seus filhos conforme especificado pela função IsChild e dentro do intervalo de valores de mensagem fornecidos pelos parâmetros wMsgFilterMin e wMsgFilterMax . Observe que um aplicativo só pode usar a palavra baixa nos parâmetros wMsgFilterMin e wMsgFilterMax ; a palavra alta é reservada para o sistema.

Observe que PeekMessage sempre recupera mensagens WM_QUIT , independentemente de quais valores você especificar para wMsgFilterMin e wMsgFilterMax.

Durante essa chamada, o sistema despacha (DispatchMessage) mensagens pendentes, ou seja, mensagens enviadas para janelas pertencentes ao thread de chamada usando a função SendMessage, SendMessageCallback, SendMessageTimeout ou SendNotifyMessage . Em seguida, a primeira mensagem enfileirada que corresponde ao filtro especificado é recuperada. O sistema também pode processar eventos internos. Se nenhum filtro for especificado, as mensagens serão processadas na seguinte ordem:

  • Mensagens enviadas
  • Mensagens postadas
  • Mensagens de entrada (hardware) e eventos internos do sistema
  • Mensagens enviadas (novamente)
  • WM_PAINT mensagens
  • WM_TIMER mensagens
Para recuperar mensagens de entrada antes das mensagens postadas, use os parâmetros wMsgFilterMin e wMsgFilterMax .

A função PeekMessage normalmente não remove WM_PAINT mensagens da fila. WM_PAINT mensagens permanecem na fila até serem processadas. No entanto, se uma mensagem WM_PAINT tiver uma região de atualização NULL , PeekMessage a removerá da fila.

Se uma janela de nível superior parar de responder a mensagens por mais de vários segundos, o sistema considerará que a janela não está respondendo e a substituirá por uma janela fantasma que tenha os mesmos atributos de ordem z, local, tamanho e visual. Isso permite que o usuário o mova, redimensione-o ou até mesmo feche o aplicativo. No entanto, essas são as únicas ações disponíveis porque o aplicativo realmente não está respondendo. Quando um aplicativo está sendo depurado, o sistema não gera uma janela fantasma.

Virtualização de DPI

Essa API não participa da virtualização de DPI. A saída está no modo da janela que a mensagem está direcionando. O thread de chamada não é levado em consideração.

Exemplos

Para obter um exemplo, consulte Examinando uma fila de mensagens.

Observação

O cabeçalho winuser.h define PeekMessage como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winuser.h (inclua Windows.h)
Biblioteca User32.lib
DLL User32.dll
Conjunto de APIs ext-ms-win-ntuser-message-l1-1-0 (introduzido no Windows 8)

Confira também

Conceitual

GetMessage

IsChild

MSG

Mensagens e filas de mensagens

Outros recursos

Referência

Waitforinputidle

WaitMessage