Material Design in XAML – How to make sense of the Dialog Host

,

 

Material Design In XAML (MDIX) is a beautiful theme library that brings Google’s Material Design to your Windows Presentation Framework (WPF) applications. In this tutorial, we look at how easy it is to get started with one of its most powerful controls, the DialogHost. It provides a simple way to display a dialog with information or prompt the user when information is required.

 

This post assumes that you have already setup a project with MDIX and understand the Model-View-ViewModel (MVVM) pattern (though the DialogHost can be used without MVVM as well).

The anatomy of a DialogHost

We will start with a very simple example.

 

Running application then looks like this:

Figure 1: Simple dialog host application.

 

The DialogHost consists of three individual UI components: the host control, the overlay and the dialog. The host control contains the content that the dialog should be placed on top of. Typically, this will be placed near the root of your XAML so that it covers everything. The overlay is the darkened region that covers all of the content within the host control. Finally the dialog itself contains the content to display. By default, the dialog is shown inside of a popup. Because a popup is a separate window, the dialog can be larger than its parent window. If you want the dialog to be constrained to its parent window, you can apply the alternate MaterialDesignEmbeddedDialogHost style to the DialogHost (this style is new in version 2.5.0 which is currently in beta).

Figure 2: The layers of a DialogHost. 1. The host control wrapping the rest of the content. 2. The overlay. 3. The dialog content.
Figure 2: The layers of a DialogHost. 1. The host control wrapping the rest of the content. 2. The overlay. 3. The dialog content.

Showing and closing a dialog

The DialogHost works well with applications using both MVVM and code behind architecture. Because of this, there are several ways to show a dialog. You may elect to use any number of these options in your app.

 

Routed Commands

The DialogHost provides two RoutedCommands for showing and hiding dialogs; OpenDialogCommand and CloseDialogCommand respectively. This is the simplest pure XAML option as it simply walks up the element tree until it encounters a DialogHost control. Simply set this as the Command property and it will show the dialog.

Also, if you want to close a dialog, you can use the CloseDialogCommand.

 

IsOpen Property

For simple programmatic control over the state of the dialog, the DialogHost provides an IsOpen property. Toggling the state of this property will cause the dialog to be shown or hidden. This property can also be used with data binding making it easy to use in MVVM architecture.

Or, use code behind:

 

CloseOnClickAway Property

To make the dialog close automatically if the user clicks on the overlay, simply set the CloseOnClickAway property to “True”.

Static DialogHost.Show Method

For even more control over dialogs, there are several static Show methods on the DialogHost class. All of these methods return Tasks and are designed to be used as async methods. In the previous examples, the dialog’s content was specified in XAML and then simply shown or hidden. When using the Show method, you must pass the content for the dialog. This allows for creating dynamic dialogs.

Figure 3: A dynamic dialog
Figure 3: A dynamic dialog

 

This approach certainly works but requires creating the dialog UI in code. A better approach is to declare the dialog’s UI as a DataTemplate and pass a data object as the dialog’s content.

 

Figure 4: A dialog created from a DataTemplate
Figure 4: A dialog created from a DataTemplate

 

The Show method also includes overloads with callback delegates that are invoked when the dialog is opened or closed. You can also register for the DialogOpened and DialogClosed events directly on the DialogHost. The event arguments for these callbacks, contain a DialogSession object. This session object can be used to update the content of a dialog that has already been shown or to close a visible dialog.

 

Finally there are additional overloads for passing a dialog identifier. If there is only a single DialogHost instance, the Show method will automatically use it. However, in cases where there is more than one DialogHost instance, you must specify a dialog identifier. This unique id identifies which DialogHost control should be used.

 

Returning values

Dialogs shown with the static Show method can also return result values. These result values can be object that you want.

 

Depending on how the dialog is being closed, there are a number of ways to specify the return value.

  • If using the DialogCloseCommand, set the CommandParameter on the same element that is using the command.
  • If using the CloseOnClickAway, set the CloseOnClickAwayParameter on the DialogHost
  • If using the DialogSession, simply pass a parameter to the Close method.
  • The IsOpen property does not support passing a result. You must use one of the other methods.

 

Despite being one of the most powerful control in the MDIX library, the DialogHost is also one of the most misunderstood. However, with a little effort it can make working with “modal” dialogs in your application a breeze. It can improve both the aesthetics of the user interface, and simplify the user experience.

 

Additional Resources.

 

At time of writing, the current release of Material Design in XAML is version 2.4.1

Share this story