IMessageBox

The IMessageBox class displays message boxes that are compliant with the Windows Interface Guidelines for Software Design style guide on Windows, the Common User Access (CUA) style guide on OS/2, and the Motif style guide on AIX.

IMessageBox - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class. You cannot copy or assign IMessageBox objects because both the copy constructor and assignment operator are private functions.

~IMessageBox

public:
virtual ~IMessageBox()

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

IMessageBox

public:
IMessageBox(IWindow* owner)

You can only construct objects of this class by specifying an object of the class IWindow.

owner: The IWindow object that becomes the owner of the new message box. The message box title defaults to the owner's title. You can specify that the message box has no owner window by using a value of 0.
To display help for a message box, ensure that owner is nonzero, and that the owner specified is associated with an IHelpWindow object.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Showing the Message Box

A message window is not displayed when you construct an IMessageBox object. When you show the message window, you can specify its message text, push buttons, icon, and other specifics.

show

Shows a message box. The returned value is an enumerator provided by Response.

Overload 1

public:
virtual IMessageBox::Response
  show( const IResourceId& message,
        const Style& style,
        unsigned long helpId = 0 )

message: Identifier for a string or message resource to be used for the message box text.
style: The style of the message box, as a combination of objects of the class IMessageBox::Style.
helpPanelId: If helpPanelId is nonzero, a Help push button is displayed. When the Help push button is selected, the help panel with the ID corresponding to the helpPanelId parameter is displayed. Optional.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Overload 2

public:
virtual IMessageBox::Response
  show( const char* message,
        Severity severity,
        unsigned long helpId = 0 )

message: The message box text.
severity: Use the enumeration Severity to specify the severity of your message.
helpPanelId: If helpPanelId is nonzero, a Help push button is displayed. When the Help push button is selected, the help panel with the ID corresponding to the helpPanelId parameter is displayed. Optional.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Overload 3

public:
virtual IMessageBox::Response
  show( const char* message,
        const Style& style,
        unsigned long helpId = 0 )

message: The message box text.
style: The style of the message box, as a combination of objects of the class IMessageBox::Style.
helpPanelId: If helpPanelId is nonzero, a Help push button is displayed. When the Help push button is selected, the help panel with the ID corresponding to the helpPanelId parameter is displayed. Optional.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Overload 4

public:
virtual IMessageBox::Response
  show( const IBaseErrorInfo& error,
        unsigned long helpId = 0 )

error: An IBaseErrorInfo object. The message box displays the text contained in this object.
helpPanelId: If helpPanelId is nonzero, a Help push button is displayed. When the Help push button is selected, the help panel with the ID corresponding to the helpPanelId parameter is displayed. Optional.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Overload 5

public:
virtual IMessageBox::Response
  show( const IResourceId& message,
        Severity severity,
        unsigned long helpId = 0 )

message: Identifier for a string or message resource to be used for the message box text.
severity: Use the enumeration Severity to specify the severity of your message.
helpPanelId: If helpPanelId is nonzero, a Help push button is displayed. When the Help push button is selected, the help panel with the ID corresponding to the helpPanelId parameter is displayed. Optional.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Overload 6

public:
virtual IMessageBox::Response
  show( const IException& exception,
        unsigned long helpId = 0 )

exception: An IException object. The message box displays the text contained in this object.
helpPanelId: If helpPanelId is nonzero, a Help push button is displayed. When the Help push button is selected, the help panel with the ID corresponding to the helpPanelId parameter is displayed. Optional.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Styles

IMessageBox defines a set of objects of the nested class IMessageBox::Style. You can use these styles with versions of the function show to identify the push buttons and icon to be displayed on the message box, the modality of the message box, and whether the user is allowed to move the message box.

abortRetryIgnoreButton

public:
static const Style abortRetryIgnoreButton

Specifies the message box should contain the Abort, Retry, and Ignore push buttons.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

applicationModal

public:
static const Style applicationModal

Specifies that the message box be application-modal. This is the default style.
Note: The owner window of an application-modal message box is disabled while the message box is displayed.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

cancelButton

public:
static const Style cancelButton

Specifies the message box should contain a Cancel push button.

Supported Platforms

Windows	OS/2	AIX
Ignored	Yes	Yes

Windows Considerations

Specifies the message box should contain an OK push button because Windows does not have a message box with a Cancel button.

defButton1

public:
static const Style defButton1

Specifies that the default selection for the message box should be the first push button. This is the default style.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

defButton2

public:
static const Style defButton2

Specifies that the default selection for the message box should be the second push button.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

defButton3

public:
static const Style defButton3

Specifies that the default selection for the message box should be the third push button.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

enterButton

public:
static const Style enterButton

Specifies the message box should contain an Enter push button.

Supported Platforms

Windows	OS/2	AIX
Ignored	Yes	Yes

Windows Considerations

Specifies the message box should contain an OK push button because Windows does not have a message box with an Enter button.

enterCancelButton

public:
static const Style enterCancelButton

Specifies the message box should contain both Enter and Cancel push buttons.

Supported Platforms

Windows	OS/2	AIX
Ignored	Yes	Yes

Windows Considerations

Specifies the message box should contain OK and Cancel push buttons because Windows does not have a message box with Enter and Cancel buttons.

errorIcon

public:
static const Style errorIcon

Specifies the message box should contain a

icon.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

informationIcon

public:
static const Style informationIcon

Specifies the message box should contain an

icon.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

moveable

public:
static const Style moveable

Specifies that the user can move the message box. This style gives the message box a title bar.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

noIcon

public:
static const Style noIcon

Specifies the message box should contain no icon.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

okButton

public:
static const Style okButton

Specifies the message box should contain an OK push button.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

okCancelButton

public:
static const Style okCancelButton

Specifies the message box should contain both OK and Cancel push buttons.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

queryIcon

public:
static const Style queryIcon

Specifies the message box should contain a

query icon.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

retryCancelButton

public:
static const Style retryCancelButton

Specifies the message box should contain both Retry and Cancel push buttons.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

systemModal

public:
static const Style systemModal

Specifies that the message box be system modal. This prevents the user from interacting with any other window, including those of other applications, until dismissing the message box.

Supported Platforms

Windows	OS/2	AIX
Ignored	Yes	Yes

warningIcon

public:
static const Style warningIcon

Specifies the message box should contain an

icon.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

yesNoButton

public:
static const Style yesNoButton

Specifies the message box should contain both Yes and No push buttons.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

yesNoCancelButton

public:
static const Style yesNoCancelButton

Specifies the message box should contain Yes, No, and Cancel push buttons.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Title Text

Use these functions to set the text displayed in the title bar of the message box, or if the message box has no title bar, to set the text displayed above the message text.

setTitle

Sets the message box's title.

Overload 1

public:
virtual IMessageBox& setTitle(const IResourceId& title)

title: The new title. The text is the specified string resource in a string table.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Overload 2

public:
virtual IMessageBox& setTitle(const char* title)

title: The new title. The text is the specified character string.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

IMessageBox - Enumerations

Response

enum Response { enter, 
                ok, 
                cancel, 
                abort, 
                retry, 
                ignore, 
                yes, 
                no, 
                unknown }

These enumerators identify the push button used by the user to dismiss a message box.

enter: The user selected the Enter push button.
ok: The user selected the OK push button.
cancel: The user selected the Cancel push button or closed the message box using its system menu.
abort: The user selected the Abort push button.
retry: The user selected the Retry push button.
ignore: The user selected the Ignore push button.
yes: The user selected the Yes push button.
no: The user selected the No push button.
unknown: The user selected a push button other than one of the above.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Windows Considerations

The Windows platform does not support Enter push buttons in message boxes. The enter response is not applicable to that environment.

Severity

enum Severity { information, 
                warning, 
                action, 
                critical, 
                catastrophic }

Use these enumerators to specify the different severity levels of a message box:

information: Displays an information icon and an OK push button.
warning: Displays a warning icon, and Enter and Cancel push buttons.
action: Displays a query icon, and Retry and Cancel push buttons.
critical: Displays an error icon, and Retry and Cancel push buttons.
catastrophic: Displays an error icon and an OK push button.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

IMessageBox - Inherited Member Functions and Data

Inherited Public Functions

None

Inherited Public Data

None

Inherited Protected Functions

None

Inherited Protected Data

None