如何使用TTaskDialog？

Question

如何使用 TTaskDialog 类（在 Delphi 2009 及更高版本中）？ 官方文档没有帮助。事实上，通过使用 CodeInsight 或 VCL 源代码检查类，您可以学到更多东西。那里没有教学解释，但至少也没有错误（嗯，只有几个）。

就在最近，我想知道如何响应对话框中的超链接点击。事实上，通过设置 tfEnableHyperlinks 标志，您可以在对话框的文本部分中包含 HTML 超链接。 （嗯，文档关于该标志是这样说的：“如果设置了，内容、页脚和扩展文本可以包含超链接。”当然，“显然”链接是使用 实现的HTML 元素。）我自己发现，您使用 OnHyperLinkClick 事件来响应超链接的点击。但这个事件是一个TNotifyEvent，那么你如何知道点击了哪个链接呢？嗯，文档没有提到这一点，所以我不得不猜测。最终我发现对话框的 URL 公共属性已设置，因此我可以执行

procedure TmainFrm.TaskDialogHyperLinkClicked(Sender: TObject);
begin
  if Sender is TTaskDialog then
    with Sender as TTaskDialog do
      ShellExecute(0, 'open', PChar(URL), nil, nil, SW_SHOWNORMAL);
end;

官方文档所述，关于此属性：

URL 包含任务的 URL 对话框。

现在，你必须承认，这是一个很好的解释！但比这更糟糕的是：文档不仅缺乏解释，而且还包含错误。 例如，

ExpandButtonCaption：此按钮的附加信息。

这不太准确。什么按钮？如果您显示此特定属性的帮助，它会显示

ExpandButtonCaption 包含展开标题时要显示的附加文本。

也不好。什么字幕？正确的解释是

ExpandButtonCaption 是按钮旁边显示的文本，可让用户展开对话框以显示更多信息。例如，此属性可能是“更多详细信息”。

无论如何，目前，我正在尝试创建一个带有两个命令链接按钮的对话框。我知道操作系统可以显示这些按钮，并带有标题和较长的解释，但我似乎无法使用 TTaskButton 使其工作。文档不太好。

但我不会问如何在 SO 实现这一特定目标，而是问另一个问题：

TTaskDialog 类有任何（非官方）文档吗？

Answer 1

如果您找不到文档，请编写它：

任务对话框的 Hello World

with TTaskDialog.Create(Self) do
  try
    Caption := 'My Application';
    Title := 'Hello World!';
    Text := 'I am a TTaskDialog, that is, a wrapper for the Task Dialog introduced ' +
            'in the Microsoft Windows Vista operating system. Am I not adorable?';
    CommonButtons := [tcbClose];
    Execute;
  finally
    Free;
  end;

Caption 是窗口标题栏中显示的文本，Title 是标题，Text 是对话框的正文。不用说，执行会显示任务对话框，结果如下所示。 （我们将在一两节中返回到 CommonButtons 属性。）

做一个有礼貌的公民

当然，如果在没有任务对话框 API 的 Windows XP 下运行，任务对话框会使程序崩溃。如果视觉主题被禁用，它也将不起作用。在任何这种情况下，我们都需要坚持使用老式的 MessageBox。因此，在实际应用程序中，我们需要执行以下操作：

if (Win32MajorVersion >= 6) and ThemeServices.ThemesEnabled then
  with TTaskDialog.Create(Self) do
    try
      Caption := 'My Application';
      Title := 'Hello World!';
      Text := 'I am a TTaskDialog, that is, a wrapper for the Task Dialog introduced ' +
              'in the Microsoft Windows Vista operating system. Am I not adorable?';
      CommonButtons := [tcbClose];
      Execute;
    finally
      Free;
    end
else
  MessageBox(Handle,
             'I am an ordinary MessageBox conveying the same message in order to support' +
             'older versions of the Microsoft Windows operating system (XP and below).',
             'My Application',
             MB_ICONINFORMATION or MB_OK);

在本文的其余部分中，我们将假设税，而是仅专注于任务对话框。

对话框的类型。模态结果

CommonButtons 属性的类型为 TTaskDialogCommonButtons，定义为

TTaskDialogCommonButton = (tcbOk, tcbYes, tcbNo, tcbCancel, tcbRetry, tcbClose);
TTaskDialogCommonButtons = set of TTaskDialogCommonButton;

该属性确定对话框中显示的按钮（如果没有手动添加按钮，我们稍后会这样做） 。如果用户单击其中任何按钮，则在 Execute 返回后，相应的 TModalResult 值将存储在 ModalResult 属性中。 MainIcon 属性确定对话框中显示的图标，并且当然应该反映对话框的性质，按钮组也应该如此。 MainIcon 形式上是一个整数，可以设置为 tdiNone、tdiWarning、tdiError、 中的任何值tdiInformation 和 tdiShield。

with TTaskDialog.Create(Self) do
  try
    Caption := 'My Application';
    Title := 'The Process';
    Text := 'Do you want to continue even though [...]?';
    CommonButtons := [tcbYes, tcbNo];
    MainIcon := tdiNone; // There is no tdiQuestion
    if Execute then
      if ModalResult = mrYes then
        beep;
  finally
    Free;
  end;

以下是其余图标类型的示例（分别为屏蔽、警告和错误）：

< img src="https://specials.rejbrand.se/TTaskDialog/taskdialog3.png" alt="TTaskDialog 示例">

最后，您应该知道可以使用 < code>DefaultButton 属性设置对话框中的默认按钮。

with TTaskDialog.Create(Self) do
  try
    Caption := 'My Application';
    Title := 'The Process';
    Text := 'Do you want to continue even though [...]?';
    CommonButtons := [tcbYes, tcbNo];
    DefaultButton := tcbNo;
    MainIcon := tdiNone;
    if Execute then
      if ModalResult = mrYes then
        beep;
  finally
    Free;
  end;

自定义按钮

您可以将自定义按钮添加到任务对话框。事实上，您可以将 CommonButtons 属性设置为空集，并完全依赖自定义按钮（并且此类按钮的数量也不受限制）。以下实际示例显示了这样一个对话框：

with TTaskDialog.Create(self) do
  try
    Title := 'Confirm Removal';
    Caption := 'Rejbrand BookBase';
    Text := Format('Are you sure that you want to remove the book file named "%s"?', [FNameOfBook]);
    CommonButtons := [];
    with TTaskDialogButtonItem(Buttons.Add) do
    begin
      Caption := 'Remove';
      ModalResult := mrYes;
    end;
    with TTaskDialogButtonItem(Buttons.Add) do
    begin
      Caption := 'Keep';
      ModalResult := mrNo;
    end;
    MainIcon := tdiNone;
    if Execute then
      if ModalResult = mrYes then
        DoDelete;
  finally
    Free;
  end

命令

链接任务对话框按钮可以是命令链接。这是通过设置 tfUseCommandLinks 标志（在 Flags 中）来实现的。现在您还可以设置 CommandLinkHint （每个按钮）属性：

with TTaskDialog.Create(self) do
  try
    Title := 'Confirm Removal';
    Caption := 'Rejbrand BookBase';
    Text := Format('Are you sure that you want to remove the book file named "%s"?', [FNameOfBook]);
    CommonButtons := [];
    with TTaskDialogButtonItem(Buttons.Add) do
    begin
      Caption := 'Remove';
      CommandLinkHint := 'Remove the book from the catalogue.';
      ModalResult := mrYes;
    end;
    with TTaskDialogButtonItem(Buttons.Add) do
    begin
      Caption := 'Keep';
      CommandLinkHint := 'Keep the book in the catalogue.';
      ModalResult := mrNo;
    end;
    Flags := [tfUseCommandLinks];
    MainIcon := tdiNone;
    if Execute then
      if ModalResult = mrYes then
        DoDelete;
  finally
    Free;
  end

tfAllowDialogCancellation 标志将恢复关闭的系统菜单项（和标题栏按钮——事实上，它将恢复整个系统菜单）。

不要向最终用户抛出技术细节

您可以使用属性 ExpandedText< /code> 和 ExpandedButtonCaption 添加一段文本（前者），仅在用户单击按钮（后一个属性中文本的左侧）请求它后才显示。

with TTaskDialog.Create(self) do
  try
    Title := 'Confirm Removal';
    Caption := 'Rejbrand BookBase';
    Text := Format('Are you sure that you want to remove the book file named "%s"?', [FNameOfBook]);
    CommonButtons := [];
    with TTaskDialogButtonItem(Buttons.Add) do
    begin
      Caption := 'Remove';
      CommandLinkHint := 'Remove the book from the catalogue.';
      ModalResult := mrYes;
    end;
    with TTaskDialogButtonItem(Buttons.Add) do
    begin
      Caption := 'Keep';
      CommandLinkHint := 'Keep the book in the catalogue.';
      ModalResult := mrNo;
    end;
    Flags := [tfUseCommandLinks, tfAllowDialogCancellation];
    ExpandButtonCaption := 'Technical information';
    ExpandedText := 'If you remove the book item from the catalogue, the corresponding *.book file will be removed from the file system.';
    MainIcon := tdiNone;
    if Execute then
      if ModalResult = mrYes then
        DoDelete;
  finally
    Free;
  end

下图显示了用户单击按钮以显示其他详细信息后的对话框。

如果添加 tfExpandFooterArea 标志，则附加文本将改为页脚中显示：

在任何情况下，您都可以打开对话框，其中的详细信息已展开通过添加 tfExpandedByDefault 标志。

自定义图标

您可以在任务对话框中使用任何自定义图标，方法是使用 tfUseHiconMain 标志并指定要在 CustomMainIcon 属性中使用的 TIcon。

with TTaskDialog.Create(self) do
  try
    Caption := 'About Rejbrand BookBase';
    Title := 'Rejbrand BookBase';
    CommonButtons := [tcbClose];
    Text := 'File Version: ' + GetFileVer(Application.ExeName) + #13#10#13#10'Copyright © 2011 Andreas Rejbrand'#13#10#13#10'http://english.rejbrand.se';
    Flags := [tfUseHiconMain, tfAllowDialogCancellation];
    CustomMainIcon := Application.Icon;
    Execute;
  finally
    Free;
  end

超链接

您甚至可以在对话框中使用类似 HTML 的超链接（在 Text、Footer、 和 ExpandedText），如果您仅添加 tfEnableHyperlinks 标志：

with TTaskDialog.Create(self) do
  try
    Caption := 'About Rejbrand BookBase';
    Title := 'Rejbrand BookBase';
    CommonButtons := [tcbClose];
    Text := 'File Version: ' + GetFileVer(Application.ExeName) + #13#10#13#10'Copyright © 2011 Andreas Rejbrand'#13#10#13#10'<a href="http://english.rejbrand.se">http://english.rejbrand.se</a>';
    Flags := [tfUseHiconMain, tfAllowDialogCancellation, tfEnableHyperlinks];
    CustomMainIcon := Application.Icon;
    Execute;
  finally
    Free;
  end

但是请注意，单击该链接时没有任何反应。链接的操作必须手动实现，这当然是一件好事。为此，请响应 OnHyperlinkClicked 事件，该事件是 TNotifyEvent。链接的 URL（即 a 元素的 href）存储在 TTaskDialog 的 URL 公共属性中：

procedure TForm1.TaskDialogHyperLinkClicked(Sender: TObject);
begin
  if Sender is TTaskDialog then
    with Sender as TTaskDialog do
      ShellExecute(0, 'open', PChar(URL), nil, nil, SW_SHOWNORMAL);
end;

procedure TForm1.FormCreate(Sender: TObject);
begin
  with TTaskDialog.Create(self) do
    try
      Caption := 'About Rejbrand BookBase';
      Title := 'Rejbrand BookBase';
      CommonButtons := [tcbClose];
      Text := 'File Version: ' + GetFileVer(Application.ExeName) + #13#10#13#10'Copyright © 2011 Andreas Rejbrand'#13#10#13#10'<a href="http://english.rejbrand.se">http://english.rejbrand.se</a>';
      Flags := [tfUseHiconMain, tfAllowDialogCancellation, tfEnableHyperlinks];
      OnHyperlinkClicked := TaskDialogHyperlinkClicked;
      CustomMainIcon := Application.Icon;
      Execute;
    finally
      Free;
    end
end;

页脚

您可以使用 Footer 和 FooterIcon 属性用于创建页脚。 icon 属性接受与 MainIcon 属性相同的值。

with TTaskDialog.Create(self) do
  try
    Caption := 'My Application';
    Title := 'A Question';
    Text := 'This is a really tough one...';
    CommonButtons := [tcbYes, tcbNo];
    MainIcon := tdiNone;
    FooterText := 'If you do this, then ...';
    FooterIcon := tdiWarning;
    Execute;
  finally
    Free;
  end

使用 tfUseHiconFooter 标志和 CustomFooterIcon 属性，您可以在页脚中使用任何自定义图标，就像您可以选择自己的主图标一样。

复选框

使用 VerificationText 字符串属性，您可以将复选框添加到任务对话框的页脚。复选框的标题是属性。

with TTaskDialog.Create(self) do
  try
    Caption := 'My Application';
    Title := 'A Question';
    Text := 'This is a really tough one...';
    CommonButtons := [tcbYes, tcbNo];
    MainIcon := tdiNone;
    VerificationText := 'Remember my choice';
    Execute;
  finally
    Free;
  end

您可以通过指定 tfVerificationFlagChecked 标志来使复选框最初处于选中状态。不幸的是，由于 TTaskDialog 的 VCL 实现中存在错误 (?)，当 Execute 返回时包含此标志并不反映复选框的最终状态。为了跟踪复选框，应用程序需要记住初始状态并切换内部标志作为对每个 OnVerificationClicked 事件的响应，该事件在每次复选框状态更改时都会触发。对话的形式。

单选按钮

单选按钮的实现方式与添加自定义按钮（或命令链接按钮）类似：

with TTaskDialog.Create(self) do
  try
    Caption := 'My Application';
    Title := 'A Question';
    Text := 'This is a really tough one...';
    CommonButtons := [tcbOk, tcbCancel];
    MainIcon := tdiNone;
    with RadioButtons.Add do
      Caption := 'This is one option';
    with RadioButtons.Add do
      Caption := 'This is another option';
    with RadioButtons.Add do
      Caption := 'This is a third option';
    if Execute then
      if ModalResult = mrOk then
        ShowMessage(Format('You chose %d.', [RadioButton.Index]));
  finally
    Free;
  end

Answer 2

这是旧内容，但为了完整性，我在此处添加此内容：

适用于 XP,Vista,7 的开源 SynTaskDialog 单元

TTaskDialog 单元在 XP（使用 VCL）下工作，但在 Vista+ 下使用系统 TaskDialog。

Answer 3

TMS 有一个很好的包装器，并且它还模拟在 XP 上运行时的新行为。这是一个快速插入。但它不是免费的，并且不能真正回答您的“如何”问题。

http://www.tmssoftware.com/site/vtd.asp

他们还有一些他们讨论对话框的文章，如果您想制作自己的包装器，那么一些源代码可能对您有用。

http://www.tmssoftware.com/site/atbdev5.asp

http://www.tmssoftware.com/site/atbdev7.asp

Answer 4

这是我的简短文档：

1. 不要使用它，除非您不希望您的应用程序在 XP 上运行。

2. 像其他人一样，对 delphi doc wiki 内容提出改进建议，但是请注意短语“注意：任务对话框需要 Vista 或 Windows 7”。这是“不要使用它！”的代码。基本上，有人想到了完全支持新的 Windows Vista 对话框，其实现方式是编写仅调用对话框 API 的包装器代码。由于没有向您提供后备功能，因此您在 XP 上运气不好。