Extending Modal Dialog Boxes

To guarantee functional and visual compatibility with Visual Studio, create modal dialog boxes for Visual Studio extensions by deriving dialog box windows from the Microsoft.VisualStudio.PlatformUI.DialogWindow object. Dialog boxes derived in this manner can also provide additional functionality; for example, you can set F1 Help targets and enable minimize and maximize on the window.

Creating Modal Dialog Boxes

1. In your project, add a reference to System.XAML.

2. In Solution Explorer, right-click the project, click Add, and then click Window.

3. Name the window, and then click Add.

   An empty XAML window appears in the designer.

4. In the top-level Window element, add a namespace declaration for Microsoft.VisualStudio.PlatformUI, and change the Window element to a Microsoft.VisualStudio.PlatformUI.DialogWindow element, as shown in the following example.

   <ui:DialogWindow x:Class="Microsoft.VSModalDialog.MyModalDialog"
       xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:ui="clr-namespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.11.0"
       Title="MyModalDialog" Height="100" Width="320">
   

5. Add buttons, labels, and other controls from the Toolbox, type the text labels, and adjust the appearance of the dialog box.

6. Switch to code view.

7. In the class definition, set the class to inherit from DialogWindow. (By default, the class inherits from System.Windows.Window.)

8. Add event handlers for buttons and other controls.

To add F1 Help to a modal dialog box

1. To the constructor, add a parameter that takes a string as its argument and set the constructor to inherit from the base constructor by using the same parameter, as shown in the following example.

   // Use this constructor to provide a Help button and F1 support.
   public MyModalDialog(string helpTopic) : base(helpTopic)
   {
       InitializeComponent();
   }
   

   This constructor sets the HasHelpButton property to true and enables the received string to be used as a keyword when a user presses F1 or clicks the Help button.

To add Minimize and Maximize buttons to a modal dialog box

1. In the constructor function, set the P:Microsoft.VisualStudio.PlatformUI.DialogWindow.hasMinimizeButton and P:Microsoft.VisualStudio.PlatformUI.DialogWindow.hasHMaximizeButton properties to true, as shown in the following example.

   // Use this constructor for minimize and maximize buttons and no F1 Help.
   public MyModalDialog()
   {
       this.HasMaximizeButton = true;
       this.HasMinimizeButton = true;
       InitializeComponent();
   }
   

   Warning

   When Minimize and Maximize buttons are shown, the Help button is hidden, even if the HasHelpButton property is set to true.

Example

The following example shows a modal dialog box that has two constructors. The first constructor takes an F1 keyword as an argument and displays a Help button. The second constructor takes no arguments, but displays Minimize and Maximize buttons. When you click the Yes button, a second instance of the dialog box is invoked and has Help enabled.

<ui:DialogWindow x:Class="Microsoft.VSModalDialog.MyModalDialog"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:ui="clr-namespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.11.0"
    Title="MyModalDialog" Height="100" Width="320">
    <Grid Height="60" Width="300">
        <Label Content="Would you like to view this dialog with Help enabled?" Height="25" Name="label1" VerticalAlignment="Top" />
        <Button Content="Yes" Name="btnYes" Click="btnYes_Click" Height="25" Width="75" HorizontalAlignment="Left" Margin="0,30,0,0" />
        <Button Content="No" Name="btnNo" Click="btnNo_Click" Height="25" Width="75" HorizontalAlignment="Left" Margin="80,30,0,0" />
    </Grid>
</ui:DialogWindow>

using System.Windows;
using Microsoft.VisualStudio.PlatformUI;

namespace Microsoft.VSModalDialog
{
    // Use this constructor to enable F1 Help.
    public partial class MyModalDialog : DialogWindow
    {
        // Use this constructor to provide a Help button and F1 support.
        public MyModalDialog(string helpTopic) : base(helpTopic)
        {
            InitializeComponent();
        }

        // Use this constructor for minimize and maximize buttons and no F1 Help.
        public MyModalDialog()
        {
            this.HasMaximizeButton = true;
            this.HasMinimizeButton = true;
            InitializeComponent();
        }

        private void btnYes_Click(object sender, RoutedEventArgs e)
        {
            var v = new MyModalDialog("Microsoft.VisualStudio.PlatformUI.DialogWindow");
            v.Content = "Here you go.";
            v.ShowModal();
            this.Close();
        }

        private void btnNo_Click(object sender, RoutedEventArgs e)
        {
            System.Windows.Forms.MessageBox.Show("Okay.");
            this.Close();
        }
    }
}

The following code invokes the dialog box from an event handler.

private void MenuItemCallback(object sender, EventArgs e)
{
    // Create the dialog instance without Help support.
    var d = new MyModalDialog();
    // Show the dialog.
    var m = d.ShowModal();
}

See Also

Creating and Managing Modal Dialog Boxes