### Creating a Message Box

A message box is a frame window that an application uses to display a note, caution, or warning to the user. For instance, an application can use a message box to inform a user of a problem that the application encountered while performing a task. The Open Class Library provides an IMessageBox class for displaying messages in a message box.

The help button does not appear on message boxes in Windows NT 3.51.

You construct objects of the IMessageBox class by using an object of a class derived from IWindow. The IWindow object becomes the owner of the new message box, as follows:

    IMessageBox  messageBox(owner);

The following example shows you how to create a message box:

    /***********************************************************/
    /* Create the information type message box                 */
    /***********************************************************/
    int about()
    {
      IMessageBox msg(IWindow::desktopWindow());
      msg.setTitle("Basic MsgBox");
      msg.show("Error MsgBox",
             IMessageBox::abortRetryIgnoreButton |
             IMessageBox::defButton1 |
             IMessageBox::errorIcon |
             IMessageBox::moveable);
      return true;
    }

The following shows a message box similar to the one created by the preceding example:

#### Creating a Message Window

The new class, IMessageWindow, supports message IDs on a message box. IMessageWindow is a customizable window for displaying simple to complex messages in your application. An IMessageWindow can be made to look similar to an IMessageBox using predefined settings, or can be customized by replacing or adding to components on the message window. The default message window contains an image in the upper left, message text in the center, a button area along the bottom, and message ID text in the lower right. Through various mechanisms, you can customize or replace any of these areas on the message window. In contrast, IMessageBox does not provide the message ID text area and is not customizable. The appearance of the message window is platform independent, so it may look slightly different than the native controls supported by IMessageBox.

You can use IMessageWindow without customization. There are five predefined message types in the EMessageType enumeration that you can pass on the IMessageWindow constructor that give the message window a certain image and certain buttons. Using one of these predefined types gives you a message window that looks similar to an IMessageBox. However, IMessageWindow only provides the most commonly used combinations for this simple use.

In addition, there are degrees of customization you can use with IMessageWindow. The simplest customization is to create the message window with the kUserDefinedMessage type, which indicates no image and no buttons, and add your own image and buttons using setMessageImage and addButton, respectively. With these functions you can specify a predefined image or button, or create your own, and add them to the message window. This allows you to customize without deriving from IMessageWindow. Any buttons you create and add to the message window should be created with the parent window returned by buttonParent. If a button is added without this parent, an exception is thrown. The buttons are added left to right in the order that you call addButton. You can call addButton even if you used a message type other than kUserDefinedMessage on the constructor, and any buttons you add are placed to the right of the existing buttons. There is no limit on the number of buttons you can add.

You can obtain a pointer to a predefined button you have added to the message window by calling the button function and passing one of the EButton enumerations. You can use the pointer returned to manipulate the appearance of the button, for example, by changing the text. One reason you may want to change the default buttons or add your own buttons to the message window is so you can provide translated text for them. The predefined button text is not translated into all languages on whose platforms you may want to run your application.

Set the styles of buttons you add or change to obtain the desired behavior for your message window. If you want a button to be the default, you must give it the IButton::defaultButton style. Likewise, if you want a help button, you must give it the IPushButton::help and IButton: :noPointerFocus styles.

For further customization, you can derive from IMessageWindow and override one or more functions to provide your own controls to be placed in the message window. The message window allows you to provide controls for the image, the message text, and the message ID by overriding createMessageImage, createMessageText, and createMessageIdText, respectively. You can provide any IBitmapControl or derived class for the image, and any ITextControl or derived class for the message text and message ID. The default image is an IIconControl, and the default message text and message ID are IStaticText controls. Any control you replace is positioned in the same place in the message window client area. However, you define the characteristics of the control such as minimum size, image, text, scrollability, or color.

Note that you can still add or replace buttons if you derive from IMessageWindow by using IMessageWindow::addButton.

The most comprehensive way to customize IMessageWindow is to derive your own class and replace the entire client area by overriding createClient. You must use the deferClientCreation style for your override of createClient to be called. The function is called when the message window is shown. Whatever you return from this function is placed in the client area with no changes. You can obtain the default image, message text, and message ID controls to place in your client area by calling createMessageImage, createMessageText, or createMessageIdText. The characteristics of the controls returned from these functions aredependent on the message type indicated in the constructor and previous calls to setMessageText, setMessageImage, and setMessageId. To determine which buttons to place in your client area or other characteristics you may want to add, you can call messageType to obtain the message type specified on the constructor.

Since IMessageWindow derives from IFrameWindow, you can use inherited functions and styles to manage the message window. Use IFrameWindow::show or IFrameWindow::showModally to display your message window. Use IFrameWindow::systemModal to make your message window system modal. There are many other frame window functions and styles you may want to apply to your message window.

You must use an ICommandHandler to handle processing for any buttons you add to your message win dow that are not listed in the EButton enumeration. By default, the message window will dismiss its elf when any predefined button (except help) is clicked. The IDs for the predefined buttons provided by IMessageWindow are listed in the EButton enumeration. For buttons you create and add, you determine the action to be taken in your handler. If you display the message window using showModally, the ID of the button clicked is returned from the call to that function.

Provide help for your message window just as you would any other frame window.

Windows

Creating a Frame Window
Creating an Information Area

ICommandHandler
IFrameWindow
IMessageBox
IMessageWindow
IWindow