Flags and Return Values from HtmlMessageBox / Show

Top  Previous  Next

This page details both the elements that can go into the flags parameter of the HtmlMessageBox / Show function, and that function's return values.

 

All of the codes for flags and return values can be found in winuser.h, for C/C++ programmers, or as properties of the COM object or static/shared properties of the sample .NET classes. Because a different interface is used for the PowerBuilder Show functions, none of these flags and return values apply to it.

 

Flags

 

The flags parameter to the HTMLMessageBox / Show function can include one from each of the following groups of codes. You add the desired codes together to get the complete flags parameter.

 

Codes for which Buttons to Display:

 

MB_OK: Only the OK button is shown (this is the default if none of these codes is used).

MB_OKCANCEL: OK and Cancel buttons are shown, and pressing ESC or closing the MessageBox does a Cancel.

MB_YESNO: Yes and No buttons are shown.

MB_YESNOCANCEL: Yes, No and Cancel buttons are shown, and pressing ESC or closing the MessageBox does a Cancel.

MB_RETRYCANCEL: Retry and Cancel buttons are shown, and pressing ESC or closing the MessageBox does a Cancel.

MB_ABORTRETRYIGNORE: Abort, Retry and Ignore buttons are shown.

MB_CANCELTRYCONTINUE: Cancel, Try Again and Continue buttons are shown.

 

Note: In any version of Windows after Windows 2000 (i.e. XP, Vista or later), if you have a non-English language version of Windows, the names of the buttons (e.g. "OK" etc.) will be the standard translated buttons that you would see in standard Windows API MessageBox calls.

 

Codes for which Icon to Display:

 

MB_ICONINFORMATION: The standard Information icon is displayed.

MB_ICONEXCLAMATION: The standard Exclamation icon is displayed.

MB_ICONSTOP: The standard Stop sign icon is displayed.

MB_ICONQUESTION: The standard Question mark icon is displayed.

 

If none of these codes is used, there is no icon on the MessageBox.

 

Codes for which Button is the Default (has the focus):

 

MB_DEFBUTTON1: The first button has the focus when the MessageBox is displayed. (This is the default.)

MB_DEFBUTTON2: The 2nd button has the focus.

MB_DEFBUTTON3: The 3rd button has the focus.

 

Obviously it only makes sense to use MB_DEFBUTTON2 or MB_DEFBUTTON3 if you have selected a code for buttons that has at least 2 buttons in it, or 3 buttons in it, respectively.

 

Unimplemented Codes

 

The following codes from the standard Windows MessageBox API are not implemented in this version of the library. (Please contact me if you strongly need them, so that I can consider adding them as enhancements.)

 

MB_HELP: Adds a Help button to the MessageBox

 

MB_ICONWARNING: A synonym for MB_ICONEXCLAMATION, so not needed.

MB_ICONASTERISK: A synonym for MB_ICONINFORMATION, so not needed.

MB_ICONERROR, MB_ICONHAND: Synonyms for MB_ICONSTOP, so not needed.

 

MB_DEFBUTTON4: Not needed because none of the button choices contain 4 buttons, and MB_HELP is not implemented.

 

MB_APPLMODAL: The MessageBox is modal with respect to the window identified in the hWnd parameter of the HtmlMessageBox / Show call (or the parent window which created the MessageBox if 0 is passed for hWnd), but possibly not with respect to other top-level windows in the same thread or windows in other threads of the same application.

MB_TASKMODAL: The MessageBox is modal with respect to all top-level windows in the calling application.

MB_SYSTEMMODAL: The MessageBox is top-most.

 

All of these codes are ignored - the MessageBox is always MB_APPLMODAL.

 

All of the following are obscure or unusual, and not implemented:

 

MB_DEFAULT_DESKTOP_ONLY: Related to which desktop the MessageBox is displayed on if there are multiple desktops.

MB_RIGHT: The text is right-justified.

MB_RTLREADING: Displays message and caption text using right-to-left reading order on Hebrew and Arabic systems.

MB_SETFOREGROUND: The message box becomes the foreground window.

MB_TOPMOST: The message box is created with the WS_EX_TOPMOST window style.

MB_SERVICE_NOTIFICATION: Related to calling from a service, or from Terminal Services.

MB_SERVICE_NOTIFICATION_NT3X: Like MB_SERVICE_NOTIFICATION, but for Windows NT 3.51.

 

Return Values

 

The HtmlMessageBox / Show function always returns a code to indicate which button was clicked. If the Cancel button is included in the MessageBox and the user presses ESC or closes the box with the close button in the top right corner, IDCANCEL is returned.

 

IDOK: The OK button was clicked.

IDCANCEL: The Cancel button was clicked, or ESC was pressed or the MessageBox was closed.

IDYES: The Yes button was clicked.

IDNO: The No button was clicked.

IDABORT: The Abort button was clicked.

IDRETRY: The Retry button was clicked.

IDIGNORE: The Ignore button was clicked.