Using InstallScript to Process Dialog Controls

InstallShield 2019

Project • This information applies to the following project types:

InstallScript
InstallScript MSI

In InstallScript and InstallScript MSI installation projects, you use InstallScript to process the controls that you add to your custom dialogs.

Using Check Box Controls

In addition to handling button clicks, a custom dialog generally needs to be able to retrieve the end user’s selections in dialog controls such as check boxes.

Note • InstallShield has a standard dialog called AskOptions. This dialog displays up to nine check boxes or radio buttons, and therefore it is not necessary to create a custom dialog to display only check boxes to the end user.

As with push buttons, for each check box control that you add to a dialog, you generally add a #define statement to your script that assigns a symbolic name to the numeric control ID. For example, if you add a check box control to a custom dialog, the control’s numeric ID will appear in the Control Identifier property of the control. If the numeric ID is 1302, you would add the following line to your script.

#define MYCHECKBOX1 1302

For most types of controls, InstallScript defines CtrlGet and CtrlSet functions with which you can get or set the current state or data for a control. For example, you can get and set the current state of a check box control using CtrlGetState and CtrlSetState. In the DLG_INIT case of your dialog’s message loop, you can call CtrlSetState to set the initial selection state of the check box. The following code causes the check box to appear initially selected.

case DLG_INIT:

    // Initialize the back, next, and cancel button enable/disable states for this dialog

    // and replace %P, %VS, %VI with IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION,

    // and IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202.

    hwndDlg = CmdGetHwndDlg("CustomDialog");

    SdGeneralInit("CustomDialog", hwndDlg, 0, "");

    CtrlSetState("CustomDialog", MYCHECKBOX1, BUTTON_CHECKED);

Similarly, you can add the following code outside the dialog’s message loop to detect the final selection state of the check box.

nState = CtrlGetState("CustomDialog", MYCHECKBOX1);

if (nState = BUTTON_CHECKED) then

    // check box selected

else

    // check box unselected

endif;

Using Edit Fields

You can also add edit controls to a custom dialog, which allow the end user to enter a single line of text. InstallShield has standard dialogs called SdShowDlgEdit1, SdShowDlgEdit2, and SdShowDlgEdit3, which display one, two, or three edit fields in which the end user can enter text.

You can read the text stored in an Edit control with CtrlGetText. For example, to read the text from an Edit control with resource ID 10000 into a string variable called svEdit, you can use the following code:

CtrlGetText("CustomDialog", 10000, svEdit);

Similarly, you can set the initial text stored in an Edit control (in the DLG_INIT block of the message-loop’s switch statement) with CtrlSetText.

Tip • You can use the Password attribute of an edit control to hide the characters that the end user types into the edit field. You can use the Number attribute to allow the end user to enter only numbers in the edit field.

Using List Box and Combo Box Controls

List box and combo box controls need to be associated with a variable of type LIST. Before displaying the list box control, you should populate a string-list variable, and associate it with the list box or combo box control using CtrlSetList in the dialog’s DLG_INIT handler. (For a combo box control, you will usually set the Drop-Down List property to True, and set the Height property to the height of the drop-down-list portion of the control.)

To set the initial selection in a list box or combo box control, you can call CtrlSetCurSel in the dialog’s DLG_INIT handler; and to retrieve the user’s current selection call CtrlGetCurSel. For example, the following code populates a list variable with the drive letters of every available drive (using GetValidDrivesList), associates the list with a combo-box control, and then reads the end user’s selection from the combo box before exiting the dialog.

function NUMBER CustomDialog( )

  NUMBER nReturn;

  NUMBER nControl;

BOOL bDone;

       // variables for combo box list and current selection

  LIST listDrives;

  STRING svDrive;

begin

    nReturn = EzDefineDialog("CustomDialog", ISUSER, "CustomDialog", 0);

    

    bDone = FALSE;

    

    // create the list containing the combo box items

    listDrives = ListCreate(STRINGLIST);

    // fill the list with all available drive letters

    GetValidDrivesList(listDrives, -1, -1);

    

    while (!bDone)

    

    nControl = WaitOnDialog("CustomDialog");

    

    switch (nControl)

    

        case DLG_INIT:

            // Initialize the back, next, and cancel button enable/disable states

            // for this dialog and replace %P, %VS, %VI with IFX_PRODUCT_DISPLAY_NAME,

            // IFX_PRODUCT_DISPLAY_VERSION, and IFX_INSTALLED_DISPLAY_VERSION,

            // respectively, on control IDs 700-724 and 202.

            hwndDlg = CmdGetHwndDlg("CustomDialog");

            SdGeneralInit("CustomDialog", hwndDlg, 0, "");

            CtrlSetState("CustomDialog", MYCHECKBOX1, BUTTON_CHECKED);

            // associate the list with the combo box

            CtrlSetList("CustomDialog", MYCOMBOBOX1, listDrives);

            // get the first drive letter from the list...

            ListGetFirstString(listDrives, svDrive);

            // ...and make it the current selection

            CtrlSetCurSel("CustomDialog", MYCOMBOBOX1, svDrive);

        // ...cases for other controls...

    

    endswitch;

    

    endwhile;

    

    // get the end user's selection, and display it in a message box

    CtrlGetCurSel("CustomDialog", MYCOMBOBOX1, svDrive);

    MessageBox("You selected drive " + svDrive, INFORMATION);

    

    EndDialog("CustomDialog");

    ReleaseDialog("CustomDialog");

    

    return nReturn;

end;

List box and combo box controls have a Sorted property, which you can set to Yes to sort the contents of the list controls by the items’ display names.