Vista TaskDialog 包装器和模拟器

• 下载源代码和测试项目 - 93.57 KB

引言

在像狂躁的松鼠一样在网上花费了无数时间寻找在 Vista 之前版本的 Windows 上使用 Vista TaskDialog 的方法后，我决定自己写一个。“Necessity is the mother of invention。”（必要是发明之母）。当我需要帮助时，我经常访问 The Code Project 网站，我想是时候回馈社区了。因此，有了这篇文章。

背景

基本上，我想要一个类来包装 TaskDialog，这样在 Vista 机器上，它就会调用 COMCTL32.dll v6（随 Vista 一起提供）中的原生 TaskDialog，而在 Vista 之前的机器上，它会用一个几乎完全相同的替代品来模拟 TaskDialog 。我必须非常感谢 KevinGre 他那篇精彩的文章“TaskDialog for WinForms”，它包装了 COMCTL32 TaskDialog API。他代码中唯一的改动如下：

1. 为了清晰起见，在类/枚举/结构名称前加上“VistaXxxx”（例如 TaskDialog -> VistaTaskDialog）
2. 实现了他文章底部评论区提到的 x64 机器的 bug 修复

这个项目比 Kevin 的工作更进一步，它使得 TaskDialog 不再局限于 Windows Vista。现在你可以使用相同的代码显示 TaskDialog ，而无需担心 Windows 版本。

Using the Code

这个项目的命名空间是 PSTaskDialog（Pioneer Software 是 我的公司），我们真正需要了解的唯一类是 static public class cTaskDialog（方便地位于 cTaskDialog.cs 中）。cTaskDialog 类包含许多 static public 方法来执行 TaskDialog。主要方法是 ShowTaskDialogBox。我说“主要”是因为这个例程做了所有的工作，并显示了 Vista TaskDialog 或模拟版本。cTaskDialog 中的所有其他方法最终都会调用这个方法来调用 TaskDialog。

static public DialogResult ShowTaskDialogBox(IWin32Window ParentWindow,
                                             string Title,
                                             string MainInstruction,
                                             string Content,
                                             string ExpandedInfo,
                                             string Footer,
                                             string VerificationText,
                                             string RadioButtons,
                                             string CommandButtons,
                                             eTaskDialogButtons Buttons,
                                             eSysIcons MainIcon,
                                             eSysIcons FooterIcon)

示例 1：使用完整的 ShowTaskDialogBox 方法

DialogResult res =
  PSTaskDialog.cTaskDialog.ShowTaskDialogBox(this,
                                             "The main instruction text for
                                             the TaskDialog goes here.",
                                            "The content text for the task
                                             dialog is shown here and the
                                             text will automatically wrap as
                                             needed.",
                                            "Any expanded content text for
                                             the task dialog is shown here
                                             and the text will automatically
                                             wrap as needed.",
                                            "Optional footer text with an
                                             icon can be included",
                                            "Don't show me this message
                                             again",
                                            "Radio Option 1|Radio Option 2|
                                             Radio Option 3",
                                            "Command Button 1
                                             |Command Button 2\nLine 2\nLine 3
                                              |Command Button 3",
                                            PSTaskDialog.eTaskDialogButtons.
                                            OKCancel,
                                            PSTaskDialog.eSysIcons.
                                            Information,
                                            PSTaskDialog.eSysIcons.Warning);

这是上面内容的截图（在 Vista 上以模拟模式运行）。

需要注意的一些事项。

1. string RadioButtons 和 string CommandButtons 参数是管道（|）分隔的 string，分别包含单选按钮和命令按钮的每个项。
2. 将空 string ("") 发送到某些参数将禁用（即隐藏）TaskDialog 的某些功能，具体如下：
   • ExpandedInfo（“显示详细信息”部分）
   • Footer（带图标的底部页脚）
   • VerificationText（“不再显示此消息”复选框）
   • RadioButtons（单选按钮）
   • CommandButtons（命令按钮）
3. 除了 DialogResult 返回值外，执行 TaskDialog 后您可能需要了解的其他信息保存在 cTaskDialog 的以下 static public 变量中：
   • VerificationChecked （“不再显示此消息” CheckBox 是否被选中）
   • RadioButtonResult （所选 RadioButton 的 0 基索引）
   • CommandButtonResult （点击的 CommandButton 的 0 基索引）

   请注意：我意识到有些人可能认为 ref 参数是比 public static 方法更好的检索这些值的方式。请随时根据您的喜好修改代码！

4. cTaskDialog 还有一些其他的 static public 变量需要考虑：
   • EmulatedFormWidth （默认 450）。这是模拟窗体的宽度。Vista 似乎会根据内容对 TaskDialog 进行一些智能的动态调整。根据我的测试，450 像素似乎是一个合理的宽度（在大多数情况下与 Vista 非常相似），并且对于大多数 TaskDialog 场景来说看起来都不错。如果您愿意，可以在执行 TaskDialog 之前更改此值。
   • ForceEmulationMode 是一个 bool 类型变量，它强制在 Vista 机器上使用模拟的 Windows Forms 版本的 TaskDialog （这主要是为了测试目的，因为在运行 Vista 时没有真正的原因使用模拟模式）。
   • UseToolWindowOnXP （1.02 版新增）是一个 bool 类型变量，它使 TaskDialog 在 Vista 之前的系统上使用 ToolWindow 。我认为它比厚厚的对话框标题栏更符合 Vista 的外观。
   • PlaySystemSounds（1.03 版新增）是一个 bool 类型变量，它决定了 TaskDialog 在显示时是否播放默认系统声音（与 MainIcon 类型关联）。此值默认为 true，因此将其设置为 false 可禁止声音。

示例 2：显示 MessageBox

PSTaskDialog.cTaskDialog.MessageBox(this,
                                   "MessageBox Title",
                                   "The main instruction text for the
                                    message box is shown here.",
                                   "The content text for the message box
                                    is shown here and the text will
                                    automatically wrap as needed.",
                                   "Any expanded content text for the
                                    message box is shown here and the text
                                    will automatically wrap as needed.",
                                   "Optional footer text with an icon can be
                                    included",
                                   PSTaskDialog.eTaskDialogButtons.YesNo,
                                   PSTaskDialog.eSysIcons.Information,
                                   PSTaskDialog.eSysIcons.Error);

下面是在 Windows XP 上显示上述内容的截图。请将此图像与本文开头的两个图像进行比较。生成这些对话框的代码完全相同。

示例 3：显示一个更简单的 MessageBox

PSTaskDialog.cTaskDialog.MessageBox(this,
                                   "MessageBox Title",
                                   "The main instruction text for the
                                    message box is shown here.",
                                   "The content text for the message box
                                    is shown here and the text will
                                    automatically wrap as needed.",
                                    PSTaskDialog.eTaskDialogButtons.OK,
                                    PSTaskDialog.eSysIcons.Warning);

if (PSTaskDialog.cTaskDialog.VerificationChecked)
{
  // persist the user's choice here

  // e.g. write a registry entry to remember not to show this next time

}

示例 4：显示单选列表框

PSTaskDialog.cTaskDialog.ShowRadioBox(this,
                                       "RadioBox Title",
                                       "The main instruction text for the
                                       radiobox is shown here.",
                                      "The content text for the radiobox is
                                       shown here and the text will
                                       automatically wrap as needed.",
                                      "Any expanded content text for the
                                       radiobox is shown here and the text
                                       will automatically wrap as needed.",
                                      "Optional footer text with an icon
                                       can be included",
                                      "Don't show this message again",
                                      "Radio Option 1|Radio Option 2|
                                       Radio Option 3|Radio Option 4|
                                       Radio Option 5",
                                      PSTaskDialog.eSysIcons.Information,
                                      PSTaskDialog.eSysIcons.Warning);

示例 5：显示命令按钮

PSTaskDialog.cTaskDialog.ShowCommandBox(this,
                                        "CommandBox Title",
                                       "The main instruction text for the
                                        commandbox is shown here.",
                                       "The content text for the commandbox
                                        is shown here and the text will
                                        automatically wrap as needed.",
                                       "Any expanded content text for the
                                        commandbox is shown here and the text
                                        will automatically wrap as needed.",
                                       "Optional footer text with an icon
                                        can be included",
                                       "Don't show this message again",
                                       "Command Button 1|Command Button 2|
                                        Command Button 3|Command Button 4",
                                       true,
                                       PSTaskDialog.eSysIcons.Information,
                                       PSTaskDialog.eSysIcons.Warning);

请查看 TaskDialogTest 文件夹中的 Form1.cs 源代码，了解 cTaskDialog 在您的代码中是如何使用的。

已知限制

• 我**没有**在模拟的 TaskDialog 中实现 ProgressBar 功能，主要是因为我自己不需要它。如果您想添加此功能，改编代码应该不难。
• 我省略了 Vista 上可用的**盾牌**图标，因为 System.Drawing.SystemIcons（被模拟窗体使用）没有这个图标。
• 奇怪的是，Vista TaskDialog 中没有**问号**图标，所以在 Vista 上指定 eSysIcons.Question 时，Vista TaskDialog 会使用**信息**图标。

历史

• 12/11/2007 v1.0
• 首次发布
• 12/11/2007 v1.01
• 对 RadioButton 布局和 CommandButton 字体进行了视觉调整，使其更具“Vista 风格”
• 将 public enum 移出了 frmTaskDialog（这样更合理）
• 15/11/2007 v1.02
• 添加了新的 cTaskDialog.UseToolWindowOnXP（详情请参见上文）；CommandButtons 现在接受 string 中的 \n 来换行并显示较小的文本
• 进行了一些额外的视觉调整，使其看起来更像“Vista”（如果这算一个词的话？！）
• 25/11/2007 v1.03
• 添加了新的 cTaskDialog.PlaySystemSounds（感谢 logan1337）
• “主指令”文本和命令按钮文本现在使用 ClearTypeGridFit 文本渲染进行绘制，以获得更具 Vista 风格的外观（感谢 Thorsten Dittmar）
• 06/07/2009 v1.04 
• 所有的 public 例程现在都可以接受一个 IWin32Window Owner 作为第一个参数。这提供了对 Vista（或 Windows 7）和 XP 中 TaskDialog 父级的更多控制（感谢 grahamoneale）。我添加了许多重载例程，因此如果省略 Owner，则假定为 null，但指定 Owner 窗体是一个好习惯。
• 实现了图像大小调整改进（感谢 TheDesertFox）
• 改进了 Dispose 代码（感谢 veki-peki）
• CommandButton 现在可以用作独立按钮（感谢 SDragon42）
• 加速键现在可以正确绘制（感谢 Member243669）