Usage Examples

There are two main interfaces provided in object code with the program: a DLL with the standard Windows API calling convention (__stdcall for you C/C++ programmers), and a COM control. Both use UNICODE strings. In addition, sample code is provided for several other programming languages (currently, C#, and PowerBuilder).

To use the DLL, you may choose to call any or all of the following functions initially, in order to change from the default font of Arial 10, or the default behaviour that <BR> is required for line breaks, and newlines (or carriage returns followed by newlines) are just treated as whitespace:

HtmlMessageBoxSetDefaultFontFace("fontName");

HtmlMessageBoxSetDefaultPointSize(sizeInPoints);

HtmlMessageBoxSetNewlineIsBreak(1); // newlines are treated as line breaks, like <BR>, if the passed-in value is non-0

Then any time you need a MessageBox, just call the following function which has the exact same signature as the UNICODE version of the standard Windows API MessageBox call:

HtmlMessageBox(hWnd, text, caption, flags);

where hWnd is a window handle (or 0), text is the text (or HTML) to be displayed, caption is the title bar text for the MessageBox, and flags contains the same flags as in the standard MessageBox API, with some small limitations (see the reference section for details). The flag values and return values can be found in winuser.h, if you are doing C/C++ programming.

COM API

To use the COM API, first you have to register the COM DLL (HtmlMessageBoxCom.dll). For that to succeed, the standard DLL (HtmlMessageBox.dll) must be in the same directory as the COM DLL being registered. The installation of the entire downloaded package does this, but if you are distributing an application, you are not permitted to distribute the HTML MessageBox installer, so you will have to do this registration yourself in your installer..

You then need to create the COM object as you normally would in whatever your development environment is - its ID is:

 "HtmlMessageBoxCom.HtmlMessageBox"

Assuming you have created that as an object named "msg", your calls would then be to the following methods corresponding to the standard Windows API-style methods referred to above:

In addition, the COM object has read-only properties for all of the possible flag values and return values for the Show method, such as msg.MB_OK, msg.MB_ICONEXCLAMATION, msg.MB_DEFBUTTON1, msg.IDOK etc. See the reference section for all of the flags and return values.

.NET API

Sample C# code is supplied in the installed Samples directory. Either one creates a class HtmlMsgBox,  with static methods that use PInvoke to call the methods in the DLL, and also provides static/shared integer constants for all of the possible flag values and return values for the Show method (as is done with the COM API). The method names are exactly the same as for the COM API above, e.g. SetDefaultFontFace, SetDefaultPointSize, SetNewlineIsBreak, and Show.

N.B. This is not the way the standard .NET System.Windows.MessageBox class works. If anyone using this product would like to create a class that more closely models itself after the .NET MessageBox class' API, and share it with me for (license free!) distribution with the program, I would be happy to do so.

PowerBuilder API

Although PowerBuilder (PB) could call the standard API functions from HtmlMessageBox.dll directly, its built-in MessageBox function has a significantly different calling convention. To work around that, in the installed samples directory a PowerBuilder non-visual object (NVO) is provided, nvo_messagebox.sru, that can be imported into your PBL. It declares the DLL's API functions as local external functions, but then has several overloaded Show() methods that mirror the PB MessageBox API. One difference, however, is that in this implementation I dropped the initial "title" argument, which is instead set by setting the instance variable is_title on the NVO, on the assumption that most MessageBoxes in your application will have the same title, usually the name of the application. (If this isn't how you want to use it, you can of course modify the methods in the NVO.)