Building a custom dialog is pretty easy. Simply add a new form to your project as described in Lesson 9 and give it whatever controls you need.

To allow the user to finish using the dialog, add one or more buttons. Some dialogs have a single OK button. Others have OK and Cancel buttons, or some other combination of buttons. Because you're creating the dialog, you can give it whatever buttons you like.

Figure 10.1. FIGURE 10-1

By convention, the buttons go at the bottom of the dialog in the right corner. Figure 10-1 shows a very simple dialog that contains a single textbox where the user can enter a name.

To make using the dialog easier, you can set the form's AcceptButton and CancelButton properties. These determine which button is triggered if the user presses [Enter] and [Esc], respectively. Typically the AcceptButton triggers the dialog's OK or Yes button, and the CancelButton triggers the Cancel or No button.

A program uses the ShowDialog method to display a dialog. This method returns a value that indicates which button the user clicked. As explained in Lesson 8, the program can check that return value to see what it should do with the dialog's results. The examples in Lesson 8 checked that ShowDialog returned the value DialogResult.OK before processing the user's selections.

A form's DialogResult property determines what value the call to ShowDialog returns. For example, you could use the following code to make the dialog's OK Button set the form's DialogResult property to DialogResult.OK to tell the calling program that the user clicked the OK button:

' Return OK to ShowDialog.
Private Sub btnOk_Click() Handles btnOk.Click
    Me.DialogResult = DialogResult.OK
End Sub

Setting the form's DialogResult property not only determines the return result, but also closes the dialog so the call to ShowDialog returns and the calling code can continue.

That means you can set the dialog's return result and close the dialog in a single line of code. Typing one line of code should be no real hardship, but believe it or not there's an even easier way to close the dialog.

If you set a Button's DialogResult property, the Button automatically sets the form's DialogResult property when it is clicked. For example, suppose you set the btnCancel's DialogResult property to DialogResult.Cancel. When the user clicks the Button, it automatically sets the form's DialogResult property to DialogResult.Cancel so the form automatically closes. That enables you to set the return value and close the form without typing any code at all.

If you think setting one Button property is still too much work, you can even avoid that, at least for the Cancel button. When you set a form's CancelButton property, Visual Basic automatically sets that Button's DialogResult property to DialogResult.Cancel.

Note that when you set the form's AcceptButton property, Visual Basic does not automatically set the Button's DialogResult property. The assumption is that the OK Button might need to validate the data on the form before it decides whether to close the dialog. For example, if the user doesn't fill in all required fields, the OK Button might display a message asking the user to fill in the remaining fields instead of closing the dialog.

If you don't want to perform any validation, you can simply set the OK Button's DialogResult property to DialogResult.OK yourself in the Properties window.

A program uses a custom dialog in exactly the same way that it uses a standard dialog. It creates, initializes, and displays the dialog. It checks the return result and takes whatever action is appropriate.

There's a slight difference in how the program creates the dialog because you can add standard dialogs to a form at run time, something you can't do with custom dialogs. To use a custom dialog, the code needs to create a new instance of the dialog's form as described in Lesson 9.

The following code shows how a program might display a new customer dialog:

' Display the new customer form.
Private Sub btnNew_Click() Handles btnNew.Click
    ' Create and display a NewCustomerForm dialog.
    Dim dlgNewCustomer As New NewCustomerForm()

    If (dlgNewCustomer.ShowDialog() = DialogResult.OK) Then
        ' ... Create the new customer here ...
    End If
End Sub

The code declares a variable to refer to the dialog and makes a new dialog. It displays the dialog by using its ShowDialog method and checks the return result. If the user clicks OK, the program takes whatever steps are needed to create the new customer, such as adding a record to a database.

In this Try It, you build and use a simple custom dialog. The dialog lets you enter a name. If you enter a nonblank value and click OK, the main form adds the name you entered to a ListBox.

This Try It also gives you a little practice using the ListBox control, showing how to add and remove items.

Lesson Requirements

In this lesson:

• Create the main form shown on the upper left in Figure 10-2. Make the New Comedian Button be the form's AcceptButton and the Delete Comedian Button be the form's CancelButton.

• Create the dialog shown on the lower right in Figure 10-2. Set the AcceptButton and CancelButton properties in the obvious way.

• Make the New Comedian Button display the dialog. If the dialog returns DialogResult.OK, add the new comedian's name to the ListBox.

• Make the Delete Comedian Button remove the currently selected comedian from the ListBox.

• When the user clicks the dialog's Cancel button, close the form and return DialogResult.Cancel.

• When the user clicks the dialog's OK Button, check the entered name's length. If the length is 0, display a message asking the user to enter a name. If the length is greater than 0, close the form and return DialogResult.OK.

Figure 10.2. FIGURE 10-2