Task Dialogs

Task Dialogs are Windows Vista's alternative to the classic Message Box (System.Windows.Forms.MessageBox on .NET) which has been used from times immemorial to notify the users about errors, status changes and to prompt for action. Task Dialogs have a much better looking interface and have many more interaction possibilities (customizable text buttons, radio buttons, progress bars, and so on...).

To get a full guide about Task Dialogs, refer to these MSDN pages:

TaskDialog static methods

The TaskDialog class has been designed to be used exactly as you used MessageBox on standard WinForms applications. The class exposes a set of common static methods which allow you to define highly customizable dialogs without instancing any object and making a single function call:

Basic Task Dialogs

The simplest TaskDialog call takes a single parameter:

TaskDialog.Show("Instruction");


taskdialog1.png

You can further customize your dialog with a custom title and verbose instructions:

TaskDialog.Show("Instruction", "My Task Dialog", "Verbose instructions.");


taskdialog2.png

The buttons that appear on the task dialog can be customized by providing one or more elements of the TaskDialogButton enumeration. Valid values are:
  • OK
  • Cancel
  • Yes
  • No
  • Close
  • Retry

TaskDialog.Show("Instruction", "My Task Dialog", "Verbose instructions.", TaskDialogButton.Retry | TaskDialogButton.Cancel);


taskdialog3.png

Like with MessageBox, you may customize the dialog's icon. All new Vista icons are included: from the classic Information and Warning, to the new Security warnings.

TaskDialog.Show("Instruction", "My Task Dialog", "Verbose instructions.", TaskDialogButton.Retry | TaskDialogButton.Cancel, TaskDialogIcon.Information);

  • Information: taskdialog4.png
  • Stop
  • Warning
  • SecurityError: taskdialog5.png
  • SecurityWarning: taskdialog6.png
  • SecuritySuccess: taskdialog7.png
  • SecurityShield
  • SecurityShieldGray
  • SecurityShieldBlue

Results

The static TaskDialog methods return results as a value of the Result enumeration. It may assume the following values (some values have no corresponding TaskDialogButton value and cannot be used via static method):
  • None
  • OK
  • Cancel
  • Abort
  • Retry
  • Ignore
  • Yes
  • No
  • Close

TaskDialog instances

To really exploit the power of Vista's Task Dialog library, you'll need to instance a TaskDialog object and customize it.

Creating an instance

The interface for creating an instance is identical to that of the static methods: you can define an instruction, a title, some content, icons and common buttons.

TaskDialog dlg = new TaskDialog("Instruction", "Title", "Verbose instruction.", TaskDialogButton.Cancel, TaskDialogIcon.Warning);
Results results = dlg.Show(this.Handle);

if(results.CommonButton == Result.Cancel)
	//...
else
	//...


But using this slightly less practical approach, you can define many other parameters and access the complete results set of the dialog.

Setting Properties

AllowDialogCancellation

Setting this property to true (default) allows the used to cancel the dialog even if no Cancel button has been added by you (by clicking ESC or the red X). If you set it to false, you prevent the user from canceling the dialog and force him/her to select one of the buttons.

Please note that if a button with the Cancel value is present, this property will be ignored and the user will be allowed to close the dialog as usual.

A dialog with this property set to true and without Cancel buttons:
taskdialog_nocancel.png

CanBeMinimized

If this property is true and the Task dialog is shown wihtout a parent handle, the user may minimize the dialog. Notice that the task dialog will be modal nonetheless.

taskdialog_minimize.png

Expanded information

Task Dialogs can display more information on request by the user. This is done by clicking on a special control which will trigger the vertical expansion of the dialog and make place for more text (which can be initially hidden or shown).

dlg.ExpandedInformation = "Expanded information.";
dlg.CollapsedControlText = "Collapsed control text";
dlg.ExpandedControlText = "Expanded control text";
dlg.IsExpanded = false;
dlg.ShowExpandedInfoInFooter = false;


ExpandedInformation is the actual text which will be displayed in the expanding section. CollapsedControlText and ExpandedControlText are optional and set the text of the button on the dialog bottom. The IsExpanded property (default false) allows you to define whether the expanded text is initially visible or not.
ShowExpandedInfoInFooter sets whether you'd like the information displayed just below the dialog's content or on the bottom of the dialog.

Not expanded:
taskdialog_expand1.png
Expanded:
taskdialog_expand2.png
Expanded on footer:
taskdialog_expand3.png

Common properties

The same information that can be set through the constructor can be set individually through properties:

dlg.Title = "Title";
dlg.Instruction = "Instruction";
dlg.Content = "Content.";
dlg.CommonButtons = TaskDialogButton.OK | TaskDialogButton.Cancel; ;
dlg.CommonIcon = TaskDialogIcon.Information;

Custom icon

Instead of using one of the common icons, you can easily set a custom icon to be displayed by your task dialog.

dlg.CustomIcon = new Icon("myicon.ico");


The icon can be any instance of System.Drawing.Icon.

Footer

The footer of a Task dialog is a gray area below the buttons that can optionally contain some information and a common (or a custom) icon. Custom icons can simply be provided as a standard System.Drawing.Icon instance.

dlg.Footer = "Footer info.";
dlg.FooterCommonIcon = TaskDialogIcon.SecurityError;
dlg.FooterCustomIcon = new Icon("myicon.ico");


taskdialog_footer.png

Verification checkbox

Task dialog's allow you to add a single "verification" checkbox with custom text and set its state.

dlg.VerificationText = "Verification";
dlg.IsVerificationChecked = true;


taskdialog_verification.png

Custom buttons

As shown before, you can freely use and mix the common buttons provided by the Task dialog class. One of the most powerful aspects of the library though, is given by the possibility of defining your own buttons with custom return codes and custom text. These custom buttons can be set very easily using the CustomButtons property:

dlg.CustomButtons = new CustomButton[] {
	new CustomButton(100, "Button 100"),
	new CustomButton(Result.Cancel, "Custom cancel")
};


As you can see, custom buttons are created by instancing objects from the CustomButton class. Each button can have an own text string and a return code (which may be a common code from the Result enumeration or a free integer value - just notice that values less than 9 are reserved by common buttons and may cause collisions).

Also note that you can mix common and custom buttons, like in the following task dialog:
taskdialog_custombutton.png

Command links

Task dialogs can obviously use Vista's brand new "Command Link" buttons instead of the more classic styled buttons on the bottom of the window.

dlg.CustomButtons = new CustomButton[] {
	new CustomButton(100, "Button 1"),
	new CustomButton(Result.Cancel, "Button 2\nDescription note.")
};

dlg.UseCommandLinks = true;


Note that when using command links you must define at least one custom button or the Show() call will raise an exception. You can also define a description note for the command link by inserting a '\n' newline code in the button text.

taskdialog_commandlink.png

Radio buttons

Task dialogs not only allow you to define custom buttons, you may also add a set of radio buttons to your dialog. This is done by setting the RadioButtons property with an array of CustomButton instances.

dlg.RadioButtons = new CustomButton[] {
	new CustomButton(1, "Radio button 1"),
	new CustomButton(2, "Radio button 2"),
	new CustomButton(3, "Radio button 3")
};
dlg.EnabledRadioButton = 2;
dlg.NoDefaultRadioButton = false;


EnabledRadioButton sets the ID of the radio button that will be selected automatically when the dialog is opened. If you do not provide any default enabled radio button, Windows will automatically select the first one of the list. You can override this behavour by setting NoDefaultRadioButton to true.

taskdialog_radio.png

IsShowing

IsShowing is a read-only property that returns true if the dialog is currently showing and false otherwise. This can be useful if you define event handlers for your task dialog.

PositionRelativeToWindow

By default, task dialogs are centered on the screen on which they are displayed. If you set this property to true, the dialog will be placed centered on its parent window (you must supply a handle to the parent window in the Show() call).

Progress bars

Task dialogs can optionally contain a progress bar indicating the progress of an action (check out the section of this page about events and ticks to find out how to update the progress bar).

dlg.ShowProgressBar = true;
dlg.ProgressBarState = VistaControls.ProgressBar.States.Paused;
dlg.ProgressBarMinRange = 0;
dlg.ProgressBarMaxRange = 100;
dlg.ProgressBarPosition = 50;
dlg.ShowMarqueeProgressBar = true;


The property ProgressBarState sets the color and the state of the progress bar (normal, paused/yellow and error/red), MaxRange, MinRange and Position set the numeric range of the progress bar and the current position. ShowMarqueeProgressBar enables a particular state of the progress bar that expresses activity but does not indicate what proportion of the task is complete.

taskdialog_progressbar.png

Events and Timing

ButtonClick

This event is raised as soon as the user clicks on any button of the dialog. The EventArgs class contains the ID of the button and a bool value that allows you to prevent the dialog from closing automatically after the click.

Construction and destruction events

Task dialogs raise two events: Constructed, which is sent first, and Created which is sent just before the dialog is shown.

After being destroyed, the Destroyed event is raised and means that the handle of the dialog isn't valid anymore.

Expanding

This event is raised just before the dialog is expanded or collapsed. The EventArgs class contains a bool value indicating whether the dialog is switching to the expanded state or not.

Help

Is raised when the user requests help (for instance with the F1 key).

Hyperlinks

In task dialogs you can add a hyperlink to the content, which will be displayed underlined and in blue color. When the user clicks one of these hyperlinks, the HyperlinkClick event is raised, containing the clicked URL. In order to enable this feature, you must set the EnableHyperlinks property to true:

dlg.EnableHyperlinks = true;
dlg.Content = "This is content. This is a <a href=\"link\">hyperlink</a>.";


taskdialog_hyperlink.png

In this case, a click on "hyperlink" will raise the HyperlinkClick event with the Url property set to "link".

Navigating

Is raised when the dialog navigates from one page to another. See Navigation section.

RadioButtonClick

Is similar to the ButtonClick, except that since the dialog will not automatically close after the click, the PreventClosing property of the EventArgs class has no effect.

Ticking

In order to allow you to update the dialog's contents in real-time (for instance progress bars), task dialogs provide a "ticking" interface which will call a delegate defined by you at 200ms intervals. In order to enable this callback, you must set the EnableCallbackTimer property to true.

The Tick event will be raised periodically with an EventArgs class containing the current count of "ticks" which have passed (in milliseconds) and an optional ResetCount property that, if set to true, will reset the count on the next call.

VerificationClick

Is raised when the user clicks on the verification checkbox. The EventArgs class tells whether the checkbox is now checked or not.

Calling methods on buttons

The task dialog interface provides several different ways to change the appearance and behavior of buttons. The following methods give you additional ways to change how your dialog looks and operates.

EnableButton

Takes the ID of the button you want to change and a bool that allows you to disable (or enable) the button.

EnableRadioButton

Takes the ID of the radio button and a bool that allows you to disable (or enable) the button.

SetShieldButton

Takes the ID of the button and a bool indicating whether to add or remove the UAC shield icon. This works for common buttons, custom buttons and command links, but not for radio buttons.

Click simulation

The methods SimulateButtonClick(), SimulateRadioButtonClick() and SimulateVerificationClick() allow you to inject virtual clicks on any button of the dialog at runtime. This can be used to change the state when reacting to events.

Navigation

One of the most complex aspects of Task dialogs, is that you can "navigate" from one to another. The Windows Vista Controls implementation simplifies everything to a single method call:

TaskDialog firstDialog; //instance has been created and is currently showing

TaskDialog secondDialog = new TaskDialog("New Task Dialog");

firstDialog.Navigate(secondDialog);


This will cause the first dialog to fade out, transform into the second dialog and then fade in again. You don't have to call Show() again on the second dialog and must not keep its reference: just keep the original task dialog reference (firstDialog in the sample above). All delegates registered on the dialog's events will be kept and be called correctly.

Fallback for previous Windows versions

The Windows Vista Controls library does not currently provide an automatic fallback for non-Vista versions of Windows, eventhough this may be implemented in future versions. You should always provide an alternative dialog to task dialogs and check if you can call the native version using the VistaControls.OSSupport class provided by the library.

Last edited Feb 28, 2008 at 9:34 PM by Lck, version 6

Comments

No comments yet.