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 |
|---|---|
|
As mensagens não são removidas da fila após o processamento por PeekMessage. |
|
As mensagens são removidas da fila após o processamento por PeekMessage. |
|
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.
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
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
Mensagens e filas de mensagens
Outros recursos
Referência