TASKDIALOGCONFIG 結構 (commctrl.h)

發行項
08/22/2023

TASKDIALOGCONFIG結構包含用來顯示工作對話方塊的資訊。 TaskDialogIndirect函式會使用此結構。

語法

typedef struct _TASKDIALOGCONFIG {
  UINT                           cbSize;
  HWND                           hwndParent;
  HINSTANCE                      hInstance;
  TASKDIALOG_FLAGS               dwFlags;
  TASKDIALOG_COMMON_BUTTON_FLAGS dwCommonButtons;
  PCWSTR                         pszWindowTitle;
  union {
    HICON  hMainIcon;
    PCWSTR pszMainIcon;
  } DUMMYUNIONNAME;
  PCWSTR                         pszMainInstruction;
  PCWSTR                         pszContent;
  UINT                           cButtons;
  const TASKDIALOG_BUTTON        *pButtons;
  int                            nDefaultButton;
  UINT                           cRadioButtons;
  const TASKDIALOG_BUTTON        *pRadioButtons;
  int                            nDefaultRadioButton;
  PCWSTR                         pszVerificationText;
  PCWSTR                         pszExpandedInformation;
  PCWSTR                         pszExpandedControlText;
  PCWSTR                         pszCollapsedControlText;
  union {
    HICON  hFooterIcon;
    PCWSTR pszFooterIcon;
  } DUMMYUNIONNAME2;
  PCWSTR                         pszFooter;
  PFTASKDIALOGCALLBACK           pfCallback;
  LONG_PTR                       lpCallbackData;
  UINT                           cxWidth;
} TASKDIALOGCONFIG;

成員

cbSize

類型： UINT

指定結構大小，以位元組為單位。

hwndParent

類型： HWND

父視窗的控制碼。此成員可以是 Null。

hInstance

類型： HINSTANCE

控制碼，其中包含 pszMainIcon 或 pszFooterIcon 成員所識別的圖示資源，以及 pszWindowTitle、 pszMainInstruction、 pszContent、 pszVerificationText、 pszExpandedInformation、 pszExpandedControlText、 pszCollapsedControlText 或 pszFooter 成員所識別的字串資源。

dwFlags

類型： TASKDIALOG_FLAGS

指定工作對話方塊的行為。此參數可以是下列群組中的旗標組合：

值	意義
TDF_ENABLE_HYPERLINKS	啟用 pszContent、 pszExpandedInformation 和 pszFooter 成員中所指定字串的超連結處理。啟用時，這些成員可能會指向以下列格式包含超連結的字串： `<A HREF="executablestring">Hyperlink Text</A>` 警告：使用來自不安全來源的內容時啟用超連結可能會導致安全性弱點。注意工作對話方塊不會實際執行任何超連結。超連結執行必須在 pfCallback所指定的回呼函式中處理。如需詳細資訊，請參閱 TaskDialogCallbackProc。
TDF_USE_HICON_MAIN	指出對話方塊應該使用 hMainIcon 成員中控制碼所參考的圖示做為工作對話方塊中的主要圖示。如果指定此旗標，則會忽略 pszMainIcon 成員。
TDF_USE_HICON_FOOTER	指出對話方塊應該使用 hFooterIcon 成員中控制碼所參考的圖示做為工作對話方塊中的頁尾圖示。如果指定此旗標，則會忽略 pszFooterIcon 成員。
TDF_ALLOW_DIALOG_CANCELLATION	表示即使 dwCommonButtons 或 pButtons 成員中未指定取消按鈕，對話方塊也應該能夠使用 Alt-F4、Escape 和標題列的關閉按鈕來關閉。
TDF_USE_COMMAND_LINKS	表示 pButtons 成員中指定的按鈕會顯示為命令連結， (使用標準工作對話方塊圖像) 而非按鈕。使用命令連結時， pszButtonText 成員中第一個新行字元的所有字元都會被視為命令連結的主文字，其餘字元則會被視為命令連結的附注。如果 cButtons 成員為零，則會忽略此旗標。
TDF_USE_COMMAND_LINKS_NO_ICON	表示 pButtons 成員中指定的按鈕會顯示為命令連結， (沒有字元) 而非按鈕。使用命令連結時， pszButtonText 成員中第一個新行字元的所有字元都會被視為命令連結的主文字，其餘字元則會被視為命令連結的附注。如果 cButtons 成員為零，則會忽略此旗標。
TDF_EXPAND_FOOTER_AREA	指出 pszExpandedInformation 成員指定的字串會顯示在對話方塊頁尾區域的底部，而不是緊接在對話方塊的內容之後。如果 pszExpandedInformation 成員為 Null，則會忽略此旗標。
TDF_EXPANDED_BY_DEFAULT	指出一開始顯示對話方塊時，會顯示 pszExpandedInformation 成員所指定的字串。如果 pszExpandedInformation 成員為 Null，則會忽略此旗標。
TDF_VERIFICATION_FLAG_CHECKED	指出一開始顯示對話方塊時，會核取對話方塊中的驗證核取方塊。如果 pszVerificationText 參數為 Null，則會忽略此旗標。
TDF_SHOW_PROGRESS_BAR	表示要顯示進度列。
TDF_SHOW_MARQUEE_PROGRESS_BAR	表示要顯示 Marquee 進度列。
TDF_CALLBACK_TIMER	表示工作對話方塊的回呼大約每 200 毫秒呼叫一次。
TDF_POSITION_RELATIVE_TO_WINDOW	指出工作對話方塊的位置 (相對於 hwndParent所指定的視窗置中) 置中。如果未在 (提供旗標，或未) 指定 hwndParent 成員，則工作對話方塊會置中 (相對於監視器) 置中。
TDF_RTL_LAYOUT	表示文字會顯示在由右至左閱讀。
TDF_NO_DEFAULT_RADIO_BUTTON	表示不會選取預設專案。
TDF_CAN_BE_MINIMIZED	表示工作對話方塊可以最小化。
TDIF_SIZE_TO_CONTENT	此旗標已被取代。請改用 TDF_SIZE_TO_CONTENT 。
TDF_SIZE_TO_CONTENT	表示工作對話方塊的寬度取決於其內容區域的寬度。如果 cxWidth 未設定為 0，則會忽略此旗標。

dwCommonButtons

類型： TASKDIALOG_COMMON_BUTTON_FLAGS

指定工作對話方塊中所顯示的按鈕。如果未指定一般按鈕，且未使用 cButtons 和 pButtons 成員指定任何自訂按鈕，則工作對話方塊預設會包含 [確定 ] 按鈕。此參數可以是下列群組中的旗標組合：

值	意義
TDCBF_OK_BUTTON	工作對話方塊包含一鍵： [確定]。
TDCBF_YES_BUTTON	工作對話方塊包含按鈕：是。
TDCBF_NO_BUTTON	工作對話方塊包含按鈕：否。
TDCBF_CANCEL_BUTTON	工作對話方塊包含按鈕：取消。如果指定此按鈕，工作對話方塊會回應一般取消動作， (Alt-F4 和 Escape) 。
TDCBF_RETRY_BUTTON	工作對話方塊包含按鈕：重試。
TDCBF_CLOSE_BUTTON	工作對話方塊包含按鈕：關閉。

pszWindowTitle

類型： PCWSTR

參考要用於工作對話方塊標題之字串的指標。這個參數可以是以 Null 結束的字串或傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼。如果此參數為 Null，則會使用可執行程式的檔案名。

DUMMYUNIONNAME

DUMMYUNIONNAME.hMainIcon

類型： HICON

要顯示在工作對話方塊中之圖示的控制碼。除非指定TDF_USE_HICON_MAIN旗標，否則會忽略這個成員。如果此成員為 Null ，且已指定TDF_USE_HICON_MAIN，則不會顯示任何圖示。

DUMMYUNIONNAME.pszMainIcon

類型： PCWSTR

參考要顯示在工作對話方塊中之圖示的指標。如果指定USE_HICON_MAIN旗標，則會忽略此參數。否則，如果此參數為 Null 或 hInstance 參數為 Null，則不會顯示任何圖示。此參數必須是傳遞至 MAKEINTRESOURCE 宏或下列其中一個預先定義值的整數資源識別碼：

值	意義
TD_ERROR_ICON	停止登錄圖示會出現在工作對話方塊中。
TD_WARNING_ICON	工作對話方塊中會出現驚嘆號圖示。
TD_INFORMATION_ICON	由圓形中的小寫字母 i 所組成的圖示會出現在工作對話方塊中。
TD_SHIELD_ICON	[工作] 對話方塊中會出現一個防護圖示。

pszMainInstruction

類型： PCWSTR

參考要用於主要指令之字串的指標。此參數可以是以 Null 結尾的字串或傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼。

pszContent

類型： PCWSTR

參考要用於對話主要內容的字串指標。此參數可以是以 Null 結尾的字串或傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼。如果為 dwFlags 成員指定ENABLE_HYPERLINKS旗標，則此字串可能包含格式 < 為：HREF=「可執行檔字串」 > 超連結文字 < /A > 。 警告：使用不安全來源的內容時啟用超連結可能會導致安全性弱點。

cButtons

類型： UINT

pButtons陣列中用來在工作對話方塊中建立按鈕或命令連結的專案數。如果此成員為零，且未使用 dwCommonButtons 成員指定任何通用按鈕，則工作對話方塊會顯示單一 [確定 ] 按鈕。

pButtons

類型：const TASKDIALOG_BUTTON*

TASKDIALOG_BUTTON 結構的陣列指標，其中包含要顯示在工作對話方塊中之自訂按鈕的定義。此陣列必須至少包含 cButtons 成員所指定的專案數目。

nDefaultButton

類型： int

工作對話方塊的預設按鈕。這可能是pButtons陣列中其中一個TASKDIALOG_BUTTON結構之nButtonID成員中指定的任何值，或其中一個對應至 dwCommonButtons成員中所指定按鈕的識別碼：

IDCANCEL	將 [取消] 按鈕設為預設值。
IDNO	將 [否] 按鈕設為預設值。
IDOK	將 [ 確定 ] 按鈕設為預設值。
IDRETRY	將 [ 重試 ] 按鈕設為預設值。
IDYES	將 [ 是 ] 按鈕設為預設值。
IDCLOSE	將 [ 關閉] 按鈕設為預設值。

如果這個成員為零，或其值未對應至對話方塊中的任何按鈕識別碼，則對話方塊中的第一個按鈕會是預設值。

cRadioButtons

類型： UINT

pRadioButtons陣列中用來在工作對話方塊中建立選項按鈕的專案數。

pRadioButtons

類型：const TASKDIALOG_BUTTON*

包含要顯示在工作對話方塊中之選項按鈕定義之TASKDIALOG_BUTTON 結構的陣列指標。此陣列必須至少包含 cRadioButtons 成員所指定的專案數目。此參數可以是 Null。

nDefaultRadioButton

類型： int

預設選取選項按鈕的按鈕識別碼。如果此值未對應至按鈕識別碼，則預設會選取陣列中的第一個按鈕。

pszVerificationText

類型： PCWSTR

參考要用來標記驗證核取方塊之字串的指標。此參數可以是以 Null 結尾的字串或傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼。如果此參數為 Null，工作對話方塊中不會顯示驗證核取方塊。如果TaskDialogIndirect的pfVerificationFlagChecked參數為Null，則不會啟用核取方塊。

pszExpandedInformation

類型： PCWSTR

參考要用來顯示其他資訊的字串指標。此參數可以是以 Null 結尾的字串或傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼。視是否指定TDF_EXPAND_FOOTER_AREA旗標而定，其他資訊會顯示在內容下方或頁尾文字下方。如果為 dwFlags 成員指定TDF_ENABLE_HYPERLINKS旗標，則此字串可能包含格式 < 為：HREF=「可執行檔字串」 > 超連結文字 < /A > 。 警告：使用不安全來源的內容時啟用超連結可能會導致安全性弱點。

pszExpandedControlText

類型： PCWSTR

參考要用來標記按鈕以折迭可展開資訊的字串指標。此參數可以是以 Null 結尾的字串或傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼。當 pszExpandedInformation 成員為 Null時，會忽略這個成員。如果此成員為 Null ，且已指定 pszCollapsedControlText ，則 pszCollapsedControlText 值也會用於此成員。

pszCollapsedControlText

類型： PCWSTR

參考要用來標記按鈕以展開可展開資訊的字串指標。此參數可以是以 Null 結尾的字串或傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼。當 pszExpandedInformation 成員為 Null時，會忽略這個成員。如果此成員為 Null ，且已指定 pszCollapsedControlText ，則 pszCollapsedControlText 值也會用於此成員。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.hFooterIcon

類型： HICON

要在工作對話方塊頁尾中顯示的圖示控制碼。除非指定TDF_USE_HICON_FOOTER旗標，而且 pszFooterIcon 不是，否則會忽略這個成員。如果此成員為 Null ，且已指定TDF_USE_HICON_FOOTER，則不會顯示任何圖示。

DUMMYUNIONNAME2.pszFooterIcon

類型： PCWSTR

參考要在工作對話方塊頁尾區域中顯示之圖示的指標。如果指定TDF_USE_HICON_FOOTER旗標，或 pszFooter 為 Null，則會忽略此參數。否則，如果此參數為 Null 或 hInstance 參數為 Null，則不會顯示任何圖示。此參數必須是傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼，或 針對 pszMainIcon列出的其中一個預先定義值。

pszFooter

類型： PCWSTR

要用於工作對話方塊頁尾區域之字串的指標。此參數可以是以 Null 結尾的字串或傳遞至 MAKEINTRESOURCE 宏的整數資源識別碼。如果為 dwFlags 成員指定TDF_ENABLE_HYPERLINKS旗標，則此字串可能包含此格式的超連結。

<A HREF="executablestring">Hyperlink Text</A>

警告使用不安全來源的內容時啟用超連結可能會導致安全性弱點。

pfCallback

類型： PFTASKDIALOGCALLBACK

應用程式定義回呼函式的指標。如需詳細資訊，請參閱 TaskDialogCallbackProc。

lpCallbackData

類型： LONG_PTR

應用程式定義的參考資料的指標。這個值是由呼叫端所定義。

cxWidth

類型： UINT

工作對話方塊工作區的寬度，以對話方塊單位為單位。如果為 0，工作對話方塊管理員會計算理想的寬度。

規格需求


最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
標頭	commctrl.h

共用方式為

TASKDIALOGCONFIG 結構 (commctrl.h)

語法

成員

規格需求

意見反應

其他資源