TaskDialog of Revit API – 1: A Comprehensive TaskDialog Example

The TaskDialog of Revit API is a counterpart of the .NET MessageBox class, it looks like.
It provides more customization capabilities than the .NET MessageBox class such as message categorizations,  a few more buttons/links, an indicator of whether something is checked off, and a hide and show trick.

The most important thing may be that it can provide a consistent user interface appearance. In this article and some following ones, let’s look at some details about the TaskDialog class of Revit API.
Let’s make some code to create a comprehensive TaskDialog meaning showing up everything possible and demonstrating all methods and properties that the API supports:

// Constructor stuff
TaskDialog td = new TaskDialog("TaskDialog Demonstration by Spiderinnet");

// Nice to set stuffs
td.Id = "ID_TaskDialog_Demonstration_by_Spiderinnet";
td.MainIcon = TaskDialogIcon.TaskDialogIconWarning;
td.Title = "This is 'Title'.";
td.TitleAutoPrefix = true;
td.AllowCancellation = true;

// Message related stuffs
td.MainInstruction = "This is 'MainInstruction'.";
td.MainContent = "This is 'MainContent'.";
td.FooterText = "This is 'FooterText'.";
td.ExpandedContent = "This is 'ExpandedContent'.\nLine1: blar blar...\nLine2: blar blar...\nLine3: blar blar...";

// VerificationText stuff
td.VerificationText = "This is 'VerificationText'.";

// Command link stuffs
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink1, "This is 'CommandLink1'.");
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink2, "This is 'CommandLink2'.");
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink3, "This is 'CommandLink3'.");
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink4, "This is 'CommandLink4'.");

// Common button stuffs
td.CommonButtons =
    TaskDialogCommonButtons.Cancel | TaskDialogCommonButtons.Ok | TaskDialogCommonButtons.Close |
    TaskDialogCommonButtons.No | TaskDialogCommonButtons.Yes | TaskDialogCommonButtons.Retry |
    TaskDialogCommonButtons.None;
td.DefaultButton = TaskDialogResult.Ok;

// Dialog showup stuffs
TaskDialogResult tdRes = td.Show();

MessageBox.Show(string.Format("Button result: {0}\nVerifictionText checked: {1}", tdRes.ToString(), td.WasVerificationChecked()));

 

If the above code is wrapped into an external command and in turn triggered by a ribbon item, PushButton for example, a TaskDialog like the following will appear:

 
 
Now it is clear that which property or method controls which part of the TaskDialog display.  The only thing needs a few more words to explain may be the TitleAutoPrefix property of the TaskDialog class and the ‘Command 17 – ‘ substring on the title of the TaskDialog display.

Does it point to the Assembly name, FullClassName, or Name of the Application AddIn as specified in the manifest file of the test Revit Addin?

<AddIn Type="Application">
 <Assembly>C:\Temp\RevitAddinCSProject\bin\Debug\RevitAddinCSProject.dll</Assembly>
 <FullClassName>RevitAddinCSProject.ExtApp</FullClassName>
 <ClientId>53505c47-958b-424a-9773-74d860b3bc58</ClientId>
 <Name>RevitAddinCSProject</Name>
</AddIn>

No. Obviously, none of them is the target of the TitleAutoPrefix aims at.

If the code snippet of the PushButton definition is found and appended below, things are clear:

PushButtonData itemData17 = new PushButtonData("itemName17", "Command 17", AssemblyFullName, "RevitAddinCSProject.TaskDialogTest");
PushButton item17 = group1.AddPushButton(itemData17) as PushButton;
item17.ToolTip = itemData17.Text;  // Can be changed to a more descriptive text.
item17.Image = new BitmapImage(new Uri(Path.Combine(AssemblyPath, "Standalone_Item1_16x16.bmp"), UriKind.Absolute));
item17.LargeImage = new BitmapImage(new Uri(Path.Combine(AssemblyPath, "Standalone_Item1_32x32.bmp"), UriKind.Absolute));

That is, the TitleAutoPrefix property of the TaskDialog was trying hard to find the Text of the PushButton and use it as the title prefix. It does not use the class name of the external command either as in our case the class name is ‘TaskDialogTest’ which is also shown in the above code.
People may wonder then:

 
• What will happen if the external command is trigged by some other ribbon items such as ToggleButton?
• What will happen if the external command is registered in the manifest file and in turn triggered by the External Command menu item directly?

Things are not clear at this point but it may not be hard to find out. You guys can give it a try and see what will be going on if you like.

If the little tiny thing ‘See details’ is clicked, the TaskDialog will be expanded and the ExpandedContent show up:
 
 
Before closing this topic, let’s talk a bit about those right green arrow things.  They are not something like hyperlinks or can be used to pop up some children dialogs or something like that. Instead, they behave exactly the same as those OK, Yes, No, Retry, Cancel, Close buttons though they look a bit nicer and much bigger. That is, when one of them is clicked, the TaskDialog will close and a TaskDialogResult return telling which ‘CommandLink’ has been clicked.

TaskDialoger of RevitAddinWizard can help create the code automatically.

Our Software http://netspiderstudio.com/Software.html 
Support: mailto:[email protected]
Query: mailto:[email protected]
Blog: http://spiderinnet.typepad.com
More: http://netspiderstudio.com