TaskDialog 函式 (commctrl.h)

發行項
02/24/2024

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 或以 Null 終止的 Unicode 字串指標，其中包含系統資源標識碼，例如，TD_ERROR_ICON。

[in] pszWindowTitle

類型： PCWSTR

要用於工作對話框標題之字串的指標。此參數是以 Null 終止的 Unicode 字串，其中包含文字，或透過 MAKEINTRESOURCE 宏傳遞的整數資源識別碼。如果此參數為 NULL，則會使用可執行文件的檔名。

[in] pszMainInstruction

類型： PCWSTR

要用於主要指令之字串的指標。此參數是以 Null 終止的 Unicode 字串，其中包含文字，或透過 MAKEINTRESOURCE 宏傳遞的整數資源識別碼。如果沒有想要主要指令，此參數可以是 NULL 。

[in] pszContent

類型： PCWSTR

在較小的字型中，用於出現在主要指令下方之其他文字的字串指標。此參數是以 Null 終止的 Unicode 字串，其中包含文字，或透過 MAKEINTRESOURCE 宏傳遞的整數資源識別碼。如果沒有其他文字需要，可以為 NULL 。

[in] dwCommonButtons

類型： TASKDIALOG_COMMON_BUTTON_FLAGS

指定對話框中顯示的按鈕。此參數可能是來自下列群組的旗標組合。

注意如果未指定任何按鈕，則對話框預設會包含 [確定 ] 按鈕。

值	意義
TDCBF_OK_BUTTON	工作對話框包含按鈕：確定。
TDCBF_YES_BUTTON	工作對話框包含按鈕：是。
TDCBF_NO_BUTTON	工作對話框包含按鈕：否。
TDCBF_CANCEL_BUTTON	工作對話框包含按鈕：取消。必須指定此按鈕，對話方塊才能回應一般取消動作， (Alt-F4和逸出) 。
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、按下逸出，或使用者按兩下關閉視窗按鈕。
IDNO	未選取按鈕。
IDOK	已選取 [確定] 按鈕。
IDRETRY	已選取 [重試] 按鈕。
IDYES	已選取 [是] 按鈕。
IDCLOSE	已選取 [關閉] 按鈕。

如果此值為 NULL，則不會傳回任何值。

傳回值

類型： HRESULT

此函式可以傳回其中一個值。

傳回碼	描述
S_OK	作業已成功完成。
E_OUTOFMEMORY	記憶體不足，無法完成作業。
E_INVALIDARG	一或多個自變數無效。
E_FAIL	作業失敗。

備註

當您使用工作對話框來指出系統記憶體不足時， pszMainInstruction 和 pszWindowTitle 參數所指向的字串不應該從資源檔取得，因為嘗試載入資源可能會失敗。

如果您在對話方塊存在時建立工作對話框，請使用對話框的句柄做為 hWndParent 參數。 hWndParent 參數不應該識別子視窗，例如對話框中的控件。

因為工作對話框使用正確的系統定義UI元素，所以您應該使用它們，而不是使用以 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
標頭	commctrl.h (包含 Commctrl.h)
程式庫	Comctl32.lib
Dll	Comctl32.dll (第 6 版)

另請參閱

對話框

共用方式為

TaskDialog 函式 (commctrl.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

其他資源