Help-Tutorial-Direct-MessageBoxes

Getting the Message Across

The first feature of the Two-Layered GUI Toolkit that we are going to use are message boxes. Message boxes are simple windows that show a textual messages and that contain one or more buttons to close the window.

Most GUI toolkits such as Gtk# already provide an API for displaying some sort of message boxes, so you might wonder why you would want to use those provided by the Two-Layered GUI Toolkit rather than the default ones. The answer is that the message boxes in the Two-Layered GUI Toolkit support a variety of useful features beside showing a simple message, such as:

• any number of buttons
• arbitrary buttons
• custom ordering of buttons
• localizable default button captions
• optional do not show this message again checkboxes
• optional headline texts that can contain a short abstract of what the message is about
• foldable panels for details displays

The Gtk# implementation of these message boxes is accessible through the TwoLayeredGUI.Gtk.MessageBox class. To show a message box, invoke its static Show method. For a start, we pick a very simple overload:

MessageBox.Show("Hello World!");

This will display a small window that contains the indicated string, as well as an icon and a Close button.

Looking at the API reference, we can see that the overload isn't that simple after all: It contains a second parameter that can be used to specify which buttons to show in the dialog box. (As that parameter is declared with the params keyword, it is treated as a variadic parameter and hence was simply omitted in our first invocation.)

The values for that second parameter must be something called TwoLayeredGUI.ButtonDef. This is a button definition, an object that stores the settings of a button. For now, we will use the pre-defined buttons that can be obtained from static properties of the ButtonDef class with the Button suffix. The following message box will contain two buttons, ButtonDef.RetryButton and ButtonDef.IgnoreButton:

MessageBox.Show("The world does not respond.",
                ButtonDef.RetryButton, ButtonDef.IgnoreButton);

Like this, you can specify any combination and order of buttons for the dialog box that you desire. Note that some common combinations are returned by static properties of the ButtonDef class that have the Buttons suffix, such as ButtonDef.AbortRetryIgnoreButtons.

Now that there are two buttons, we want to know which one was pressed to close the message box. This information is provided in the return value of the Show method. The return value is always a ButtonDef instance (and never null).

If the message box was closed by a button, the respective ButtonDef instance will be returned. If the message box was closed with the window manager - e.g. on systems, where this exists, by clicking an X button in the window title bar - ButtonDef.CancelButton will be returned. This ensures that you can always safely access members of the return value of Show without checking for null.

The resulting ButtonDef object can either be checked for instance identity with the ButtonDef instances that were passed to Show in the button list, or its Kind property can be compared to one of the values from the DefaultButtonKind enumeration. The second approach is more similar to message box APIs provided in various GUI toolkits, but it is not applicable when using custom buttons.

The following code snippet uses the first approach (this works because the static ButtonDef properties such as ButtonDef.RetryButton always return the same instance):

if (MessageBox.Show("The world does not respond.",
                    ButtonDef.RetryButton, ButtonDef.IgnoreButton)
        == ButtonDef.RetryButton) {
    MessageBox.Show("Still not getting anything.");
}

And this code snippet uses the second approach:

if (MessageBox.Show("The world does not respond.",
                    ButtonDef.RetryButton, ButtonDef.IgnoreButton).Kind
        == DefaultButtonKind.Retry) {
    MessageBox.Show("Still not getting anything.");
}

More options are available for message boxes, some by using alternative Show overloads with more parameters, and even more by using the settings object for message boxes.

More options than those presented above are available if you use an instance of the MessageBoxSettings class. For example, it allows you to display an additional foldable area that shows some more detailed information:

MessageBoxSettings settings = new MessageBoxSettings("This message is short.",
                                                     ButtonDef.ShowDetailsButton,
                                                     ButtonDef.CloseButton);
settings.Details = "This detailed information is considerably longer than the message text.\nIt can even cover multiple lines.";
MessageBox.Show(settings);

Note how ButtonDef.ShowDetailsButton is listed as one of the buttons for the message box. Without it, there would be no way to unfold the details area.

There are also some shortcuts available for easily displaying certain message boxes with frequent settings:

string pattern = "This pattern contains {0} characters.";
MessageBox.ShowInformation(pattern, pattern.Length);

This ShowInformation method accepts a format pattern and a variable number of string format arguments. Analogous ShowWarning and ShowError methods exist as well. Moreover, it is possible to directly display an exception:

int[] array = new int[20];
try {
    int x = array[50];
}
catch (IndexOutOfRangeException ex) {
    MessageBox.ShowError(ex);
}

The exception message will be used as the message box text and the stack trace will be shown in the details area with this overload, though other overloads allow for setting a custom message text.

Back / Continue