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 成員所識別的圖示資源,以及 pszWindowTitlepszMainInstruction 成員所識別的字串資源。 如果此參數為 NullpszIcon 必須是 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 已選取[是] 按鈕。
 

如果此值為 Null,則不會傳回任何值。

傳回值

類型: HRESULT

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

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

備註

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

如果您在對話方塊存在時建立工作對話方塊,請使用對話方塊的控制碼做為 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)

另請參閱

對話方塊