3. Revit API UI: TaskDialog

3. Revit API UI: TaskDialog

这一篇，我们简单讲一下Dialog相关API，UI中，有几个相关的类，TaskDialog、ColorSelectionDialog、FileDialog及其子类，前者是本篇重点，后面的就附带讲一下的，都比较简单。

---

TaskDialog

TaskDialog和 Winform 的MessageBox，JS 的alert很像，可以方便的输出一些信息，所以在测试中好用，毕竟附加到程序的调试不够快捷。TaskDialog 具体是什么样子的呢，我们来看看文档。

文档中，是这么介绍 TaskDialog 的：任务对话框（Task Dialog）是一种用于向用户显示信息并接收简单输入的对话框。它具有一组通用的控件，这些控件按照标准顺序排列，以确保外观和感觉的一致性。

从介绍我们可以得出几个点：①显示信息；②具备简单交互功能；③控件排布顺序是固定的。

基于这三点认识，我们来好好了解一下它。

类结构

TaskDialog 有三个静态方法，作用都是一样的，就是输出一个信息。

TaskDialog.Show("title","mainInstruction");  // MainInstruction

主要属性：

属性	说明
Title	标题
MainIcon	主内容前的Icon，枚举类型，有5种，默认None。Icon长这样：
MainInstruction	大号字体的内容，在最上方，接着Icon显示。
MainContent	小号字体的内容，在MainInstruction的下方。
ExtraCheckBoxText	一个带内容的复选框，不可与VerificationText同时使用。
ExpandedContent	默认隐藏的信息，分两部分，一是内容，二是显示隐藏切换按钮。
CommonButtons	自定义按钮，枚举类型，有 7 种。可以设置多个，每种都可以设置处理结果。
VerificationText	一个带内容的复选框，不可与ExtraCheckBoxText 同时使用。
FooterText	放在最底部的文字，相当于Word的页脚。

主要方法：

方法	说明
AddCommandLink(TaskDialogCommandLinkId, String) AddCommandLink(TaskDialogCommandLinkId, String, String)	TaskDialogCommandLinkId是枚举类型，有 4 个值，CommandLink(1~4)， 这表明最多只能设置4个选择。
Show()::TaskDialogResult	显示弹窗，返回TaskDialogResult枚举类型，有 7+4=11 种。 意味着每种都可以判断与处理。
WasExtraCheckBoxChecked() WasVerificationChecked()	检查复选框是否勾选了

显示排布

前面说控件的排布顺序是固定的，上面介绍属性的时候，也稍微提了一点，但再怎么说，都不如看图直观易懂，看图。

补充：FooterText单独占一栏（隐约看到白线隔开），在最下面，而VerificationText在FooterText上面的左侧，右侧被CommonButtons占用了。

使用示例

看代码，代码是上图的效果。

public void ShowTaskDialog()
{
    TaskDialog taskDialog = new TaskDialog("DialogDemo标题")
    {
        MainInstruction = "Main Instruction：顶部大号主要文本",
        MainContent = "Main Content：中间的小号文本",
        FooterText = "Footer Text：底部的小号文本",

        ExtraCheckBoxText = "Extra CheckBox Text：显示在这个位置，不可与 VerificationText 同时使用",
        ExpandedContent = "Expanded Content：默认隐藏的内容，在用户按下“查看详细信息”按钮时显示",
        //VerificationText = "Verification Text：显示在靠近底部位置，不可与 ExtraCheckBoxText 同时使用",

        MainIcon = TaskDialogIcon.TaskDialogIconShield,
        CommonButtons = TaskDialogCommonButtons.Ok | TaskDialogCommonButtons.Cancel,  // 添加俩按钮
        DefaultButton = TaskDialogResult.Cancel
    };
    taskDialog.AddCommandLink(TaskDialogCommandLinkId.CommandLink1, "Command Link 1", "Command Link 1 Content");
    taskDialog.AddCommandLink(TaskDialogCommandLinkId.CommandLink2, "Command Link 2", "Command Link 2 Content");

    TaskDialogResult tashResult = taskDialog.Show();

    // 每种结果都可以设置处理程序
    if (tashResult == TaskDialogResult.Cancel) { TaskDialog.Show("Dialog(2)", "You clicked Cancel."); }
    else if (tashResult == TaskDialogResult.Ok) { TaskDialog.Show("Dialog(2)", "You clicked OK."); }
    else if (tashResult == TaskDialogResult.CommandLink1) { TaskDialog.Show("Dialog(2)", "You clicked Command Link 1."); }
    else if (tashResult == TaskDialogResult.CommandLink2) { TaskDialog.Show("Dialog(2)", "You clicked Command Link 2."); }
}

---

ColorSelectionDialog

这个就是简单了，就一个弹窗，选择颜色，确定或者取消关闭，看个样吧。

OriginalColor：图中左下角的“原始颜色”

SelectedColor：图中左下角的“新建颜色”

public void ShowColorSelectionDialog()
{
    ColorSelectionDialog colorSelectionDialog = new ColorSelectionDialog();
    ItemSelectionDialogResult colorResult = colorSelectionDialog.Show();
    if (colorResult == ItemSelectionDialogResult.Confirmed)
    {
        TaskDialog.Show("Dialog(3)", $"You clicked Confirmed. SelectedColor is 0x{this.ColorToInt(colorSelectionDialog.SelectedColor)}");
    }
    else if (colorResult == ItemSelectionDialogResult.Canceled)
    {
        TaskDialog.Show("Dialog(3)", $"You clicked Canceled. OriginalColor is 0x{this.ColorToInt(colorSelectionDialog.OriginalColor)}");
    }
}

private int ColorToInt(Color color)
{
    return color.Red << 16 | color.Green << 8 | color.Blue;
}

结尾

这篇就这么点内容了，至于FileDialog就略过了。