Project: This information applies to the following project types:
• | InstallScript |
• | InstallScript MSI |
1. | Begin by creating a new InstallScript source file to contain the custom dialog code. Name the file CustomDialog.rul. |
Tip: To be able to use the dialog script in other projects, copy the .rul file to another location. In your other projects, open the InstallScript view, right-click the Files item in the InstallScript explorer, and click Insert Script Files.
2. | Inside CustomDialog.rul, place the prototype and implementation for your custom dialog function. Add the following code to CustomDialog.rul. |
3. | When you compile your script, indicate that the main script Setup.rul should include the code for your CustomDialog function by inserting the following line near the top of Setup.rul: |
4. | In the CustomDialog.rul script, define the constants that store the numeric IDs of the controls that you added to the dialog. If you copied the Back, Next, and Cancel buttons from a standard dialog, you can add the following lines near the top of CustomDialog.rul: |
Important: To enable end users to cancel the installation by clicking the close button in the upper-right corner of the InstallScript dialog, the dialog must have a button control with a value of 2 for the Control Identifier property. You can place this button anywhere on the dialog, and if necessary, you can make this button invisible. This is necessary because the InstallScript engine passes the WM_CLOSE message to the script only if it comes from a valid control in the dialog. If the dialog does not have a button with this identifier, the installation does not pass through the message that is generated when the dialog’s close button is clicked.
5. | Your CustomDialog function loads the custom dialog into memory using the EzDefineDialog function: |
Tip: The resource ID of a dialog is the dialog’s name, as it appears in the Dialog Editor. If you need to specify a numeric resource ID, you can add a numeric ID to the ISResourceId column in the Dialog table for the custom dialog. You can access the Dialog table in the Direct Editor.
6. | Create a message loop in your script for the custom dialog. The message loop repeatedly calls the function WaitOnDialog, which returns the numeric control ID for the control with which user interacts with. A typical message loop appears as follows. |
7. | When the end user exits the dialog by clicking Back or Next, you should remove the dialog from the screen and from memory using EndDialog and ReleaseDialog: |
Note: For information on implementing dialog control functionality, see Using InstallScript to Process Dialog Controls.
• | Immediately before the dialog is displayed on the screen, WaitOnDialog returns the message constant DLG_INIT. In the DLG_INIT case statement, you can set the default states of check boxes and radio buttons, populate and set the current selection in a list box or combo box control, or set the initial text of an edit field. |
• | If an error occurs, WaitOnDialog returns the constant DLG_ERR. |
InstallShield 2015 Help LibraryJune 2015 | Copyright Information | Contact Us |
• | OnBegin |
• | OnMoving |
• | OnMoved |
• | OnEnd |
1. | Open the upgraded project in InstallShield 2016. |
2. | Make the appropriate changes to your InstallScript file: |
a. | In the View List under Behavior and Logic, click InstallScript. |
b. | Find the OnBegin, OnMoving, OnMoved, and OnEnd event handler functions in your script. You can quickly find a function by clicking the function name in the center pane of the view. |
c. | Rename the functions to an alternate name to avoid conflicts with existing function prototypes automatically included in ifx.h. For example: |
• | MyOnBegin |
• | MyOnMoving |
• | MyOnMoved |
• | MyOnEnd |
d. | Update the existing functions to take a single HWND parameter. For example: |
e. | Add appropriate prototypes for these new functions: |
3. | Add InstallScript custom actions that call your renamed InstallScript event handler functions: |
a. | In the View List under Behavior and Logic, click Custom Actions and Sequences (in Basic MSI projects) or Custom Actions (in merge module projects). |
b. | In the center pane, right-click the Custom Actions explorer and then click New InstallScript. InstallShield adds an InstallScript custom action. |
c. | Type a name for the custom action; use the same name that you used to rename the InstallScript functions. For example: |
• | MyOnBegin |
• | MyOnMoving |
• | MyOnMoved |
• | MyOnEnd |
d. | Select the new InstallScript custom action that you created. |
e. | Set the Function Name setting to the name of the InstallScript function. |
f. | For the In-Script Execution setting, specify the value that is indicated in the table below. |
4. | Schedule the InstallScript custom action for the appropriate part of the installation: |
a. | In the View List under Behavior and Logic, click Custom Actions and Sequences. |
b. | Right-click the action or dialog that you want your InstallScript custom action to follow and click Insert. The Insert Action dialog box opens, providing a list of all the actions and dialogs that are currently associated with your project. |
c. | Select the InstallScript custom action that you created. If appropriate, enter a condition in the Condition box for launching the InstallScript event. |
d. | Click OK. |
Custom Action | In-Script Execution | Location in the Sequence |
MyOnBegin | Immediate (default) | One of the first actions in the Installation User Interface sequence. |
MyOnMoving | Deferred in system context | In the Installation Execution sequence, between the InstallInitialize and AllocateRegistrySpace actions. |
MyOnMoved | Deferred in system context | In the Installation Execute sequence, between the ScheduleReboot and InstallFinalize actions. |
MyOnEnd | Immediate (default) | The last event in the Installation Execute sequence after the InstallFinalize action. (In previous releases, OnEnd was called after all other events as a result of the installation completing.) |
• | Global variables and pointers are no longer maintained between individual InstallScript custom action calls. In addition, each InstallScript custom action initializes and uses its own individual SUPPORTDIR. Therefore, you cannot share information across individual calls using files in SUPPORTDIR. For more information, see Global Variables, Global Pointers, and SUPPORTDIR. |
• | Most Windows Installer properties are not available to deferred, commit, and rollback InstallScript custom actions. For more information, see Windows Installer Properties and Deferred, Commit, and Rollback InstallScript Custom Actions. |
InstallShield 2016 Help LibraryAugust 2016 | Copyright Information | Flexera Software |