SdFeatureDialog2

InstallShield 2014 » InstallScript Language Reference

Project: This information applies to the following project types:

InstallScript
InstallScript MSI

The SdFeatureDialog2 function creates a dialog that displays the following:

A list of features that the end user can install.
The space required for the selected features and the space that is available in the destination location. A feature’s size is displayed as the number 0 until it is selected. When the feature is selected, its actual size is displayed.
A description of the selected feature—the value of the feature’s Description setting.

If a particular feature has subfeatures, the Change button becomes active when the end user clicks the feature. Clicking the Change button launches the Select Subfeatures dialog, where the end user can make further selections.

Syntax

SdFeatureDialog2 ( szTitle, szMsg, szDir, szFeatures );

Parameters

SdFeatureDialog2 Parameters

Parameter

Description

szTitle

Specifies the title of the dialog. To display the default title (“Select Features”), pass a null string ("") in this parameter.

szMsg

Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter.

szDir

Specifies the name of the folder to be selected by default and returns the name of the folder selected by the end user. The destination folder specified by szDir is not assigned automatically to INSTALLDIR, TARGETDIR, or any other system variable. To apply the value of szDir to the installation, you must assign it to INSTALLDIR (in an InstallScript MSI installation), TARGETDIR (in an InstallScript installation), or to a script-defined variable, if one is in use.

If the default folder specified by szDir does not already exist on the end user’s system, it is not created unless the end user clicks the Browse button and follows the steps to create it from the Choose Folder dialog. Therefore, whenever you specify a default folder, you must call ExistsDir when FeatureDialog returns in order to determine whether that folder exists. If it does not exist, call CreateDir to create it on the end user’s system.

szFeatures

Specifies the name of the feature whose subfeatures are displayed. To display all top-level features, pass a null string ("") in this parameter. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls.

SdFeatureDialog2 searches for the requested features in the script-created feature set specified by the system variable MEDIA; see the Additional Information section.

Return Values

SdFeatureDialog2 Return Values

Return Value

Description

NEXT (1)

Indicates that the end user clicked the Next button.

BACK (12)

Indicates that the end user clicked the Back button.

Additional Information

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.
Default selection settings are cleared when the end user selects a feature or subfeature displayed in the dialog. If the end user clears a feature selection, all of its subfeatures are cleared. Conversely, if the end user clears all of a feature’s subfeature selections, the feature’s selection is cleared.

When a feature is not selected by default, its subfeatures are not selected by default. If all subfeatures of a feature are not selected by default, the parent feature should not be selected by default. For information on default feature and subfeature selection settings, see FeatureAddItem.

A feature’s size is displayed as the number 0 until it is selected. Once it has been selected, its actual size is displayed.
The required disk space displayed by the dialog includes the size of the files that must be installed to enable maintenance setups and uninstallation. Even if all application components are deselected, the size of these files is still displayed.
If your installation does not use a setup type dialog, you must call FeatureSetupTypeSet to specify a setup type that has been defined in the Setup Types view before calling SdFeatureDialog2.
SdFeatureDialog2 operates on the current media, which is specified by the system variable MEDIA. During setup initialization, the installation assigns to MEDIA a media name that is associated with your file media library (Data1.cab).

To display script-created features:

1. Save the current value of MEDIA in a string variable, for example, szSaveMEDIAValue.
2. Assign to MEDIA the name of the script-created component set.
3. Call SdFeatureDialog2 to get end-user selections.
4. Assign to MEDIA the value that you saved in step 1. You must do this before calling FeatureTransferData.
If necessary, feature names are truncated to allow the display of the largest possible feature size. The space required to display the size depends on the maximum feature size (2 GB), the feature size options currently in use, and the font used to display feature information in the dialog. Feature size options are set with the DialogSetInfo function.

When the space required to display the maximum possible size has been determined, all feature names are truncated automatically, if necessary, to fit the remaining space. The name of a feature that requires less space to display its size (or that is not selected) may still be truncated under this method. To maximize performance and ensure that feature names appear complete, make feature names or display names smaller than the space available in the dialog.

The Select Subfeatures dialog cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

See Also