Dialog boxes are special types of forms with very specific functionality, which we use to prompt the user for data. The Open and Save dialog boxes are two of the most familiar dialog boxes in Windows. They’re so common that they’re actually known as common dialog boxes. Technically, a dialog box is a good old form with its FormBorderStyle property set to FixedDialog. Like forms, dialog boxes might contain a few simple controls, such as Labels, TextBoxes, and Buttons. You can’t overload a dialog box with controls and functionality, because you’ll end up with a regular form.
There are a few dialog boxes you have certainly seen while working with Windows applications. The Insert Caption dialog box of Word is a modal dialog box: You must close it before switching to your document. The Find & Replace dialog box is modeless: It allows you to switch to your document, yet it remains visible while open even if it doesn’t have the focus.
Notice that some dialog boxes, such as Open, Color, and even the humble MessageBox, come with the Framework, and you can incorporate them in your applications without having to design them.
A characteristic of dialog boxes is that they provide an OK and a Cancel button. The OK button tells the application that you’re finished using the dialog box, and the application can process the information in it. The Cancel button tells the application that it should ignore the information in the dialog box and cancel the current operation. As you will see, dialog boxes allow you to quickly find out which buttons were clicked to close them, so that your application can take a different action in each case.
In short, the difference between forms and dialog boxes is artificial. If it were really important to distinguish between the two, they’d be implemented as two different objects— but they’re the same object. So, without any further introduction, let’s look at how to create and use dialog boxes.
To create a dialog box, start with a Windows form, set its FormBorderStyle property to Fixed-Dialog, and set the ControlBox, MinimizeBox, and MaximizeBox properties to False. Then add the necessary controls on the form and code the appropriate events, as you would do with a regular Windows form.
Figure 5.11 shows a simple dialog box that prompts the user for an ID and a password. The dialog box contains two TextBox controls, next to the appropriate labels, and the usual OK and Cancel buttons. The Cancel button signifies that the user wants to cancel the operation, which was initiated in the form that displayed the dialog box.
Start a new project, rename the form to MainForm, and place a button on the form. This is the application’s main form, and we’ll invoke the dialog box from within the button’s Click event handler. Then add a new form to the project, name it PasswordForm, and place on it the controls shown in Figure 5.11.

Figure 5.11 – A simple dialog box that prompts users for a username and password
To display a modal form, you call the ShowDialog method, instead of the Show method. You already know how to read the values entered on the controls of the dialog box. You also need to know which button was clicked to close the dialog box. To convey this information from the dialog box back to the calling application, the Form object provides the DialogResult property. This property can be set to one of the values shown in Table 5.3 to indicate which button was clicked. The DialogResult.OK value indicates that the user has clicked the OK button on the form. There’s no need to place an OK button on the form; just set the form’s DialogResult property to DialogResult.OK.
Table 5.3: The DialogResult Enumeration
Value | Description |
---|---|
Abort | The dialog box was closed with the Abort button. |
Cancel | The dialog box was closed with the Cancel button. |
Ignore | The dialog box was closed with the Ignore button. |
No | The dialog box was closed with the No button. |
None | The dialog box hasn’t been closed yet. Use this option to find out whether a modeless dialog box is still open. |
OK | The dialog box was closed with the OK button. |
Retry | The dialog box was closed with the Retry button. |
Yes | The dialog box was closed with the Yes button |
The dialog box need not contain any of the buttons mentioned here. It’s your responsibility to set the value of the DialogResult property from within your code to one of the settings shown in the table. This value can be retrieved by the calling application. The code behind the two buttons in the dialog box is quite short:
Private Sub bttnOK_Click(...) Handles bttnOK.Click
Me.DialogResult = DialogResult.OK
Me.Close
End Sub
Private Sub bttnCancel_Click(...) Handles bttnCancel.Click
Me.DialogResult = DialogResult.Cancel
Me.Close
End Sub
Code language: VB.NET (vbnet)
The event handler of the button that displays this dialog box should contain an If statement that examines the value returned by the ShowDialog method:
If PasswordForm.ShowDialog = DialogResult.OK Then
{ process the user selection }
End If
Code language: VB.NET (vbnet)
Depending on your application, you might allow the user to close the dialog box by clicking more than two buttons. Some of them must set the DialogResult property to DialogResult.OK, others to DialogResult.Cancel.
If the form contains an Accept and a Cancel button, you don’t have to enter a single line of code in the modal form. The user can enter values on the various controls and then close the dialog box by pressing the Enter or Cancel key. The dialog box will close and will return the DialogResult.OK or DialogResult.Cancel value. The Accept button sets the form’s DialogResult property to DialogResult.OK automatically, and the Cancel button sets the same property to DialogResult.Cancel. Any other button must set the DialogResult property explicitly. Listing 5.3 shows the code behind the Log In button on the sample project’s main form.
Listing 5.3: Prompting the User for an ID and a Password
Private Sub Button1_Click(...) Handles Button1.Click
If PasswordForm.ShowDialog() = DialogResult.OK Then
If PasswordForm.txtUserID.Text = "" Or _
PasswordForm.txtPassword.Text = "" Then
MsgBox("Please specify a user ID and a password to connect")
Exit Sub
End If
MsgBox("You were connected as " & _
passwordForm.txtUserID.Text)
Else
MsgBox("Connection failed for user " & _
password.txtPassword.Text)
End If
End Sub
Code language: VB.NET (vbnet)