Share via

TASKDIALOGCONFIG 結構 (commctrl.h)

  • 發行項

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