[Resource] TaskDialog Class (Updated 25/08/2008)

TaskDialog Class
Last updated on 25 August 2008

What the...?
The TaskDialog class provides easy access to the task dialog functionality of Windows Vista or higher.

What's a task dialog?
A task dialog is the brand new replacement for the good old "message box". It has much more customisable areas than the message box and is much more flexible.

What's in a task dialog?
Following is a description of the different parts of a task dialog. Note that not all parts have to be displayed in every task dialog, only the parts you define will be displayed.

Title - The text what is displayed in the title bar.
Main icon - The icon displayed next to the content.
Main instruction - The text displayed as heading of the task dialog.
Content - The actual content of the task dialog.
Radio buttons - A list of custom radio buttons.
Common buttons - Some standard buttons (such as OK, Cancel, Yes and No). Unlike the old message box, the task dialog allows any combination of these buttons, so you are free to use "OK/Cancel/Retry" or "Yes/No/Retry".
Custom buttons - Extra buttons added to display. If you enable command links, such as in the screenshot, the buttons are displayed as command links. Otherwise, they are displayed next to the common buttons.
Expand/Collapse button - The button to toggle the expandable area. You can change the text on this button (both in expanded as collapsed state).
Verification checkbox - A checkbox displayed at the left of the common buttons, usually used for a verification like "Do not show this message again" but you can use it for anything you like.
Footer - The text displayed at the bottom of the window, used for footnotes or additional information. Can have an icon.
Expandable area - The text toggled by the expand/collapse button.

Okay, how do I use this?
The class consists of a lot of properties and methods which allow you to configure the task dialog and finally show it. Here's a quick instruction guide to get started quickly:

Create a new instance of the TaskDialog class.

code:
var MyDialog = new TaskDialog();
Set your desired properties and call any method you need to prepare the task dialog.

code:
MyDialog.Title = "My task dialog";
MyDialog.Content.Instruction = "Installation successful";
MyDialog.Content.Text = "Do you want to start the program now?";
MyDialog.Content.SetIcon(TaskDialog.Icons.Question);
MyDialog.CommonButtons.Add("Yes", "No");
Open the task dialog using either Show() or ShowAndDestroy().

code:
var Result = MyDialog.Show();
The return value of Show() is an object with information about the user's input. If the function succeeds, the following members are available:
- btn : String identifier of the clicked button.
- radio : String identifier of the selected radio button.
- verif : Boolean specifying whether the verification checkbox was checked.
- result : Number specifying the return value of the call to "TaskDialogIndirect". This equals S_OK (0x0) when the function succeeds.
If the function fails, the following members are available:
- lastError : Number specifying the result of Interop.GetLastError() after "TaskDialogIndirect" was called.
- result : Number specifying the return value of the call to "TaskDialogIndirect".
You can re-use the class instance to show more than one dialog per instance.

code:
...
MyDialog.Show();
...
MyDialog.Content.Text = "New content goes here";
MyDialog.Show();
When you're done using the instance, call Destroy() to clear any created memory structures used by the class. Alternatively, you can use ShowAndDestroy() which combines Show() and Destroy().
Note: Even after calling Destroy(), you can still re-use the instance! All required structures will be regenerated once you call Show(). Don't forget to destroy your instance at the very end however!

Where can I learn more about the actual properties, methods and child objects?
The script file of the class has a huge comment block with information about everything in the class. Use it as a reference, but don't forget to remove it when you're about to release your script! It'd be a waste of kilobytes to keep all those lines of comments in a file which may be downloaded by hundreds or thousands of users.

Right, where can I get this class thing?
» Download the TaskDialog Example script
» Download the TaskDialog class only

Change-log:

1.0.1 @ 25 August 2008 - Small code restructure. No changes were made to the structure of the properties and methods so your script doesn't need any changes to work with this update.
1.0.0 @ 23 August 2008 - Initial release

Screenshot:
[Image: TaskDialogClass.png]

Shoutbox

login | register | shoutbox