HandlerEx

InstallShield 2016 » InstallScript Language Reference

The HandlerEx function creates custom handlers for events such as the Help accelerator key (F1) and the Cancel button.

If the end user presses the F1 key, the currently defined HELP handler is executed. If the user presses the Cancel button, the currently defined EXIT handler is executed. If you have not defined custom HELP or EXIT handlers using the HandlerEx function, the default handlers are executed. The default EXIT handler displays the Exit dialog. The default HELP handler does nothing.

To execute custom handlers defined using HandlerEx, the InstallScript engine calls a unique label that is specified in the parameter Label when the nObject event occurs. When the InstallScript engine reaches a return statement in the handler code (under the label), control returns to the statement that would have executed next if the handler label were not called.

Using HandlerEx, you can specify custom handling of EXIT or HELP. You can display the MessageBox, SprintfBox, and AskYesNo dialogs inside Exit handlers; however, you cannot display Sd dialogs.

Syntax

HandlerEx (nObject, Label);

Parameters

HandlerEx Parameters

Parameter

Description

nObject

Specifies the event to trap. Pass one of the following predefined constants in this parameter:

•

EXIT—Specifies that a custom handler is called when the Cancel button is pressed. If you do not define a handler, a default Exit dialog appears when the Cancel button is pressed.

•

HELP—Specifies that a custom handler is called when the F1 accelerator key is pressed. If you do not define a handler, nothing happens when the F1 accelerator key is pressed.

Label

Specifies the name of the label to which the program should jump if the specified button or accelerator key is pressed. Do not define this label as a numeric value or as a string variable.

To cancel a currently defined handler and reinstall the default handler, pass -1 in this parameter. This method is useful in scripts that install a custom handler only for certain processes and then revert to the default handler.

Caution • Do not define the label name as a numeric value or as a string variable.

Return Values

HandlerEx Return Values
Return Value	Description
0	HandlerEx successfully created the handle.
< 0	HandlerEx was unable to create the handle.

Additional Information

•

The only accelerator available is the F1 function key (Help).

•

Help (F1) allows you to launch the help engine or provide other suitable help. When the end user presses the F1 key, the InstallScript engine calls the currently defined Help handler. You can provide any type of help functionality in the Help handler. If you want to provide context-sensitive help, you must keep track of the context in your script.

For example, you can have a string variable that contains a current context string. You can then use that string variable in a switch-case statement inside the Help handler to execute the appropriate Help events based on the value of the context string. You can also test the value of the nSdDialog global variable in your Help handling routine. nSdDialog is set to the dialog ID (as described in _isres.h in the InstallShield Program Files Folder\Script\Isrt\Include folder) of the currently executing Sd dialog. (When no Sd dialog is executing, nSdDialog is not defined.) You can therefore give the user access to Sd dialog-specific help when an Sd dialog is executing.

•

As with Help handlers, you can also define and execute custom and Sd dialog-specific EXIT handlers.

HandlerEx

InstallShield 2016 Help Library

May 2017