MessageBox Dialog

MessageBox Dialog

A MessageBox displays information to the user and the user can respond in multiple ways. The last chapter used a MessageBox that displayed a message and then went away when the user clicked the OK button. This section describes other options that can be used to make a MessageBox more expressive. The only method that belongs to the MessageBox class itself is the static Show method. The Show method has twelve overloads but is really not that complex. This section explains the parameters used in the overloads and contains examples of how to use most of them.

The IWin32Window Interface

Six of the twelve overloads of the MessageBox method begin with the IWin32Window parameter. This parameter is intended to designate the window that the MessageBox will appear in front of.

MessageBoxButtons

Another set of overloads to the Show method accepts arguments of type MessageBoxButtons. This enables the MessageBox to give the user more decision-making power. After showing the MessageBox, code can capture the return value, which is of type DialogResult, to check the user's selection. Listing 7.2 shows how to implement MessageBoxButtons in the MessageBox.Show method.

Listing 7.2 The MessageBoxButtons Parameter (MessageBoxButtons.cs)

 protected override void OnClosing(CancelEventArgs e) {    DialogResult dlgRes = MessageBox.Show("Are you sure?",    "Closing", MessageBoxButtons.OKCancel);    if (dlgRes == DialogResult.Cancel)    {       e.Cancel = true;    } } private void btnExit_Click(object sender, System.EventArgs e) {    Close(); } 

Either clicking btnExit or clicking the Close button on the form causes the form's Closing event to fire. The code in Listing 7.2 overrides the base class (Form) OnClosing method and presents the MessageBox with its MessageBoxButtons parameter set to OKCancel. By capturing the DialogResult returned with the user's selection, this routine can either close the application or allow it to continue. Setting the Cancel property of the CancelEventArgs object passed to OnClosing tells the system not to close the application.

This could have been done by entering a method in the Closing event in the Object Inspector also. The only significant difference is that an event handler is accessible by outside objects, whereas the protected overridden OnClosing method can only be accessed inside the same class or by derived classes.

Table 7.1 lists each of the MessageBoxButtons enum members and what they are used for.

Table 7.1. MessageBoxButtons Options

MessageBoxButtons ENUM	PURPOSE
AbortRetryIgnore	Commonly used for error conditions. Allows user to abort entire operation, retry the process, or ignore the error and move on.
OK	Simple acknowledgement to a message.
OKCancel	A choice of either accepting an option or canceling the operation in progress.
RetryCancel	A process was not able to complete. Give the user the choice to try again or just stop.
YesNo	The user must decide whether to perform an action or not.
YesNoCancel	Lets the user choose whether to perform a specific action or just cancel the whole operation.

MessageBoxIcon

All the MessageBoxes shown so far have been blank with only a message to display. Using an icon with the MessageBox helps communicate more information about the message. For example, an Error icon communicates something much different than an Information icon. Listing 7.3 shows how to add an icon to a MessageBox.

Listing 7.3 The MessageBoxIcon Parameter (MessageBoxIcon.cs)

 protected override void OnClosing(CancelEventArgs e) {    DialogResult dlgRes = MessageBox.Show(       "Do you want to save changes?",       "C#Builder Kick Start",       MessageBoxButtons.YesNoCancel,       MessageBoxIcon.Warning);    switch (dlgRes)    {       case DialogResult.Yes:          // perform save opertation          break;       case DialogResult.No:          // no need to do anything          break;       case DialogResult.Cancel:          e.Cancel = true;          break;       default:          throw new InvalidOperationException(             "Invalid result from MessageBox!");   } } private void btnExit_Click(object sender, System.EventArgs e) {    Close(); } 

The MessageBox.Show method in Listing 7.3 uses the Warning member of the MessageBoxIcon parameter. This is a yellow triangle with an exclamation point. Table 7.2 lists the members of the MessageBoxIcon enum.

Listing 7.3 takes the user's choice and makes a decision in a switch statement, which makes more sense because it covers all options. Although the MessageBox should never return an option that isn't part of its MessageBoxButtons, the default case is a safeguard: What if the MessageBox class was changed to have a different MessageBoxButtons argument?

Table 7.2. MessageBoxIcon Options

MessageBoxIcon MEMBER	DESCRIPTION
Asterisk and Information	A circled letter "i". Used for information messages.
Error, Hand, and Stop	An "X" in a red circle. Indicates an error condition.
Exclamation and Warning	An "!" in a yellow triangle. Represents caution or warning.
None	No icon appears.
Question	A circled "?". Queries the user for a response.

MessageBoxDefaultButton

When the only button on a MessageBox is the OK button, it is clearly the default. However, when you're setting the MessageBoxButtons parameter, sometimes the first or OK button should not be the default. The MessageBoxDefaultButton parameter explicitly states which of three possible buttons is the default. Listing 7.4 shows how to use the MessageBoxDefaultButton parameter. Allowable values are Button1, Button2, or Button3.

Listing 7.4 The MessageBoxDefaultButton Parameter (MessageBoxDefaultButton.cs)

 private void btnService_Click(object sender, System.EventArgs e) {   MessageBox.Show(     "Web Service Timeout!",     "C#Builder Kick Start",     MessageBoxButtons.AbortRetryIgnore,     MessageBoxIcon.Error,     MessageBoxDefaultButton.Button2); } 

The MessageBox.Show method in Listing 7.4 uses the Button2 member of the MessageBoxDefaultButton parameter, which makes the Retry button on the MessageBox appear as the default.

If the MessageBoxDefaultButton parameter identifies a nonexistent button, the normal default button will be selected as if the MessageBoxDefaultButton parameter were not used. For example, when MessageBoxDefaultButton.Button3 is used on a MessageBox that uses the MessageBoxButtons.OKCancel, the OK button will be the default and there will be no error.

MessageBoxOptions

The MessageBoxOptions parameter is sort of a catchall for any options that don't fit into any of the other categories. For example, the DefaultDesktopOnly and ServiceNotification are for applications like Windows Services that run in the background, but need to notify the user of some condition. The RtlReading supports displaying text differently for localization. There is also a RightAlign member for aligning the text to the right of the MessageBox. Listing 7.5 shows how to use the MessageBoxOptions parameter.

Listing 7.5 The MessageBoxOptions Parameter (MessageBoxOptions.cs)

 private void btnRightAlign_Click(object sender, System.EventArgs e) {   MessageBox.Show(     "Text\nAligned\nTo\nThe\nRight.",     "C#Builder Kick Start",     MessageBoxButtons.RetryCancel,     MessageBoxIcon.Information,     MessageBoxDefaultButton.Button2,     MessageBoxOptions.RightAlign); } 

Listing 7.5 shows the RightAlign option, where text is aligned to the right side of the message box, as opposed to the default left alignment.