IMessageWindow

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 the following:

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. Use IMessageWindow instead of IMessageBox when you want to take advantage of its additional capabilities. 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 specify on the IMessageWindow constructor that give the message window a certain image, certain buttons, and an appropriate beep. Using one of these predefined types gives you a message window that looks similar to an IMessageBox object, but the range of these types in IMessageWindow is not as great as in the IMessageBox class.

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 and add them to the message window. This allows you to customize without deriving from IMessageWindow. You can also create your own buttons and have them appear on the message window by creating them with the parent window returned by buttonParent. All buttons are added left to right in the order that they are created. 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, but take care not to impact the usability of your message window with too many buttons. If you use addButton to add a predefined button that already exists on the message window, the previous instance of the button is replaced.

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 enumeration. 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. By default, the message window will do this for buttons you add with the kHelp button type.

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 must use the deferClientCreation style for your overrides of these functions to be called. The overridden functions are called the first time one of the following functions is called:

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 as a predefined control would be placed. 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 the addButton interface.

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 the first time one of the following functions is called:

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 are dependent 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 any other characteristics you may want to add, call messageType to obtain the message type specified on the constructor.

If you override createClient, you are responsible for placing and sizing the message window. Otherwise, the message window is sized based on the minimum sizes of all the contained controls and is centered on the desktop.

Since IMessageWindow derives from IFrameWindow, you can use inherited functions and styles to manage the message window. The default style of the message window is a combination of IFrameWindow styles that give it an appearance similar to the native message box. You can override this appearance by providing a combination of IFrameWindow styles on the message window constructor.

You must use an ICommandHandler to handle processing for buttons on your message window. By default, the message window does not do anything when any button is clicked. You should write your handler so that the message window is dismissed and closed when the appropriate button is pressed. The IDs for the predefined buttons provided by IMessageWindow are listed in the EButton enumeration.

You provide help for your message window just as you would any other frame window. See the IHelpWindow class for more information.


IMessageWindow - Member Functions and Data by Group

Constructors & Destructor

Constructors for the message window.


[view class]
~IMessageWindow
public:
virtual ~IMessageWindow()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IMessageWindow
public:
IMessageWindow( unsigned long id = IC_DEFAULT_FRAME_ID, IWindow* owner = 0, EMessageType type = kInformationMessage, const Style& style = defaultStyle ( ) )

Constructs an IMessageWindow from an ID, owner, message type, and style. The parent of the message window is always the desktop window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Buttons

Information about buttons used in the message window.


[view class]
addButton
public:
virtual IPushButton* addButton( EButton buttonType, bool isDefaultButton = false )

Adds a push button to the message window. The button is added to the right of any push buttons already on the message window as a result of using one of the EMessageType enumerators on construction or previous calls to addButton. If you do not want any push buttons on the message window by default, then use the kUserDefinedMessage message type on construction.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
button
public:
IPushButton* button(EButton buttonType)

Returns a pointer to the push button with the specified EButton enumerators as an id. If you have created and added a button with this id, the pointer returned will be your button. Otherwise, it will be one of the default push buttons. If the message window does not contain the push button you request, a null pointer is returned.

You can use this pointer to manipulate the button's attributes, for example, the text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
buttonParent
public:
virtual IWindow* buttonParent()

Returns the window to be used as a parent for creating buttons to be added to the message window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Customization

Use these members to customize the message window.


[view class]
createClient
protected:
virtual IWindow* createClient()

Override this function to create and customize the client window of the message window yourself. You must use the deferClientCreation style for your override to be called. The function is called the first time one of the following functions is called:

In this function you are responsible for building the message window based on criteria specific to your application and/or the EMessageType enumerator specified on construction. You can get the message type by calling the messageType function.

The window you return from this function is placed in the client area of the message window with no changes. You control the amount and type of customization for your message window with the following options:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
createMessageIdText
protected:
virtual ITextControl* createMessageIdText( IWindow* parentOwner )

Override this function to return a text control for the message window to place the message ID text into. By default, the message window creates a static text control to contain the message ID. The message ID control is placed in the lower right corner of the default message window client area.

If you override createClient, you would not typically override this function. Call the default implementation to obtain a pointer to the default static text control to place in your own customized client window.

This function is called the first time one of the following functions is called:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
createMessageImage
protected:
virtual IBitmapControl* createMessageImage( IWindow* parentOwner )

Override this function to return a bitmap control for the message window to place in its client area. By default, the bitmap control is placed in the upper left corner of the default message window client area.

If you override createClient, you would not typically override this function. Call the default implementation to obtain a pointer to the default bitmap control to place in your own customized client window.

This function is called the first time one of the following functions is called:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
createMessageText
protected:
virtual ITextControl* createMessageText( IWindow* parentOwner )

Override this function to return a text control for the message window to place the message text into. By default, the message window creates a static text control to contain the message text. The message text control is placed in the center of the default message window client area above the buttons.

If you override createClient, you would not typically override this function. Call the default implementation to obtain a pointer to the default static text control to place in your own customized client window.

This function is called the first time one of the following functions is called:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Images

Use these functions to set the image used in the message window.


[view class]
setMessageImage

Sets the message bitmap.


Overload 1
public:
virtual IMessageWindow& setMessageImage(EImageType image)

Sets the message bitmap using an image type from the EImageType enumeration.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IMessageWindow& setMessageImage( const IBitmapHandle& bitmapHandle )

Sets the message bitmap using an IBitmapHandle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Message Id

These functions set and get the message ID to be displayed.


[view class]
messageId
public:
IText messageId() const

Returns the message id text of the message window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMessageId

Sets the message ID text. The message ID area is limited to twelve characters and will be truncated if the text is longer. If you want to provide a custom control for the message ID that will not have this limitation, you can override the createMessageIdText function.


Overload 1
public:
virtual IMessageWindow& setMessageId( const IText& messageId )

Sets the message ID text using an IText control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IMessageWindow& setMessageId( const IResourceId& messageId )

Sets the message ID text using an IResourceId.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Message Text

These functions set and get the message text.


[view class]
messageText
public:
IText messageText() const

Returns the message text of the message window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMessageText

Sets the message text.


Overload 1
public:
virtual IMessageWindow& setMessageText( const IText& message )

Sets the message text using an IText control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IMessageWindow& setMessageText( const IResourceId& message )

Sets the message text using an IResourceId.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IMessageWindow& setMessageText( const IException& exception )

Sets the message text using an IException. The text for the message is the text of the exception.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Message Type

This function returns the message type.


[view class]
messageType
public:
virtual EMessageType messageType() const

Returns the EMessageType passed in on the IMessageWindow constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Showing the Message Window

Use these functions to show the message window.


[view class]
show
public:
virtual IMessageWindow& show(bool showWindow = true)

Shows or hides the message window. If you created the message window using the deferClientCreation style, the message window will be initialized when this function is called and your virtual function overrides (if any) will be called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
showModally
public:
virtual unsigned long showModally()

Shows the message window modal to its owner. If you created the message window using the deferClientCreation style, the message window will be initialized when this function is called and your virtual function overrides (if any) will be called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

Use these functions to set and get the style associated with the message window.


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. This style is a combination of IFrameWindow::dialogBorder, IFrameWindow::windowList, IFrameWindow::appDBCSStatus, IFrameWindow::titleBar, IFrameWindow::systemMenu, and IFrameWindow::dialogBackground unless you have changed the style using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent message windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
deferClientCreation
public:
static const Style deferClientCreation

Indicates that IMessageWindow should not create the client window and that the client area will be created by a subclass that has overridden the createClient function. When you use this style, the IMessageWindow will call the createClient function the first time one of the following functions is called:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IMessageWindow - Enumerations


[view class]
EButton
enum EButton { kEnter=IC_ID_ENTER, 
               kOk=IC_ID_OK, 
               kCancel=IC_ID_CANCEL, 
               kAbort=IC_ID_ABORT, 
               kRetry=IC_ID_RETRY, 
               kIgnore=IC_ID_IGNORE, 
               kYes=IC_ID_YES, 
               kNo=IC_ID_NO, 
               kHelp=IC_ID_HELP }

Use these enumerators to specify the type of button requested on a call to addButton.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
EImageType
enum EImageType { kInformationImage, 
                  kQuestionImage, 
                  kWarningImage, 
                  kErrorImage }

Use these enumerators to specify an image on the setMessageImage function.

kInformationImage
Provides an information image on the message window.
kQuestionImage
Provides a question image on the message window.
kWarningImage
Provides a warning image on the message window.
kErrorImage
Provides an error image on the message window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
EMessageType
enum EMessageType { kUserDefinedMessage, 
                    kInformationMessage, 
                    kWarningMessage, 
                    kConfirmationMessage, 
                    kRetryMessage, 
                    kCatastrophicMessage }

Use these enumerators to specify a message type on the IMessageWindow constructor. You can retrieve the message type specified on the constructor using the messageType function. Each type of message provides an appropriate beep.

kUserDefinedMessage
Provides a message window with no default image and no default buttons. You can add them yourself using addButton and setMessageImage.
kInformationMessage
Provides a message window with an information image and an OK button.
kWarningMessage
Provides a message window with a warning image and OK and cancel buttons.
kConfirmationMessage
Provides a message window with a question image and retry and cancel buttons.
kRetryMessage
Provides a message window with an error image and retry and cancel buttons.
kCatastrophicMessage
Provides a message window with an error image and an OK button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IMessageWindow - Inherited Member Functions and Data

Inherited Public Functions

IFrameWindow
INotifier
IWindow

Inherited Public Data

IFrameWindow
IWindow
INotifier

Inherited Protected Functions

IFrameWindow
IWindow
INotifier

Inherited Protected Data

IFrameWindow