Função MessageBox (winuser.h)

Artigo
06/08/2023

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 MessageBox(
  [in, optional] HWND    hWnd,
  [in, optional] LPCTSTR lpText,
  [in, optional] LPCTSTR 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
MB_ABORTRETRYIGNORE 0x00000002L	A caixa de mensagem contém três botões de push: Anular, Repetir e Ignorar.
MB_CANCELTRYCONTINUE 0x00000006L	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.
MB_HELP 0x00004000L	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.
MB_OK 0x000000000L	A caixa de mensagem contém um botão de push: OK. Esse é o padrão.
MB_OKCANCEL 0x00000001L	A caixa de mensagem contém dois botões de push: OK e Cancelar.
MB_RETRYCANCEL 0x000000005L	A caixa de mensagem contém dois botões de push: Repetir e Cancelar.
MB_YESNO 0x00000004L	A caixa de mensagem contém dois botões de push: Sim e Não.
MB_YESNOCANCEL 0x00000003L	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.

Valor	Significado
MB_ICONEXCLAMATION 0x00000030L	Um ícone de ponto de exclamação aparece na caixa de mensagem.
MB_ICONWARNING 0x00000030L	Um ícone de ponto de exclamação aparece na caixa de mensagem.
MB_ICONINFORMATION 0x00000040L	Um ícone que consiste em uma letra minúscula i em um círculo aparece na caixa de mensagem.
MB_ICONASTERISK 0x00000040L	Um ícone que consiste em uma letra minúscula i em um círculo aparece na caixa de mensagem.
MB_ICONQUESTION 0x00000020L	Um ícone de ponto de interrogação aparece na caixa de mensagem. O ícone de mensagem de ponto de interrogação não é recomendado porque não representa claramente um tipo específico de mensagem e porque a elaboração de uma mensagem em formato de pergunta pode se aplicar a qualquer tipo de mensagem. Além disso, os usuários podem confundir o ponto de interrogação do símbolo da mensagem com informações da Ajuda. Portanto, não use esse símbolo de mensagem de ponto de interrogação em suas caixas de mensagem. O sistema continua dando suporte à sua inclusão somente por questão de compatibilidade com versões anteriores.
MB_ICONSTOP 0x00000010L	Um ícone de sinal de parada aparece na caixa de mensagem.
MB_ICONERROR 0x00000010L	Um ícone de sinal de parada aparece na caixa de mensagem.
MB_ICONHAND 0x00000010L	Um ícone de sinal de parada aparece na caixa de mensagem.

Para indicar o botão padrão, especifique um dos valores a seguir.

Valor	Significado
MB_DEFBUTTON1 0x000000000L	O primeiro botão é o botão padrão. MB_DEFBUTTON1 é o padrão, a menos que MB_DEFBUTTON2, MB_DEFBUTTON3 ou MB_DEFBUTTON4 seja especificado.
MB_DEFBUTTON2 0x00000100L	O segundo botão é o botão padrão.
MB_DEFBUTTON3 0x00000200L	O terceiro botão é o botão padrão.
MB_DEFBUTTON4 0x00000300L	O quarto botão é o botão padrão.

Para indicar a modalidade da caixa de diálogo, especifique um dos valores a seguir.

Valor	Significado
MB_APPLMODAL 0x000000000L	O usuário deve responder à caixa de mensagem antes de continuar o trabalho na janela identificada pelo parâmetro hWnd . No entanto, o usuário pode mover para as janelas de outros threads e trabalhar nessas janelas. Dependendo da hierarquia de janelas no aplicativo, o usuário pode ser capaz de mover para outras janelas dentro do thread. Todas as janelas filho do pai da caixa de mensagem são desabilitadas automaticamente, mas as janelas pop-up não são. MB_APPLMODAL será o padrão se nem MB_SYSTEMMODAL nem MB_TASKMODAL forem especificados.
MB_SYSTEMMODAL 0x00001000L	O mesmo que MB_APPLMODAL, exceto que a caixa de mensagem tem o estilo WS_EX_TOPMOST . Use caixas de mensagens modais do sistema para notificar o usuário de erros graves e potencialmente prejudiciais que exigem atenção imediata (por exemplo, ficando sem memória). Esse sinalizador não tem efeito sobre a capacidade do usuário de interagir com janelas diferentes daquelas associadas ao hWnd.
MB_TASKMODAL 0x00002000L	O mesmo que MB_APPLMODAL exceto que todas as janelas de nível superior pertencentes ao thread atual serão desabilitadas se o parâmetro hWnd for NULL. Use esse sinalizador quando o aplicativo ou biblioteca de chamada não tiver um identificador de janela disponível, mas ainda precisar impedir a entrada para outras janelas no thread de chamada sem suspender outros threads.

Valor

Significado

MB_APPLMODAL
0x000000000L

O usuário deve responder à caixa de mensagem antes de continuar o trabalho na janela identificada pelo parâmetro hWnd . No entanto, o usuário pode mover para as janelas de outros threads e trabalhar nessas janelas.

Dependendo da hierarquia de janelas no aplicativo, o usuário pode ser capaz de mover para outras janelas dentro do thread. Todas as janelas filho do pai da caixa de mensagem são desabilitadas automaticamente, mas as janelas pop-up não são.

MB_APPLMODAL será o padrão se nem MB_SYSTEMMODAL nem MB_TASKMODAL forem especificados.

MB_SYSTEMMODAL
0x00001000L

O mesmo que MB_APPLMODAL, exceto que a caixa de mensagem tem o estilo WS_EX_TOPMOST . Use caixas de mensagens modais do sistema para notificar o usuário de erros graves e potencialmente prejudiciais que exigem atenção imediata (por exemplo, ficando sem memória). Esse sinalizador não tem efeito sobre a capacidade do usuário de interagir com janelas diferentes daquelas associadas ao hWnd.

MB_TASKMODAL
0x00002000L

O mesmo que MB_APPLMODAL exceto que todas as janelas de nível superior pertencentes ao thread atual serão desabilitadas se o parâmetro hWnd for NULL. Use esse sinalizador quando o aplicativo ou biblioteca de chamada não tiver um identificador de janela disponível, mas ainda precisar impedir a entrada para outras janelas no thread de chamada sem suspender outros threads.

Para especificar outras opções, use um ou mais dos valores a seguir.

Valor	Significado
MB_DEFAULT_DESKTOP_ONLY 0x00020000L	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.
MB_RIGHT 0x00080000L	O texto é justificado com o botão direito do mouse.
MB_RTLREADING 0x00100000L	Exibe mensagem e legenda texto usando a ordem de leitura da direita para a esquerda em sistemas hebraicos e árabes.
MB_SETFOREGROUND 0x00010000L	A caixa de mensagem se torna a janela em primeiro plano. Internamente, o sistema chama a função SetForegroundWindow para a caixa de mensagem.
MB_TOPMOST 0x00040000L	A caixa de mensagem é criada com o estilo de janela WS_EX_TOPMOST .
MB_SERVICE_NOTIFICATION 0x00200000L	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.

Retornar valor

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.

Valor/código retornado	Descrição
IDABORT 3	O botão Anular foi selecionado.
IDCANCEL 2	O botão Cancelar foi selecionado.
IDCONTINUE 11	O botão Continuar foi selecionado.
IDIGNORE 5	O botão Ignorar foi selecionado.
IDNO 7	O botão Não foi selecionado.
IDOK 1	O botão OK foi selecionado.
IDRETRY 4	O botão Repetir foi selecionado.
IDTRYAGAIN 10	O botão Tentar novamente foi selecionado.
IDYES 6	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.

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-dialogbox-l1-1-0 (introduzido em Windows 8)