Title: Make a dialog with standard dialog features in C#

Making a dialog is easy. Just add a new form to the project. Making a dialog that provides standard features (so it acts more or less like a standard dialog) only takes a little more work.

To do it right, you need to know a little about dialogs:

• A form's AcceptButton property determines the button that fires when the user presses Enter.
• A form's CancelButton property determines the button that fires when the user presses Escape.
• A form's DialogResult property determines the value that is returned when you call the dialog's ShowDialog method. This can have values such as OK, Cancel, Retry, and so on.
• If you set the form's DialogResult property at run time, the form automatically hides and returns the appropriate value to ShowDialog.
• If you set a button's DialogResult property to a value, then when the user clicks the button, the button sets the form's DialogResult value (which in turn hides the form).
• If you make a button the CancelButton, Visual Studio sets that button's DialogResult property to Cancel.
• If you make a button the AcceptButton, Visual Studio does not automatically set that button's DialogResult property to OK. The presumption is that you will want to validate the form before hiding it. If you don't need to validate anything and just want to return OK, you can set the button's DialogResult property yourself.

To build a form with standard features:

1. Add a new form to the project. Give it OK and Cancel buttons.
2. Set the form's AcceptButton property to the OK button. Set its CancelButton property to the Cancel button.
3. If you don't need to validate the user's selections, set the OK button's DialogResult property to OK and you're done!
4. If you do need to validate the user's selections, give the OK button a Click event handler that validates the user's selections. If everything is okay, make the code set the form's DialogResult property to OK. If there's something wrong with the selections, complain to the user and exit the event handler.
5. If you want to allow easy access to the dialog's controls from the main program (for example, to let the main program get and set values in TextBoxes), set the Modifiers property for those controls to Public. (Purists would argue that you should give the dialog properties that get and set the control properties, but that's a lot of extra work for not much benefit.)

This example program displays a dialog where the user can enter a first and last name. The dialog executes the following code when the user clicks the OK button.

// Validate the user's entries. private void btnOk_Click(object sender, EventArgs e) { if (txtFirstName.Text.Length < 1) { MessageBox.Show("You must enter a First Name.", "Invalid Name", MessageBoxButtons.OK, MessageBoxIcon.Error); txtFirstName.Focus(); } else if (txtLastName.Text.Length < 1) { MessageBox.Show("You must enter a Last Name.", "Invalid Name", MessageBoxButtons.OK, MessageBoxIcon.Error); txtLastName.Focus(); } else { // It's ok. Close the dialog. DialogResult = DialogResult.OK; } }

This code simply verifies that the user didn't leave each the first or last name blank. If either name is blank, the code displays an error message and sets focus to the blank text box. If both names are filled in, the code sets the dialog's DialogResult property to hide the form.

This dialog uses the following code to hide the dialog's default Show method so the main program cannot use it. (It must use ShowDialog instead.)

// Replace Show so the program cannot use it. private new void Show() { throw new InvalidOperationException( "Use ShowDialog not Show to display this dialog"); }

That's all there is to the dialog. The following code shows how the main program uses it.

// Display the dialog. private void btnSetName_Click(object sender, EventArgs e) { // Create and initialize the dialog. NameDialog dlg = new NameDialog(); dlg.txtFirstName.Text = txtFirstName.Text; dlg.txtLastName.Text = txtLastName.Text; // Display the dialog and check the result. if (dlg.ShowDialog() == DialogResult.OK) { // The user clicked OK. Save the values. txtFirstName.Text = dlg.txtFirstName.Text; txtLastName.Text = dlg.txtLastName.Text; } }

This code follows the normal pattern for using a standard dialog: initialize the dialog's value(s), use ShowDialog to display the dialog and check its return result, if the user clicked OK use the dialog's result. (See the example Use standard dialogs in C# for more information about that pattern.)

Download the example to experiment with it and to see additional details.