The MessageBox class is used to provide simple interaction with the user by displaying a message box, which is a specialized type of dialog box containing a message, optional icons, and one or more buttons. Message boxes are often used to present information that can be formatted in a simple text message.
Unlike with other forms that you’ll use in your application, you never create an instance of the MessageBox class. Instead, you call the static Show method to display the message box, like this:
MessageBox.Show("A simple message box");
This version of Show displays the most basic message box, containing the string passed as a parameter and an OK button, as shown in Figure 11-5. There are 12 overloaded versions of the Show method, which provide a great deal of flexibility in specifying message box behavior, including the buttons and icons that are displayed. The following sections describe the options available through these overloaded versions.
To include a caption or title for the message box, pass a second string to MessageBox.Show, as shown here:
MessageBox.Show("A simple message box", "MessageBox demo");
Message boxes can be populated with buttons other than the OK button, enabling you to collect a response from the user in response to a question posed in the message box. Although up to three buttons can be displayed in a message box, you don’t have free rein in defining these buttons. Instead, you must select from the predefined button groups found in the MessageBoxButtons enumeration, listed in Table 11-1.
The following code demonstrates how you can specify an alternative button layout for a message box by passing a value from the MessageBoxButtons enumeration as a parameter:
DialogResult result = MessageBox.Show("A message box with 3 buttons", "MessageBox demo", MessageBoxButtons.YesNoCancel); switch(result) { }
As you can see, the return value from the Show method is one of the DialogResult return values shown in Table 11-1.
The MessageBoxIcon enumeration is used to specify which of four icons is displayed in the message box. Although there are only four possible icons, there are nine members in the MessageBoxIcon enumeration, as described in Table 11-2.
Member |
Description |
Asterisk |
Displays a circle containing a lowercase i. |
Error |
Displays a red circle containing a white X. |
Exclamation |
Displays a yellow triangle containing an exclamation point. |
Hand |
Displays a red circle containing a white X. |
Information |
Displays a circle containing a lowercase i. |
None |
No icon is displayed. |
Question |
Displays a circle containing a question mark. |
Stop |
Displays a red circle containing a white X. |
Warning |
Displays a yellow triangle containing an exclamation point. |
To specify the icon displayed in a message box, pass one of the values from the MessageBoxIcon enumeration to the Show method, in addition to specifying the button layout and other parameters, as shown here:
DialogResult result = MessageBox.Show("A message box with an icon", "MessageBox demo", MessageBoxButtons.YesNoCancel, MessageBoxIcon.Asterisk); switch(result) { }
The MessageBoxDefaultButton enumeration enables you to specify the button in a dialog box that will be the default button, and thus will be returned to the user as a DialogResult return value if the user presses Enter. The enumeration has three values: Button1, Button2, and Button3. The following code demonstrates using the MessageBoxDefaultButton enumeration to specify a default button:
DialogResult res = MessageBox.Show("The default button is Ignore", "MessageBox demo", MessageBoxButtons.AbortRetryIgnore, MessageBoxIcon.Asterisk, MessageBoxDefaultButton.Button3); switch(res) { }
This code displays a message box that contains three buttons: Abort, Retry, and Ignore, with the Ignore button specified as the default button.
The MessageBoxOptions enumeration is used to control how a message box is displayed to the user, as well as to define some special-case behavior. The members of the MessageBoxOptions enumeration are described in Table 11-3.
The values in Table 11-3 can be combined using the bitwise OR operator (¦). The following code demonstrates combining values from the MessageBoxOptions enumeration:
DialogResult res = MessageBox.Show("The service has not\nstarted\n.", "Service demo", MessageBoxButtons.AbortRetryIgnore, MessageBoxIcon.Exclamation, MessageBoxDefaultButton.Button3, MessageBoxOptions.RightAlign ¦ MessageBoxOptions.DefaultDesktopOnly); switch(res) { }
This code creates a message box suitable for use by a Windows service, with right-aligned text.
To ensure that a message box is displayed in front of a specific form, you can specify a reference to the form when calling the MessageBox.Show method. Each of the overloaded versions of the Show method discussed earlier in this chapter has a similar overload that allows you to specify the message box parent. In most cases, you can simply pass a pointer to the parent form as the first parameter, as shown here:
MessageBox.Show(this, "Just a message", "MessageBox demo");
The first parameter can be a reference to any object that implements the IWin32Window interface. This interface is implemented by all controls and forms in the .NET Framework and is a standard interface for types that encapsulate Win32 window handles.