The script functions to call external DLLs now allow you to access Windows API objects and functions. The most commonly used of these are the Windows Message Boxes which bring up alerts or information with OK, Cancel and other buttons on. Using the inbuilt message boxes has the advantage of being consistent with the user’s interface as well as being quicker than designing your own.
Full details of the range of Windows Message Boxes and how to use them can be found in the documentation on the MSDN site. However the key information is detailed below.
Displaying the Message Box
The Windows message boxes are provided in a DLL called User32.DLL which is located in the system directory for Windows. It cannot be redistributed with your publication but is consistent to, and required by, all versions of Windows.
To call the function you need to use the LoadDLL function to load the DLL into an object and then CallFn to call the message box function. In doing so you can provide the text to appear in the Message Box and in the title bar of the Window as well as specifying the combination of icon and button(s) to be used.
The Window’s message boxes feature various combinations buttons and icons (Warning, Error, Information, Question etc.) which are set by providing a single number as the final part of the params which can also be used to set which button is the default.
You combine one number from three sections (they need to be combined using bitwise operators but in most cases this is identical to simply adding the numbers together)
Buttons:
OK = 0
OK and CANCEL = 1
ABORT, RETRY and IGNORE = 2
YES, NO and CANCEL =3
YES and NO =4
RETRY and CANCEL =5
Icons:
STOP = 16
QUESTION = 32
WARNING = 48
INFO =64
Default Button:
First button = 0
Second button = 256
Third button = 512
Fourth button =768
Almost any combination of buttons and icon is available but the key ones are:
Information icon with a single OK button = 64
Warning icon with a single OK button = 48
Stop icon with a single Cancel button = 16
Warning with OK and Cancel buttons = 49
Question with Yes and No buttons = 36
Question icon with Yes No Cancel buttons = 35
Example
Thus the syntax for displaying the message box below is:
var UserDLL=LoadDLL(SYSTEM_WINSYS_DIR + "User32.DLL")
if (UserDLL)
{
var MsgBox=UserDLL.CallFn("MessageBoxA", true, "slong", "hwnd", 0, "string", "Please complete all questions before continuing", "string","Reminder",64)
}
In some cases (especially where the message box displays more than one button) you will want to know which button on the Message Box has been pressed by your user. You can then respond accordingly.
The return values for the different buttons available across the range of Message Boxes are:
0 –Error
1 – OK button pressed
2 – CANCEL button pressed
3 – ABORT button pressed
4 – RETRY button pressed
5 – IGNORE button pressed
6 – YES button pressed
7 – NO button pressed
10 – TRY AGAIN button pressed
11 – CONTINUE button pressed
In this simple example the user is given a choice to confirm that they wish to exit the publication. It displays a Question icon with a Yes or No button and then exits the publication only if the Yes button has been pressed (returning the value 6 into the variable UserAnswer).
var UserDLL = LoadDLL( SYSTEM_WINSYS_DIR + "User32.dll");
if (UserDLL)
{
var UserAnswer = UserDLL.CallFn( "MessageBoxA", true, "slong", "hwnd", 0, "string", "Are you sure you want to exit the publication?", "string", "Confirm Exit", "ulong", 36 );
if (UserAnswer==6)
{ExitPublication()
}
}
