Chapter 3. Dialogs

A dialog is defined by its usage. If a form is the application's main window, it's a window, not a dialog. However, if a form pops up in response to a user request for service, such as a request to open a file, and stops all other user interactions with the application, it's a dialog (a modal dialog, specifically ).

However, things get a little murky when we consider modeless dialogs. They don't stop the user from interacting with the rest of the application, but they do provide a means of interaction outside the main window.

What makes things a bit murkier is the WinForms terminology. Standard dialogs are exposed by the XxxDialog family of components, such as the FileOpenDialog. Most of these components support only modal activation using ShowDialog, but a couple of them support modeless activation using Show. In contrast, custom dialogs are classes that derive from the Form base class and can be shown modally or modelessly based on whether they're activated using ShowDialog or Show.

No matter how a dialog is defined, this chapter covers things you'd normally think of as dialog- related issues, including standard dialogs, custom forms to be used as dialogs, modal and modeless activation and lifetime, transferring data in and out, validating user-entered data, and providing help. To aid you in making the transition to the unification of dialog-like functionality with forms, we don't use the term "dialog" except when referring to the standard dialog components.

Standard Dialogs

WinForms ships with several standard dialogs (sometimes known as "common dialogs") provided as components from the System.Windows.Forms namespace. A component is like a control in that you can drag it from the Toolbox onto a design surface and set its properties using the Property Browser. However, unlike a control, a component doesn't render in a region. Instead, it shows up on the tray along the bottom of the design surface so that you can choose it, and it isn't shown at run time at all. For the details of components, read Chapter 9: Design-Time Integration.

Because all the standard dialogs are components, they can be created in two ways: manually or by using the Designer. For example, creating and showing an instance of the ColorDialog component manually looks like this:

Sub colorDialogButton_Click(sender As Object, e As EventArgs) _
     Handles colorDialogButton.Click

Dim dlg As ColorDialog = New ColorDialog()

dlg.Color = Color.Red
  Dim res As DialogResult = dlg.ShowDialog()
  If res = DialogResult.OK Then
      MessageBox.Show("You picked " & dlg.Color.ToString())
  End If
End Sub

However, if you drag a ColorDialog component from the Toolbox, you can show it without explicitly writing the creation code, because the Designer will generate it for you in the InitializeComponent function:

Sub InitializeComponent()
  ...

Me.ColorDialog1 = New ColorDialog()

...
End Sub

Sub colorDialogButton_Click(sender As Object, e As EventArgs) _
     Handles colorDialogButton.Click

colorDialog1.Color = Color.Red


Dim res As DialogResult = colorDialog1.ShowDialog()

If res = DialogResult.OK Then
      MessageBox.Show("You picked " & colorDialog1.Color.ToString())
  End If
End Sub

We tend to prefer the latter approach because we like to set properties visually, but either one works just fine. The following standard dialogs come with WinForms:

• ColorDialog allows the user to pick a color exposed by the Color property of type System.Drawing.Color.

• FolderBrowserDialog allows the user to pick a folder exposed by the SelectedPath property of type string. This component is available only in .NET 1.1 and later.

• FontDialog allows the user to choose a font and its properties, such as bold, italics, and so on. The user-configured font object of type System.Drawing.Font is available from the Font property of the component.

• OpenFileDialog and SaveFileDialog allow the user to pick a file to open or save, as appropriate for the dialog. The chosen file name is available from the FileName property of type string.

• PageSetupDialog, PrintDialog, and PrintPreviewDialog are related to printing, which is discussed in Chapter 7: Printing.

All but one of the standard dialogs, including the FolderBrowserDialog that .NET 1.0 forgot , are wrappers around existing common dialogs in Windows. Because these dialogs don't support modeless operation, neither do the WinForms components. However, the PrintPreviewDialog component, which provides a new dialog just for WinForms and is not available from Windows, supports both modal and modeless operation using ShowDialog and Show, respectively.