.NET 1.1+

Windows Forms Message Boxes

by Richard Carr, published at http://www.blackwasp.co.uk/MessageBox.aspx

Message boxes provide a simple, standardised method to display information, warnings and errors to the user. They can also be used to ask simple questions and to request confirmation of actions.

Message Boxes

When developing an application using Windows Forms, you will often wish to display a message to the user, or ask a simple yes or no question. In most cases, creating a custom dialog box or window for this purpose would be an inefficient use of time, and may lead to a non-standard dialog box that confuses users. To simplify and standardise displaying this type of dialog box, Windows Forms includes the MessageBox class.

The MessageBox class is used to display modal dialog boxes containing a basic message, a title and one or more buttons. You can also include an icon to show the purpose of the message. When you display a dialog box, the calling form stops responding until the user clicks a button, at which point the message box disappears. You can then detect which button was pressed and act accordingly.

Displaying a Simple Message

The simplest type of message box is displayed using a call to the MessageBox class's Show method, passing the message to display as a string.

We can demonstrate this with a simple example. Create a new Windows Forms project and add a button to the automatically generated form. Double-click the button to create a Click event handler. Add code to button's event, as follows:

private void button1_Click(object sender, EventArgs e)
{
    MessageBox.Show("Hello, world!");
}

Run the program and click the button to see the results. When the message box appears, you should find that the original window no longer responds to input. Clicking the OK button closes the dialog box and returns control to the main window.

Adding a Title

As the above image shows, a message box does not include a caption on the title bar by default. You can add one with a second string argument in the call to Show, as in the following example:

private void button1_Click(object sender, EventArgs e)
{
    MessageBox.Show("Hello, world!", "Important Message");
}

Choosing a Button Set

If you only wish to display a message, the default OK button is generally sufficient. However, when you want to ask the user a question or confirm an action, you need to provide a different set of buttons. You can do this by using a third parameter, which accepts a value from the MessageBoxButtons enumeration. The enumeration contains one constant for each available button set. The options are:

• OK. The default option that displays the OK button alone.
• OKCancel. This option causes two buttons to be displayed. They show the text "OK" and "Cancel". This set is useful when you want the user to confirm an action that they have started but which may cause data loss.
• YesNo. The option shows "Yes" and "No" buttons. They are ideal for asking the user a simple question.
• YesNoCancel. This option adds a "Cancel" button alongside "Yes" and "No". This option is useful for asking the user how to proceed with an action whilst still giving the option to cancel. For example, when closing an application with an unsaved document you might ask the user if they want to save it. Clicking "Yes" would save the document and close. Clicking "No" would close the application without saving. Clicking "Cancel" would leave the application open.
• RetryCancel. This value indicates that the dialog box will display "Retry" and "Cancel" buttons. It is useful for simple processes that may fail. On failing, you can display the problem and the user can elect to try again or give up.
• AbortRetryCancel. A more complex version of RetryCancel, this option adds an "Abort" button. Again, this can be useful for obtaining a user's response to a problem.

To demonstrate, try running the following, updated code:

private void button1_Click(object sender, EventArgs e)
{
    MessageBox.Show("Save the document?", "Save?", MessageBoxButtons.YesNoCancel);
}

The dialog box now appears as shown below:

To determine which button the user clicked, you use the return value. This will be a value from the DialogResult enumeration, which has one constant for each available button.

private void button1_Click(object sender, EventArgs e)
{
    DialogResult result = MessageBox.Show(
        "Save the document?", "Save?", MessageBoxButtons.YesNoCancel);
    
    Text = result.ToString();
}

Run the above code and click a button. The title bar of the main window will update to show which button was clicked.