Função MessageBoxW (winuser.h)
Exibe uma caixa de diálogo modal que contém um ícone do sistema, um conjunto de botões e uma breve mensagem específica do aplicativo, como status ou informações de erro. A caixa de mensagem retorna um valor inteiro que indica qual botão o usuário clicou.
Sintaxe
int MessageBoxW(
[in, optional] HWND hWnd,
[in, optional] LPCWSTR lpText,
[in, optional] LPCWSTR lpCaption,
[in] UINT uType
);
Parâmetros
[in, optional] hWnd
Digite: HWND
Um identificador para a janela proprietário da caixa de mensagem a ser criada. Se esse parâmetro for NULL, a caixa de mensagem não terá nenhuma janela de proprietário.
[in, optional] lpText
Tipo: LPCTSTR
A mensagem a ser exibida. Se a cadeia de caracteres consistir em mais de uma linha, você poderá separar as linhas usando um retorno de carro e/ou caractere de alimentação de linha entre cada linha.
[in, optional] lpCaption
Tipo: LPCTSTR
O título da caixa de diálogo. Se esse parâmetro for NULL, o título padrão será Error.
[in] uType
Tipo: UINT
O conteúdo e o comportamento da caixa de diálogo. Esse parâmetro pode ser uma combinação de sinalizadores dos seguintes grupos de sinalizadores.
Para indicar os botões exibidos na caixa de mensagem, especifique um dos valores a seguir.
| Valor | Significado |
|---|---|
|
A caixa de mensagem contém três botões de push: Anular, Repetir e Ignorar. |
|
A caixa de mensagem contém três botões de push: Cancelar, Tentar Novamente, Continuar. Use esse tipo de caixa de mensagem em vez de MB_ABORTRETRYIGNORE. |
|
Adiciona um botão Ajuda à caixa de mensagem. Quando o usuário clica no botão Ajuda ou pressiona F1, o sistema envia uma mensagem WM_HELP para o proprietário. |
|
A caixa de mensagem contém um botão de push: OK. Esse é o padrão. |
|
A caixa de mensagem contém dois botões de push: OK e Cancelar. |
|
A caixa de mensagem contém dois botões de push: Repetir e Cancelar. |
|
A caixa de mensagem contém dois botões de push: Sim e Não. |
|
A caixa de mensagem contém três botões de push: Sim, Não e Cancelar. |
Para exibir um ícone na caixa de mensagem, especifique um dos valores a seguir.
Para indicar o botão padrão, especifique um dos valores a seguir.
Para indicar a modalidade da caixa de diálogo, especifique um dos valores a seguir.
Para especificar outras opções, use um ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
O mesmo que a área de trabalho da estação de janela interativa. Para obter mais informações, consulte Estações de Janela.
Se a área de trabalho de entrada atual não for a área de trabalho padrão, MessageBox não retornará até que o usuário mude para a área de trabalho padrão. |
|
O texto é justificado com o botão direito do mouse. |
|
Exibe mensagem e legenda texto usando a ordem de leitura da direita para a esquerda em sistemas hebraicos e árabes. |
|
A caixa de mensagem se torna a janela em primeiro plano. Internamente, o sistema chama a função SetForegroundWindow para a caixa de mensagem. |
|
A caixa de mensagem é criada com o estilo de janela WS_EX_TOPMOST . |
|
O chamador é um serviço que notifica o usuário sobre um evento. A função exibe uma caixa de mensagem na área de trabalho ativa atual, mesmo que não haja nenhum usuário conectado ao computador.
Serviços de Terminal: Se o thread de chamada tiver um token de representação, a função direcionará a caixa de mensagem para a sessão especificada no token de representação. Se esse sinalizador for definido, o parâmetro hWnd deverá ser NULL. Isso é para que a caixa de mensagem possa aparecer em uma área de trabalho diferente da área de trabalho correspondente ao hWnd. Para obter informações sobre considerações de segurança em relação ao uso desse sinalizador, consulte Serviços Interativos. Em particular, lembre-se de que esse sinalizador pode produzir conteúdo interativo em uma área de trabalho bloqueada e, portanto, deve ser usado apenas para um conjunto muito limitado de cenários, como esgotamento de recursos. |
Valor retornado
Tipo: int
Se uma caixa de mensagem tiver um botão Cancelar , a função retornará o valor IDCANCEL se a tecla ESC for pressionada ou o botão Cancelar estiver selecionado. Se a caixa de mensagem não tiver nenhum botão Cancelar , pressionar ESC não terá efeito , a menos que um botão MB_OK esteja presente. Se um botão MB_OK for exibido e o usuário pressionar ESC, o valor retornado será IDOK.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Se a função for bem-sucedida, o valor retornado será um dos seguintes valores de item de menu.
| Retornar código/valor | Descrição |
|---|---|
|
O botão Anular foi selecionado. |
|
O botão Cancelar foi selecionado. |
|
O botão Continuar foi selecionado. |
|
O botão Ignorar foi selecionado. |
|
O botão Não foi selecionado. |
|
O botão OK foi selecionado. |
|
O botão Repetir foi selecionado. |
|
O botão Tentar novamente foi selecionado. |
|
O botão Sim foi selecionado. |
Comentários
Os ícones do sistema a seguir podem ser usados em uma caixa de mensagem definindo o parâmetro uType como o valor do sinalizador correspondente.
| ícone | Valores de sinalizador |
|---|---|
 |
MB_ICONHAND, MB_ICONSTOP ou MB_ICONERROR |
 |
MB_ICONQUESTION |
 |
MB_ICONEXCLAMATION ou MB_ICONWARNING |
 |
MB_ICONASTERISK ou MB_ICONINFORMATION |
Adicionando duas RLMs (marcas da direita para a esquerda), representadas pelo caractere de formatação Unicode U+200F, no início de uma cadeia de caracteres de exibição MessageBox é interpretada pelo mecanismo de renderização MessageBox para fazer com que a ordem de leitura do MessageBox seja renderizada como RTL (direita para a esquerda).
Quando você usa uma caixa de mensagem modal do sistema para indicar que o sistema está com pouca memória, as cadeias de caracteres apontadas pelos parâmetros lpText e lpCaption não devem ser retiradas de um arquivo de recurso porque uma tentativa de carregar o recurso pode falhar.
Se você criar uma caixa de mensagem enquanto uma caixa de diálogo estiver presente, use um identificador para a caixa de diálogo como o parâmetro hWnd . O parâmetro hWnd não deve identificar uma janela filho, como um controle em uma caixa de diálogo.
Exemplos
No exemplo a seguir, o aplicativo exibe uma caixa de mensagem que solicita ao usuário uma ação após a ocorrência de uma condição de erro. A caixa de mensagem exibe a mensagem que descreve a condição de erro e como resolve-la. O estilo MB_CANCELTRYCONTINUE direciona MessageBox para fornecer três botões com os quais o usuário pode escolher como proceder. O estilo MB_DEFBUTTON2 define o foco padrão no segundo botão da caixa de mensagem, nesse caso, o botão Tentar novamente .
int DisplayResourceNAMessageBox()
{
int msgboxID = MessageBox(
NULL,
(LPCWSTR)L"Resource not available\nDo you want to try again?",
(LPCWSTR)L"Account Details",
MB_ICONWARNING | MB_CANCELTRYCONTINUE | MB_DEFBUTTON2
);
switch (msgboxID)
{
case IDCANCEL:
// TODO: add code
break;
case IDTRYAGAIN:
// TODO: add code
break;
case IDCONTINUE:
// TODO: add code
break;
}
return msgboxID;
}
A imagem a seguir mostra a saída do exemplo de código anterior:
Para outro exemplo de caixa de mensagem, consulte Exibindo uma caixa de mensagem.
Observação
O cabeçalho winuser.h define MessageBox 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
| 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-dialogbox-l1-1-0 (introduzido em Windows 8) |
Confira também
Conceitual
Outros recursos
Referência
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de