Macro DialogBoxA (winuser.h)

Artigo
11/20/2024

Cria uma caixa de diálogo modal a partir de um recurso de modelo de caixa de diálogo. DialogBox não retorna o controle até que a função de retorno de chamada especificada encerre a caixa de diálogo modal chamando a função EndDialog.

DialogBox é implementado como uma chamada para a função DialogBoxParam.

Sintaxe

void DialogBoxA(
  [in, optional]  hInstance,
  [in]            lpTemplate,
  [in, optional]  hWndParent,
  [in, optional]  lpDialogFunc
);

Parâmetros

[in, optional] hInstance

Tipo: HINSTANCE

Um identificador para o módulo que contém o modelo da caixa de diálogo. Se esse parâmetro for NULL, o executável atual será usado.

[in] lpTemplate

Tipo: LPCTSTR

O modelo da caixa de diálogo. Esse parâmetro é o ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do modelo da caixa de diálogo ou um valor inteiro que especifica o identificador de recurso do modelo da caixa de diálogo. Se o parâmetro especificar um identificador de recurso, sua palavra de alta ordem deverá ser zero e sua palavra de ordem baixa deverá conter o identificador. Você pode usar a macro MAKEINTRESOURCE para criar esse valor.

[in, optional] hWndParent

Tipo: HWND

Um identificador para a janela que possui a caixa de diálogo.

[in, optional] lpDialogFunc

Tipo: DLGPROC

Um ponteiro para o procedimento da caixa de diálogo. Para obter mais informações sobre o procedimento da caixa de diálogo, consulte DialogProc.

Valor de retorno

Nenhum

Observações

A macro DialogBox usa a função CreateWindowEx para criar a caixa de diálogo. DialogBox envia uma mensagem de WM_INITDIALOG (e uma mensagem de WM_SETFONT se o modelo especificar o estilo DS_SETFONT ou DS_SHELLFONT) para o procedimento da caixa de diálogo. A função exibe a caixa de diálogo (independentemente de o modelo especificar o estilo WS_VISIBLE), desabilitar a janela do proprietário e iniciar seu próprio loop de mensagem para recuperar e expedir mensagens para a caixa de diálogo.

Quando o procedimento da caixa de diálogo chama a função EndDialog, DialogBox destrói a caixa de diálogo, encerra o loop de mensagem, habilita a janela do proprietário (se habilitada anteriormente) e retorna o parâmetro nResult especificado pelo procedimento da caixa de diálogo quando chamado EndDialog.

Exemplos

Para obter um exemplo, consulte Criando uma caixa de diálogo modal.

Nota

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

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winuser.h (inclua Windows.h)
biblioteca	User32.lib
de DLL	User32.dll