Creating the Object’s Run-Time User Interface

InstallShield 2024

Project: This information applies to the InstallScript Object projects.

Your object can display a dialog sequence to end users of an installation that includes the object. To define this dialog sequence, use the object script’s UI event handlers—OnFirstUIBefore, OnFirstUIAfter, OnMaintUIBefore, and OnMaintUIAfter. (By default, these handlers do not display any dialogs in an object project.)

In a project containing objects with dialog sequences, you have two alternatives for displaying the objects’ dialogs:

•

Show all object dialog sequences at one point in the project by calling the ShowObjWizardPages function.

•

Show each object’s dialog sequence whenever you choose by calling any or all of the object’s ShowxxxxxUIyyyyy methods (that is, ShowFirstUIBefore, ShowFirstUIAfter, ShowMaintUIBefore, and ShowMaintUIAfter).

The ShowObjWizardPages Function

The ShowObjWizardPages function is called by default in each UI event handler of an InstallScript installation project created with InstallShield X, InstallShield DevStudio, or InstallShield Professional 6.1 or later; you can study the use of this function in the default event handlers as a guideline. Calling ShowObjWizardPages in a project’s UI event handler displays each included object’s corresponding UI code. For example, calling ShowObjWizardPages in a project’s OnFirstUIBefore event handler displays each included object’s OnFirstUIBefore code. The included objects’ UI event handlers are executed in the order in which the objects appear in the project’s Components view.

The end user should be able to advance through the installation’s entire dialog sequence by using the Next and Back buttons. To allow this, do what is done in the default UI event handler code: assign each dialog function’s return value (NEXT or BACK) to the variable nResult, and call ShowObjWizardPages as follows:

nResult = ShowObjWizardPages(nResult);

The ShowxxxxxUIyyyyy Methods

All user-created objects internally support the methods ShowFirstUIBefore, ShowFirstUIAfter, ShowMaintUIBefore, and ShowMaintUIAfter. When you call an object’s ShowxxxxxUIyyyyy method, the object’s corresponding UI code is executed. For example, the following call executes the object’s OnFirstUIBefore code:

nResult = oObject.ShowFirstUIBefore(nResult);

 

As with the ShowObjWizardPages function, enable end-user navigation by assigning each dialog function’s return value to nResult, and calling ShowxxxxxUIyyyyy methods as in the preceding example.

Object UI Event Handler Code

Create object UI event handler code by modifying the default code. This default code, although it does not display any dialogs, contains the code structure that is necessary to enable end-user navigation.

•

To display a single dialog, place the dialog function call immediately after either the FIRST_DIALOG or the LAST_DIALOG label.

•

To display two dialogs, place the first dialog function call immediately after the FIRST_DIALOG label and the last dialog function call immediately after the LAST_DIALOG label.

•

To display more than two dialogs, place the first dialog function call immediately after the FIRST_DIALOG label and the last dialog function call immediately after the LAST_DIALOG label. For each intermediate dialog, place the dialog function call in a code block structured like the FIRST_DIALOG and LAST_DIALOG blocks.

In each of the above cases, assign the return value from the dialog function call to the variable nDirection.