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

Статья
11/20/2024

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

Синтаксис

INT_PTR DialogBoxParamW(
  [in, optional] HINSTANCE hInstance,
  [in]           LPCWSTR   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 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winuser.h (включая Windows.h)
библиотеки	User32.lib
DLL	User32.dll
набор API	ext-ms-win-ntuser-dialogbox-l1-1-1 (представлено в Windows 8.1)