apters, you learned how to modify the dialog box functions called in
your script. In this chapter, you will see how to modify built-in dialog boxes and
create your own custom dialog boxes, if none of the built-in dialog boxes has the
appearance or behavior you want.
Creating a New Custom Dialog Box
To add a custom dialog box to your installation project, you need to perform the
following general steps.
1.
Create the dialog box using the Dialog Editor, and add controls to it.
2.
Create a script function that loads the dialog box into memory, displays it on the
screen, handles the user's interaction with the dialog's controls, and closes the
dialog box when the user is finished with it.
Creating the Dialog Box
The first step in creating a custom dialog box is to create the blank dialog box and lay
out the controls used on it.
This chapter is a sample from the training manual Learning InstallScript
Projects Using InstallShield 2008. For information about attending a training
course or purchasing this training manual, please visit
http://www.macrovision.com/services/education/index.shtml
. Chapter 9: Custom Dialog Boxes
Creating a New Custom Dialog Box
192
Learning InstallScript Projects Using InstallShield 2008
T
ASK
To create the blank dialog box:
1.
In the Dialogs view (in the User Interface view group), right-click the All Dialogs
icon at the top of the view and select New Dialog, or press Insert. This launches
the Dialog Wizard, which enables you to quickly create new end-user dialog
boxes.
2.
In the Dialog Template panel of the Dialog Wizard (not shown), select the
NewScriptBasedDialog template. (If your project uses dialog skins, select the
NewSkinnableDialog template.) The script-based dialog template contains the
standard elements of most built-in dialog boxes, such as the Next, Back, and
Cancel buttons and the dialog banner bitmap. Click Finish to add the dialog
template to the project.
3.
In the All Dialogs list, rename the dialog box by right-clicking its icon, selecting
Rename, and typing (for example)
CustomDialog
.
Figure 9-1: The CustomDialog in the All Dialogs list of the Dialogs view.
Under your custom dialog icon is an icon representing each language supported by
your project. To add or modify the controls on your custom dialog box, select the
desired language icon; selecting a language icon opens the Dialog Editor in the right
side of the interface. Chapter 9: Custom Dialog Boxes
Creating a New Custom Dialog Box
Learning InstallScript Projects Using InstallShield 2008
193
Figure 9-2: The Dialog Editor.
When you select a control or dialog box in the Dialog Editor, you can edit the selected
items property list on the right side of the view.
T
IP
To maximize the Dialog Editor, press Ctrl+M.
To add a control to a dialog box, select the desired control from the Controls toolbar,
and then drag a rectangle on the dialog box representing the control.
Figure 9-3: The Dialog Controls toolbar.
If the Controls toolbar is not displayed, you can enable it by selecting Customize from
the Tools menu, and selecting the Controls toolbar. There is also a Layout toolbar
that enables you to align and resize controls (not shown).
For example, the following figure shows the custom dialog box with an added push
button control. The value of the Text property of the button has been changed to OK. Chapter 9: Custom Dialog Boxes
Creating a New Custom Dialog Box
194
Learning InstallScript Projects Using InstallShield 2008
Figure 9-4: Custom dialog box with a push button control.
The following section describes the general process of displaying and processing the
dialog box in your InstallScript code. Later sections describe the use of specific
additional types of controls.
Processing Controls in the Script
After you have created the dialog box and placed controls on it, the next step is to
write an InstallScript function that processes the end users interaction with the dialog
box controls. You begin by creating a new InstallScript source file to contain the
custom dialog box code.
T
ASK
To create a new source file:
1.
Right-click the script Files icon and choose New Script File, or press Insert.
2.
Rename the script to (for example)
CustomDialog.rul
.
Figure 9-5: The CustomDialog.rul script file. Chapter 9: Custom Dialog Boxes
Creating a New Custom Dialog Box
Learning InstallScript Projects Using InstallShield 2008
195
Inside the source file
CustomDialog.rul
, you place the prototype and implementation
for your custom dialog box function. Add the following code to
CustomDialog.rul
.
prototype NUMBER CustomDialog( );
function NUMBER CustomDialog( )
begin
end;
When you compile your script, you must ensure the main script
Setup.rul
includes
the source code for your
CustomDialog
function, by inserting the line
#include "CustomDialog.rul"
near the top of
Setup.rul
.
In the
CustomDialog.rul
script, the next step is to define constants that store the
numeric resource IDs of the controls you added to the dialog box. Each control ID is
stored in the Control Identifier property for the control, visible in the Dialog Editor.
You should copy these definitions to the top of your
CustomDialog.rul
script.
#define OK_BUTTON 1302
If you used the script-based dialog template, the Back, Next, and Cancel buttons use
the following resource IDs: Next button: SD_PBUT_OK or SD_PBUT_CONTINUE (1) Back button: SD_PBUT_BACK (12)
These constants are defined when you include
ifx.h
, and it is therefore unnecessary
to redefine them in your script. The Cancel button on the standard dialog box template
has resource ID 9, and you can define a constant to store this value.
Next, your
CustomDialog
function loads the custom dialog box into memory using the
EzDefineDialog
function:
EzDefineDialog(
"CustomDialog", // "nickname" for dialog box
ISUSER, // DLL containing the dialogs resources
"CustomDialog", // name of dialog from Dialogs view
NULL); // numeric resource ID; not used here
The arguments you use with
EzDefineDialog
are the following: The first argument is the dialogs nickname, which is used in dialog-processing
functions such as
WaitOnDialog
,
EndDialog
, and
ReleaseDialog
. This name can be
retrieved in a script using the
GetCurrentDialogName
function. The second argument specifies the
.dll
file that contains the dialog box
resources. Internally, InstallShield stores your custom dialog boxes in a file called
_ISUser1033.dll
; InstallScript provides a system variable called
ISUSER
that
refers to this file. (The number used in the file name1033 in this example Chapter 9: Custom Dialog Boxes
Creating a New Custom Dialog Box
196
Learning InstallScript Projects Using InstallShield 2008
identifies the language the dialog box is intended for. If you have custom dialog
boxes for multiple languages, InstallShield creates a separate
.dll
file for each
language.) The third argument is the string name of the dialog box as it appears in the Dialogs
view, such as
"CustomDialog"
. The fourth argument is the numeric dialog box resource ID; you can set this
argument to zero or NULL if you specified the dialogs name in the third
argument to
EzDefineDialog
.
The next step is to create a message loop in your script. The message loop repeatedly
calls the function
WaitOnDialog
, which returns the numeric resource ID for the control
the user interacts with. A typical message loop appears as follows:
// repeatedly call WaitOnDialog until the user exits the dialog
// box with the Next, Back, or Cancel button
while (!bDone)
// wait for the user to interact with a control,
// then return its ID
nCtrl = WaitOnDialog("CustomDialog");
// use a switch statement to handle the different controls
switch (nCtrl)
case CONTROL1:
// do something when user clicks CONTROL1
case CONTROL2:
// do something when user clicks CONTROL2

// case statements for other controls
endswitch;
endwhile;
For example,
CustomDialog
currently contains the standard Back, Next, and Cancel
buttons, along with a custom OK button; its message loop might appear as follows:
while (!bDone)
nCtrl = WaitOnDialog("CustomDialog");
switch (nCtrl)
case OK_BUTTON:
// user clicked OK button
MessageBox("You clicked OK.", INFORMATION);
case SD_PBUT_OK:
// user clicked Next Chapter 9: Custom Dialog Boxes
Creating a New Custom Dialog Box
Learning InstallScript Projects Using InstallShield 2008
197
nReturn = SD_PBUT_OK;
bDone = TRUE;

case SD_PBUT_BACK:
// user clicked Back
nReturn = SD_PBUT_BACK;
bDone = TRUE;
case SD_PBUT_CANCEL:
// user clicked Cancel or close button; ask user to verify
Do(EXIT);
endswitch;
endwhile;
Finally, when the end user exits the dialog box by clicking Back or Next, you should
remove the dialog box from the screen and from memory by calling
EndDialog
and
ReleaseDialog
.
EndDialog("CustomDialog");
ReleaseDialog("CustomDialog");
To use the dialog box in the main script, add a call to the
CustomDialog
function in, for
example, the
OnFirstUIBefore
event handler in
Setup.rul
.
Dlg_SdWelcome:
szTitle = "";
szMsg = "";
nResult = SdWelcome( szTitle, szMsg );
if (nResult = BACK) goto Dlg_Start;
Dlg_CustomDialog:
nResult = CustomDialog( );
if (nResult = SD_PBUT_BACK) goto Dlg_Welcome;
// etc.
After you compile your script and rebuild your proj