Contents

Introduction

Another MessageBox :The CodeProject site contains more solutions as an extension to the standard MessageBox. So why another one? You may ask. I don't develop classes unless I feel there's a real need for them in my own projects. For a long time I've used "XMessageBox - A reverse-engineered MessageBox()" class by Hans Dietrich. That is a nice class and I am thankful to him for his work. However, all things comes an end. This class has ceased to satisfy me. I wished to have a class that would allow me to control the colors of the message text and background. I had already developed, and successfully tested, a class for drawing pseudo-HTML in my own classes CPPToolTip and CPPHtmlStatic. So, the solution for drawing colored text was easily found. For the additional features of this class, I relied on already available classes on CodeProject. Many thanks to all those who have helped me in creating this class, in particular to the authors of these classes published on CodeProject:

Adds a "Yes to All" button to the message box. This flag combined with MB_YESNO, MB_YESNOCANCEL flags only.

To indicate the checkbox displayed in the message box, specify one of the following values:

<TR bgColor=#cccccc>

Value

Description

MB_CHECKBOX

Adds a checkbox to the message box. If MB_CHECKBOXUNDERBUTTONS flag not specified, a checkbox will be placed over the message box buttons. A checkbox has a "Do Not Show Again" text by default. You can change this text through lpszCheckBoxText member of a PPMSGBOXPARAMS structure.

MB_CHECKBOXCHECKED

A checkbox will check by default. This flag combined with MB_CHECKBOX only.

MB_CHECKBOXUNDERBUTTONS

A checkbox will place under the message box buttons. This flag combined with MB_CHECKBOX only.

To display an icon in the message box, specify one of the following values.

<TR bgColor=#cccccc>

Value

Description

MB_ICONEXCLAMATION

An exclamation-point icon appears in the message box.

MB_ICONWARNING

An exclamation-point icon appears in the message box.

MB_ICONINFORMATION

An icon consisting of a lowercase letter i in a circle appears in the message box.

MB_ICONASTERISK

An icon consisting of a lowercase letter i in a circle appears in the message box.

MB_ICONQUESTION

A question-mark icon appears in the message box.

MB_ICONSTOP

A stop-sign icon appears in the message box.

MB_ICONERROR

A stop-sign icon appears in the message box.

MB_ICONHAND

A stop-sign icon appears in the message box.

To indicate the default button, specify one of the following values.

<TR bgColor=#cccccc>

Value

Description

MB_DEFBUTTON1

The first button is the default button. MB_DEFBUTTON1 is the default unless MB_DEFBUTTON2, MB_DEFBUTTON3, MB_DEFBUTTON4, MB_DEFBUTTON5, or MB_DEFBUTTON6 is specified.

MB_DEFBUTTON2

The second button is the default button.

MB_DEFBUTTON3

The third button is the default button.

MB_DEFBUTTON4

The fourth button is the default button.

MB_DEFBUTTON5

The fifth button is the default button.

MB_DEFBUTTON6

The sixth button is the default button.

To specify other options, use one or more of the following values:

<TR bgColor=#cccccc>

Value

Description

MB_NORESOURCE

Do not try to load button strings from resources. (See PPMessageBox.h for string resource id numbers.) If this flag is used, English strings will be used for buttons and checkboxes. If this flag is not used, PPMessageBox() will attempt to load the strings for buttons and checkboxes from string resources first, and then use English strings if that fails.

MB_NOSOUND

Do not play sounds when message box is displayed.

MB_RIGHT

The text is right-justified.

MB_SETFOREGROUND

The message box becomes the foreground window. Internally, the system calls the SetForegroundWindow function for the message box.

MB_TOPMOST

The message box is created with the WS_EX_TOPMOST window style.

pMsgBox

Pointer to a PPMSGBOXPARAMS structure that contains information used to display the message box.

Return values

If a message box has a Cancel button, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect. If there is no enough memory to create the message box, the return value is zero. If the function succeeds, the return value is one of the following menu-item values:

<TR bgColor=#cccccc>

Value

Description

IDABORT

Abort button was selected.

IDCANCEL

Cancel button was selected.

IDCLOSE

Close button was selected.

IDCONTINUE

Continue button was selected.

IDCUSTOM1

Custom 1 button was selected.

IDCUSTOM2

Custom 2 button was selected.

IDCUSTOM3

Custom 3 button was selected.

IDCUSTOM4

Custom 4 button was selected.

IDIGNORE

Ignore button was selected.

IDIGNOREALL

Ignore All button was selected.

IDNO

No button was selected.

IDNOTOALL

No To All button was selected.

IDOK

OK button was selected.

IDRETRY

Retry button was selected.

IDSKIP

Skip button was selected.

IDSKIPALL

Skip All button was selected.

IDTRYAGAIN

Try Again button was selected.

IDYES

Yes button was selected.

IDYESTOALL

Yes To All button was selected.

Return value can include a combination of the following flags:

<TR bgColor=#cccccc>

Value

Description

MB_CHECKBOXCHECKED

A checkbox was checked.

MB_TIMEOUT

Returned if timeout expired.

Remarks

The PPMessageBox function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons.

When you use a system-modal message box to indicate that the system is low on memory, the strings pointed to by the lpszText and lpszCaptionmembers of the PPMSGBOXPARAMS structure should not be taken from a resource file, because an attempt to load the resource may fail.

If you create a message box while a dialog box is present, use a handle to the dialog box as the hWnd parameter. The hWndparameter should not identify a child window, such as a control in a dialog box.

PPMessageBoxIndirect

Parameters

pMsgBox

Pointer to a PPMSGBOXPARAMS structure that contains information used to display the message box.

Return values

If a message box has a Cancel button, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect. If there is no enough memory to create the message box, the return value is zero. If the function succeeds, the return value is one of the following menu-item values:

<TR bgColor=#cccccc>

Value

Description

IDABORT

Abort button was selected.

IDCANCEL

Cancel button was selected.

IDCLOSE

Close button was selected.

IDCONTINUE

Continue button was selected.

IDCUSTOM1

Custom 1 button was selected.

IDCUSTOM2

Custom 2 button was selected.

IDCUSTOM3

Custom 3 button was selected.

IDCUSTOM4

Custom 4 button was selected.

IDIGNORE

Ignore button was selected.

IDIGNOREALL

Ignore All button was selected.

IDNO

No button was selected.

IDNOTOALL

No To All button was selected.

IDOK

OK button was selected.

IDRETRY

Retry button was selected.

IDSKIP

Skip button was selected.

IDSKIPALL

Skip All button was selected.

IDTRYAGAIN

Try Again button was selected.

IDYES

Yes button was selected.

IDYESTOALL

Yes To All button was selected.

Return value can include a combination of the following flags:

<TR bgColor=#cccccc>

Value

Description

MB_CHECKBOXCHECKED

A checkbox was checked.

MB_TIMEOUT

Returned if timeout expired.

Remarks

The PPMessageBoxIndirect function creates, displays, and operates a message box. The message box contains application-defined message text and title, any icon, and any combination of predefined push buttons.

When you use a system-modal message box to indicate that the system is low on memory, the strings pointed to by the lpszText and lpszCaption members of the PPMSGBOXPARAMS structure should not be taken from a resource file, because an attempt to load the resource may fail.

If you create a message box while a dialog box is present, use a handle to the dialog box as the hWnd parameter. The hWnd parameter should not identify a child window, such as a control in a dialog box.

Members

Handle to the module that contains the string resource identified by the lpszText, lpszCaption and other string members.

hInstanceIcons

Handle to the module that contains the icon resource identified by the lpszIconmember.

lpszCaption

Pointer to a null-terminated string, that contains the message box title. If this member is NULL, the default title Error is used.

lpszModuleName

Specifies the source module name for the application. This may be the actual source module name (for example, the name returned by the __FILE__ macro) or a name meaningful to the context (for example, "ConfirmFileDelete"). This is used when saving the "Do Not Ask/Tell" checkbox state in the registry or ini file.

It is up to the application to manage this registry entry. If it is necessary to clear out this entry each time the application starts up, the application must include the code to do this. All key/value pairs for XMessageBox are stored in the registry under HKEY_CURRENT_USER\Software\CompanyName\AppName\PPMessageBox. If an ini file is being used, the checkbox state will be saved in the file PPMessageBox.ini, in the app's directory.

When the message box is displayed, if lpszModule has been specified in the XMSGBOXPARAMSstruct, the message box will only be displayed if the registry entry does not exist. If the message box is displayed, and the user checks the "Do Not Ask/Tell" checkbox, the checkbox state will be saved in the registry.

lpszCompanyName

Specifies the company name for the application. This is used when saving the "Do Not Ask/Tell" checkbox state in the registry or ini file.

nLine

Specifies the source module line number for the application. This is used when saving the "Do Not Ask/Tell" checkbox state in registry. Note that regardless of whether the lpszModule string is encoded, the line number will not be encoded.

dwReportMsgID

Specifies the message to be sent by click on the Report button.

pMsgBoxBk

PPMSGBOXAREA_BK structure that contains information used to display the background of the all message box.

nHeaderHeight

The minimal height of the message box header.

lpszHeaderText

Pointer to a null-terminated string, or the identifier of a string resource passed to the MAKEINTRESOURCE macro, that contains the header to be displayed. This string may has a HTML-like format.

pHeaderBk

PPMSGBOXAREA_BK structure that contains information used to display the background of the header area of the message box.

lpszText

Pointer to a null-terminated string, or the identifier of a string resource passed to the MAKEINTRESOURCE macro, that contains the message to be displayed. This string may be in a HTML-like format.

nControlsAlign

Value that specifies the horizontal alignment of the button in the message box. This member can be one of the following values: PPMSGBOX_ALIGN_LEFT, PPMSGBOX_ALIGN_RIGHT or PPMSGBOX_ALIGN_CENTER.

dwStyle

Specifies the contents and behavior of the dialog box. This member can be a combination of flags described for the dwStyle parameter of the PPMessageBox function.

In addition, you can specify the MB_USERICON flag if you want the message box to display the icon specified by the lpszIcon member.

pControlBk

PPMSGBOXAREA_BK structure that contains information used to display the background of the controls' area of the message box.

lpszMoreInfo

Pointer to a null-terminated string, or the identifier of a string resource passed to the MAKEINTRESOURCE macro, that contains the additional information to be displayed. This string may be in a HTML-like format.

pMoreInfoBk

PPMSGBOXAREA_BK structure that contains information used to display the background of the MoreInfo area of the message box.

nTimeoutSeconds

Specifies the time-out value, in seconds, before auto-click a default button.

nDisabledSeconds

Specifies the time-out value, in seconds, to disable a default button or all buttons of the message box (exclude the 'Help', 'Report' and 'MoreInfo' buttons).

bDisableAllCtrls

Flag that indicates whether default button is being disabled (FALSE) or all buttons of the message box are being disabled (TRUE). The 'Help', 'Report' and 'MoreInfo' buttons are never disabled.

dwContextHelpID

Identifies a help context. If a help event occurs, this value is specified in the HELPINFO structure that the message box sends to the owner window or callback function.

lpszIcon

Identifies an icon resource. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro.

To load one of the standard system-defined icons, set the hInstance member to NULL and zIcon to one of the values listed with the LoadIcon function.

This member is ignored if the dwStyle member does not specify the MBUSERICON flag.

lpszCustomButtons

Pointer to a null-terminated string, or the identifier of a string resource passed to the MAKEINTRESOURCE macro, that contains the list of the custom button captions. This string has the format "Custom 1\nCustom 2\nCustom 3\nCustom 4". NULL if custom buttons are not used.

Up to four buttons may be specified. When a custom button is clicked, it will return the value IDCUSTOM1, IDCUSTOM2, etc. When custom buttons are specified, no other buttons will be displayed (except 'Help', 'Report' and 'MoreInfo' buttons. These buttons may be displayed anyway).

lpszCheckBoxText

Pointer to a null-terminated string, or the identifier of a string resource passed to the MAKEINTRESOURCE macro, that contains the checkbox caption. You can change a checkbox caption for each message box. If this parameter is NULL, then a checkbox caption is retrieved from the map specified by pLocalBtnText member or from the resources. If that parameter is also NULL, the check box caption will default to 'Do not show again'.

pLocalBtnText

Pointer to the map that contains pointer to a null-terminated string, or the identifier of a string resource passed to the MAKEINTRESOURCE macro that contains the button captions. Key of the map is the button ID (for example: IDOK, IDCANCEL, IDYES, MB_CHECKBOX etc.).

CPPMessageBox::MessageBox

Parameters

lpszText - Pointer to a null-terminated string that contains the message to be displayed.

lpszCaption - Pointer to a null-terminated string that contains the dialog box title. If this parameter is NULL, the default title Error is used.

nStyle - Specifies the contents and behavior of the dialog box. See the PPMessageBox method for more information.

pMsgBox - Pointer to a PPMSGBOXPARAMS structure that contains information used to display the message box.

Return values

If a message box has a Cancel button, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect.

If the function succeeds, see the PPMessageBox method for more information about return values.

If there is not enough memory to create the message box, the return value is zero.

Remarks

The MessageBox function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons. See the PPMessageBox method for more information.

CPPMessageBox::MessageBoxIndirect

int MessageBoxIndirect(const PPMSGBOXPARAMS * pMsgBox = NULL);

Parameters

pMsgBox - Pointer to a PPMSGBOXPARAMS structure that contains information used to display the message box.

Return values

If a message box has a Cancel button, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect. If the function succeeds, see the PPMessageBox method for more information about return values. If there is not enough memory to create the message box, the return value is zero.

Remarks

The MessageBox function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons. See the PPMessageBoxIndirect method for more information.

Remarks

CPPMessageBox::SetTimeouts

Parameters

nAutoclick - Specifies the time-out value to auto click a default button, in seconds. If this parameter is a non-zero value then a default button will be clicked after time-out (nDisable and bGlobalDisable parameters are ignored).

nDisable - Specifies the time-out value to disable a default button or to disable all buttons of the message box, in seconds. This parameter is valid only if nAutoclick parameter is zero.

bGlobalDisable - TRUE to disable all buttons of the message box; otherwise to disable a default button only.

Remarks

Set a time-out value to auto-click or to disable the buttons of the message box. For more information see a following table:

CPPMessageBox::SetCustomButtons

Parameters

lpszButtonNames - Pointer to a null-terminated string, or the identifier of a string resource passed to the MAKEINTRESOURCE macro, that contains the list of the custom button captions.

Remarks

Specifies the strings to be used for the custom button captions. This string has the format "Custom 1\nCustom 2\nCustom 3\nCustom 4". NULL if custom buttons are not used. Up to four buttons may be specified. When a custom button is clicked, it will return the value IDCUSTOM1, IDCUSTOM2, etc. When custom buttons are specified, no other buttons will be displayed (except 'Help', 'Report' and 'MoreInfo' buttons. These buttons can always be displayed).

Use API method

Include the header file PPMessageBox.h in the header file where you want to call PPMessageBox() method.

Use as MFC class or WTL class

Include the header file PPMessageBoxClass.h in the header file where you want to use a CPPMessageBox() class and create an member variable.

CPPMessageBox m_pMsgBox;

You can use the OnCreate(),OnInitDialog() and any other methods for customization or showing message box.

History

14 February 2005

First release

Copyright & Disclaimer

THIS SOFTWARE AND THE ACCOMPANYING FILES ARE DISTRIBUTED "AS IS" AND WITHOUT ANY WARRANTIES WHETHER EXPRESSED OR IMPLIED. NO RESPONSIBILITIES FOR POSSIBLE DAMAGES OR EVEN FUNCTIONALITY CAN BE TAKEN. THE USER MUST ASSUME THE ENTIRE RISK OF USING THIS SOFTWARE.

THIS SOFTWARE IS FREE FOR PERSONAL USE OR FREEWARE APPLICATIONS. IF YOU WISH TO THANK MY WORK, YOU MAY DONATE ANY SUM OF MONEY TO ME FOR SUPPORT OF DEVELOPMENT OF THIS CLASS. IF YOU USE THIS SOFTWARE IN COMMERCIAL OR SHAREWARE APPLICATIONS YOU ARE GENTLY ASKED TO DONATE ANY SUM OF MONEY TO THE AUTHOR.

Contacting the Author

You are encouraged to use this class everywhere you want; there is no fee required for CPPMessageBox. Freely add modifications and/or fix bugs, but please, send any of these to me!

Comments and Discussions

when I adopt the class in my project, however, I do not like the default button on the messagebox, and I want to replace it with myown-draw button class, after reading your code, I have not an idea at all, Can you help me?