Функция DialogBoxParamA (winuser.h)

Статья
08/27/2023

Создает модальное диалоговое окно из ресурса шаблона диалогового окна. Перед отображением диалогового окна функция передает определяемое приложением значение в процедуру диалогового окна в качестве параметра lParamWM_INITDIALOG сообщения. Приложение может использовать это значение для инициализации элементов управления диалоговых окон.

Синтаксис

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

Параметры

[in, optional] hInstance

Тип: HINSTANCE

Дескриптор модуля, который содержит шаблон диалогового окна. Если этот параметр имеет значение NULL, используется текущий исполняемый файл.

[in] lpTemplateName

Тип: LPCTSTR

Шаблон диалогового окна. Этот параметр является либо указателем на строку символов, завершающуюся null, которая указывает имя шаблона диалогового окна, либо целочисленное значение, указывающее идентификатор ресурса шаблона диалогового окна. Если параметр задает идентификатор ресурса, его высокоупорядоченное слово должно быть равно нулю, а слово нижнего порядка должно содержать идентификатор. Для создания этого значения можно использовать макрос MAKEINTRESOURCE .

[in, optional] hWndParent

Тип: HWND

Дескриптор окна, которому принадлежит диалоговое окно.

[in, optional] lpDialogFunc

Тип: DLGPROC

Указатель на процедуру диалогового окна. Дополнительные сведения о процедуре диалогового окна см. в разделе DialogProc.

[in] dwInitParam

Тип: LPARAM

Значение, передаваемое в диалоговое окно в параметре lParamсообщения WM_INITDIALOG .

Возвращаемое значение

Тип: INT_PTR

Если функция выполнена успешно, возвращаемое значение — это значение параметра nResult , указанного в вызове функции EndDialog , используемой для завершения диалогового окна.

Если функция завершается ошибкой из-за недопустимого параметра hWndParent , возвращаемое значение равно нулю. Функция возвращает ноль в этом случае для совместимости с предыдущими версиями Windows. Если функция завершается сбоем по какой-либо другой причине, возвращается значение –1. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Функция DialogBoxParam использует функцию CreateWindowEx для создания диалогового окна. Затем DialogBoxParam отправляет WM_INITDIALOG сообщение (и сообщение WM_SETFONT, если шаблон задает DS_SETFONT или стиль DS_SHELLFONT) в процедуру диалогового окна. Функция отображает диалоговое окно (независимо от того, указывает ли шаблон стиль WS_VISIBLE ), отключает окно владельца и запускает собственный цикл сообщений для получения и отправки сообщений для диалогового окна.

Когда процедура диалогового окна вызывает функцию EndDialog , DialogBoxParam уничтожает диалоговое окно, завершает цикл сообщений, включает окно владельца (если оно включено ранее) и возвращает параметр nResult , заданный процедурой диалогового окна при вызове Метода EndDialog.

Примечание

Заголовок winuser.h определяет DialogBoxParam как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-dialogbox-l1-1-1 (представлено в Windows 8.1)