.NET 4.0+

WPF Controls - Window - Showing Dialog Boxes

by Richard Carr, published at http://www.blackwasp.co.uk/WPFWindowShowDialog.aspx

The one hundred and seventy-first part of the Windows Presentation Foundation Fundamentals tutorial continues to describe the Window class. This article describes the process for displaying custom dialog boxes.

Custom Dialog Boxes

Windows and dialog boxes share much of the same functionality and appearance but are used for slightly different purposes. Typically, the user interacts with windows for a long period of time, whereas a dialog box is displayed to ask one or more questions before being closed. Dialog boxes often include OK and Cancel buttons, both of which close the window. The OK button usually indicates that the user wishes to accept any entered information and continue, whilst the Cancel button tells the software to ignore any input.

Another key difference between windows and dialog boxes their modality. Windows are non-modal. This means that they appear and can be interacted with, or the user can switch to another window within the application and work with that instead. The code that opens a modal window continues to run as normal. Dialog boxes are modal. The launching code waits until the dialog box is dismissed before continuing. The user cannot switch back to the previous window until the dialog box is closed.

In WPF, you design windows and dialog boxes in the same way. You can even use the same design for both purposes, potentially at the same time. The determination of whether a window is modal or non-modal is made according to the method used to launch it. To display as a window, you call the Show method, which we saw in the "WPF Controls - Window - Display and Activation" article. To show a modal dialog box, you use the ShowDialog method.

In this article we'll create a sample program that displays a dialog box and reacts to the information entered into it and the button used to close it. To begin, create a new WPF application in Visual Studio. Name the project, "CustomDialogDemo". Once it is prepared, replace the XAML in the main window with the following:

<Window x:Class="CustomDialogDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Dialog Demo" Height="150" Width="250">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition/>
            <RowDefinition/>
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition/>
            <ColumnDefinition/>
        </Grid.ColumnDefinitions>

        <TextBlock Margin="2">Button Clicked</TextBlock>
        <TextBlock Name="ButtonClicked" Grid.Column="1" Margin="2">n/a</TextBlock>
        <TextBlock Grid.Row="1" Margin="2">Text Entered</TextBlock>
        <TextBlock Name="TextEntered" Grid.Row="1" Grid.Column="1" Margin="2">n/a</TextBlock>
        <Button Grid.Row="2" Grid.Column="1" Margin="5">Open</Button>
    </Grid>
</Window>

We'll use the window to control the launching of a dialog box when the "Open" button is clicked. We'll update the TextBlocks on the right according to the information entered into the dialog box and the button used to dismiss it.

Next, add a second window to the project. Name the window, "CustomDialogBox". Replace the XAML of the new window with the code below:

<Window x:Class="CustomDialogDemo.CustomDialogBox"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Dialog Box" Height="100" Width="200">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition/>
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition/>
            <ColumnDefinition/>
        </Grid.ColumnDefinitions>
        
        <TextBox Name="MyTextBox" Grid.ColumnSpan="2"/>
        <Button Grid.Row="1" IsDefault="True" Margin="2">OK</Button>
        <Button Grid.Row="1" Grid.Column="1" IsCancel="True" Margin="2">Cancel</Button>
    </Grid>
</Window>

This XAML defines a simple dialog box where the user can enter some text and either accept it, by clicking "OK", or reject it, by clicking "Cancel". Note the IsDefault and IsCancel properties that have been set on the two buttons. These define the default button, which responds to the user pressing Enter, and the cancel button, which reacts to the Escape key. The IsDefault property also affects the style of the button.