Поделиться через

Функция TaskDialog (commctrl.h)

  • Статья

Функция TaskDialog создает, отображает и управляет диалоговым окном задачи. Диалоговое окно задачи содержит текст и заголовок сообщения, значки и любое сочетание предопределенных кнопок. Эта функция не поддерживает регистрацию функции обратного вызова для получения уведомлений.

Синтаксис

HRESULT TaskDialog(
  [in]  HWND                           hwndOwner,
  [in]  HINSTANCE                      hInstance,
  [in]  PCWSTR                         pszWindowTitle,
  [in]  PCWSTR                         pszMainInstruction,
  [in]  PCWSTR                         pszContent,
  [in]  TASKDIALOG_COMMON_BUTTON_FLAGS dwCommonButtons,
  [in]  PCWSTR                         pszIcon,
  [out] int                            *pnButton
);

Параметры

[in] hwndOwner

Тип: HWND

Дескриптор окна владельца создаваемого диалогового окна задачи. Если этот параметр имеет значение NULL, диалоговое окно задачи не имеет окна владельца.

[in] hInstance

Тип: HINSTANCE

Дескриптор модуля, который содержит ресурс значка, определенный элементом pszIcon , и строковые ресурсы, определяемые элементами pszWindowTitle и pszMainInstruction . Если этот параметр имеет значение NULL, pszIcon должен иметь значение NULL или указатель на строку Юникода, которая содержит идентификатор системного ресурса, например TD_ERROR_ICON.

[in] pszWindowTitle

Тип: PCWSTR

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

[in] pszMainInstruction

Тип: PCWSTR

Указатель на строку, используемую для инструкции main. Этот параметр представляет собой строку Юникода, завершающуюся null, которая содержит либо текст, либо целочисленный идентификатор ресурса, передаваемый через макрос MAKEINTRESOURCE . Этот параметр может иметь значение NULL, если не требуется main инструкции.

[in] pszContent

Тип: PCWSTR

Указатель на строку, используемую для дополнительного текста, который отображается под инструкцией main, шрифтом меньшего размера. Этот параметр представляет собой строку Юникода, завершающуюся null, которая содержит либо текст, либо целочисленный идентификатор ресурса, передаваемый через макрос MAKEINTRESOURCE . Может иметь значение NULL , если дополнительный текст не требуется.

[in] dwCommonButtons

Тип: TASKDIALOG_COMMON_BUTTON_FLAGS

Указывает кнопки, отображаемые в диалоговом окне. Этот параметр может быть сочетанием флагов из следующей группы.

Примечание Если кнопки не указаны, диалоговое окно будет содержать кнопку ОК по умолчанию.
 
Значение Значение
TDCBF_OK_BUTTON
 Диалоговое окно задачи содержит кнопку " ОК".
TDCBF_YES_BUTTON
 Диалоговое окно задачи содержит кнопку push: Да.
TDCBF_NO_BUTTON
 Диалоговое окно задачи содержит кнопку " Нет".
TDCBF_CANCEL_BUTTON
 Диалоговое окно задачи содержит кнопку " Отмена". Эта кнопка должна быть указана, чтобы диалоговое окно отвечало на типичные действия отмены (Alt-F4 и Escape).
TDCBF_RETRY_BUTTON
 Диалоговое окно задачи содержит кнопку "Повторить".
TDCBF_CLOSE_BUTTON
 Диалоговое окно задачи содержит кнопку " Закрыть".

[in] pszIcon

Тип: PCWSTR

Указатель на строку, которая определяет значок, отображаемый в диалоговом окне задачи. Этот параметр должен быть целочисленным идентификатором ресурса, передаваемым макросу MAKEINTRESOURCE , или одним из следующих предопределенных значений. Если этот параметр имеет значение NULL, значок не отображается. Если параметр hInstance имеет значение NULL и одно из предопределенных значений не используется, функция TaskDialog завершается ошибкой.

Значение Значение
TD_ERROR_ICON
 В диалоговом окне задачи появится значок стоп-знака.
TD_INFORMATION_ICON
 В диалоговом окне задачи появляется значок, состоящий из строчной буквы i в круге.
TD_SHIELD_ICON
 В диалоговом окне задачи появится значок щита безопасности.
TD_WARNING_ICON
 В диалоговом окне задачи появится значок восклицательного знака.

[out] pnButton

Тип: int*

При возврате этой функции содержит указатель на целочисленное расположение, которое получает одно из следующих значений:

Значение Описание
0 Сбой вызова функции. Дополнительные сведения см. в разделе Возвращаемое значение.
IDCANCEL Была выбрана кнопка "Отмена", нажата клавиша ALT+F4, нажата escape-кнопка или пользователь нажал кнопку закрытия окна.
IDNO Кнопка не выбрана.
IDOK Выбрана кнопка ОК.
IDRETRY Выбрана кнопка "Повторить".
IDYES Выбрана кнопка "Да ".
IDCLOSE Кнопка "Закрыть" была выбрана.
 

Если это значение равно NULL, значение не возвращается.

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

Тип: HRESULT

Эта функция может возвращать одно из этих значений.

Код возврата Описание
S_OK
 Операция выполнена успешно.
E_OUTOFMEMORY
 Недостаточно памяти для завершения операции.
E_INVALIDARG
 Один или несколько аргументов являются недопустимыми.
E_FAIL
 Операция не удалась.

Комментарии

При использовании диалогового окна задачи для указания нехватки памяти в системе строки, на которые указывают параметры pszMainInstruction и pszWindowTitle , не следует брать из файла ресурсов, так как попытка загрузки ресурса может завершиться ошибкой.

При создании диалогового окна задачи при его наличии используйте дескриптор для диалогового окна в качестве параметра hWndParent . Параметр hWndParent не должен идентифицировать дочернее окно, например элемент управления в диалоговом окне.

Поскольку диалоговые окна задач используют правильные системные элементы пользовательского интерфейса, их следует использовать вместо окон сообщений, созданных с помощью функции MessageBox . Для получения дополнительных функциональных возможностей используйте TaskDialogIndirect.

В следующем примере кода, который будет включен в состав более крупной программы, показано, как создать диалоговое окно задачи и записать входные данные.


int nButtonPressed = 0;
TaskDialog(NULL, hInst, 
    MAKEINTRESOURCE(IDS_APPLICATION_TITLE),
    MAKEINTRESOURCE(IDS_DOSOMETHING), 
    MAKEINTRESOURCE(IDS_SOMECONTENT), 
    TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON,
    TD_WARNING_ICON, 
    &nButtonPressed);

if (IDOK == nButtonPressed)
{
    // OK button pressed
}
else if (IDCANCEL == nButtonPressed)
{
    // Cancel pressed
}

Требования

Требование Значение
Минимальная версия клиента Windows Vista [только классические приложения]
Минимальная версия сервера Windows Server 2008 [только классические приложения]
Целевая платформа Windows
Header commctrl.h (включая Commctrl.h)
Библиотека Comctl32.lib
DLL Comctl32.dll (версия 6)

См. также раздел

Диалоговые окна