Função DialogBoxParamA (winuser.h)

Artigo
08/27/2023

Cria uma caixa de diálogo modal de um recurso de modelo de caixa de diálogo. Antes de exibir a caixa de diálogo, a função passa um valor definido pelo aplicativo para o procedimento da caixa de diálogo como o parâmetro lParam da mensagem WM_INITDIALOG . Um aplicativo pode usar esse valor para inicializar controles de caixa de diálogo.

Sintaxe

INT_PTR DialogBoxParamA(
  [in, optional] HINSTANCE hInstance,
  [in]           LPCSTR    lpTemplateName,
  [in, optional] HWND      hWndParent,
  [in, optional] DLGPROC   lpDialogFunc,
  [in]           LPARAM    dwInitParam
);

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] lpTemplateName

Tipo: LPCTSTR

O modelo da caixa de diálogo. Esse parâmetro é o ponteiro para uma cadeia de caracteres com término 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, a palavra de alta ordem deverá ser zero e a palavra de baixa ordem deverá conter o identificador. Você pode usar a macro MAKEINTRESOURCE para criar esse valor.

[in, optional] hWndParent

Digite: 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 saber mais sobre o procedimento da caixa de diálogo, confira DialogProc.

[in] dwInitParam

Tipo: LPARAM

O valor a ser passado para a caixa de diálogo no parâmetro lParam da mensagem WM_INITDIALOG .

Retornar valor

Tipo: INT_PTR

Se a função for bem-sucedida, o valor retornado será o valor do parâmetro nResult especificado na chamada para a função EndDialog usada para encerrar a caixa de diálogo.

Se a função falhar porque o parâmetro hWndParent é inválido, o valor retornado será zero. A função retorna zero nesse caso para compatibilidade com versões anteriores do Windows. Se a função falhar por qualquer outro motivo, o valor retornado será –1. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função DialogBoxParam usa a função CreateWindowEx para criar a caixa de diálogo. DialogBoxParam 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 , DialogBoxParam 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.

Observação

O cabeçalho winuser.h define DialogBoxParam 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-dialogbox-l1-1-1 (introduzido no Windows 8.1)