DialogSetInfo

InstallShield 2014 » InstallScript Language Reference

Edition: This information applies to the following project types:

•

InstallScript

•

InstallScript MSI (in event-driven InstallScript—not in InstallScript custom actions)

The DialogSetInfo function changes the following display elements in run-time dialogs:

•

The image to be displayed

•

The style of the check boxes used to obtain end-user selections

•

The precision of the values that indicate available hard drive space

You must call DialogSetInfo each time that you want to change a particular aspect of a single dialog. Changes that are made by a call to DialogSetInfo remain in effect for the remainder of the installation or until they are changed again by a subsequent call to DialogSetInfo.

Note: If your script calls DialogSetInfo before calling any of the Sd dialog functions, the call to DialogSetInfo must be preceded by a call to SdInit. If it is not, the call to DialogSetInfo has no effect.

Syntax

DialogSetInfo ( nInfoType, szInfoString, nParameter );

Parameters

DialogSetInfo Parameters

Parameter

Description

nInfoType

Specifies the display feature to be modified. Pass one of the following predefined constants in this parameter:

•

DLG_INFO_USEDECIMAL—By default, the values displayed to indicate feature sizes, available disk space, and required disk space are rounded to the nearest kilobyte or megabyte. Pass this constant when you want these values displayed to the nearest tenth of a kilobyte or megabyte. The following dialogs are affected by this parameter: FeatureDialog, SdFeatureDialog, SdFeatureDialog2, SdFeatureDialogAdv, and SdFeatureMult.

•

DLG_INFO_KUNITS—By default, the values displayed to indicate feature sizes, available disk space, and required disk space are displayed as a measurement in megabytes. Pass this constant to display these measurements in kilobytes. The following dialogs are affected by this parameter: FeatureDialog, SdFeatureDialog, SdFeatureDialog2, SdFeatureDialogAdv, and SdFeatureMult.

•

DLG_INFO_ALTIMAGE—Specifies an alternate bitmap to be displayed in the dialog. If nParameter is set to DLG_INFO_ALTIMAGE_VERIFY_BMP or TRUE, szInfoString should specify the image to be displayed in the dialog. This parameter applies to all dialogs that display the standard installation image on the left side of the dialog. For more information, see the nParameter description.

Display effects that have been set with SetDisplayEffect do not apply to alternate images, which are always displayed without any special effects.

•

DLG_INFO_CHECKSELECTION—Specifies that the selection method will be determined by the constant passed to nParameter.

Note: You can use the DLG_INFO_ALTIMAGE parameter to enable a 16-color, 256-color, or true color (24-bit) bitmap. Note that color distortion may occur when a 256-color bitmap is displayed on a 16-color system or when a true color bitmap is displayed on a 256-color system. It is recommended that you specify an alternate image that is compatible with the color mode of the target system.

szInfoString

When DLG_INFO_ALTIMAGE is passed in nInfoType, this parameter specifies the file name of an alternate bitmap to display and, optionally, a set of bitmap attributes. If bitmap attributes are included, the string passed in this parameter should be formatted as follows:

"bitmap file name;transparent flag;3-D flag;<unused>;background color"

•

Bitmap file name—Specifies the name of the bitmap file. If the file name is unqualified (that is, if it does not include a drive designation and path), the installation searches for the bitmap in SUPPORTDIR.

•

Transparent flag—Indicates whether to display the bitmap transparently. When this flag is 1 (true), all portions of the bitmap that are magenta (RGB Value: 255,0,255) will be displayed transparently. The default for this parameter is 0 (non-transparent).

•

3-D flag—Indicates whether to add a 3-D border around the edges of the static field that contains the bitmap. The default for this parameter is 0 (no 3D border).

•

<unused>—This portion of the formatted string is ignored, but it must be included. That is, the formatted string must contain four semicolons, with two semicolons between the 3-D flag and the background color.

•

Background color—Indicates the color to use for the background of the static text field. Note that this color will be visible only if the bitmap is smaller than the static text field in which it appears or if the transparent flag is set to 1 and the bitmap has transparent areas. The background color must be expressed as an RGB value, that is, as three numeric values separated by commas.

The following example will display the bitmap from the file MyBitmap.bmp, which is located in the SUPPORTDIR folder. The bitmap is placed on a black background and has a three-dimensional border. Any parts of the bitmap that are magenta are displayed in the background color of black.

SUPPORTDIR ^ "MyBitmap.bmp" + ";1;1;;0,0,0"

Note that the standard bitmap measures 57 x 53. An alternate bitmap should be about this size as well. If the bitmap is larger than this size, it will be centered vertically within the title area, and the right side of the bitmap will be aligned with the right side of the dialog. (In the Welcome, SdWelcome, and SdFinish dialogs, the right side of the bitmap will be aligned with the right side of the larger image within which the bitmap appears.) The left side of the bitmap will extend as far to the left of the dialog as necessary. Any part of the bitmap that extends below the title area of the dialog will be clipped. If the bitmap is smaller than 57 x 53 it will be will displayed correctly, but it will not be resized or extended.

This parameter is ignored when the default bitmap is being restored or when nInfoType is not DLG_INFO_ALTIMAGE.

nParameter

Operates in conjunction with nInfoType to specify dialog features.

When nInfoType is DLG_INFO_CHECKSELECTION, pass one of the following predefined constants to specify check box style:

•

CHECKBOX—Specifies Windows 3.1-style check boxes.

•

CHECKBOX95—Specifies Windows 95-style check boxes.

•

CHECKLINE—Specifies checkline-style check boxes.

•

CHECKMARK—Specifies checkmark-style check boxes.

When nInfoType is DLG_INFO_ALTIMAGE, pass one of the following predefined constants to specify which bitmap to display:

•

DLG_INFO_ALTIMAGE_VERIFY_BMP—Specifies that the bitmap that is indicated by szInfoString should be used in subsequent dialogs. Before this bitmap is used, the installation checks for the existence of the bitmap.

•

DLG_INFO_ALTIMAGE_REVERT_IMAGE (-1)—Specifies that subsequent dialogs should display the default bitmap. The installation does not check for the existence of a bitmap.

•

TRUE—Specifies that the bitmap that is indicated by szInfoString should be used in subsequent dialogs. The installation does not check for the existence of the bitmap.

When nInfoType is either DLG_INFO_KUNITS or DLG_INFO_USEDECIMAL, pass one of the following predefined constants to specify how sizes should be displayed:

•

TRUE—Specifies that sizes should be displayed as indicated by nInfoType.

•

FALSE—Specifies that sizes should be displayed in the default style.

Return Values

DialogSetInfo Return Values
Return Value	Description
ISERR_SUCCESS (0)	The function successfully set the specified style. If DLG_INFO_ALTIMAGE_VERIFY_BMP was passed in nParameter, this return value also indicates that the bitmap was found.
< ISERR_SUCCESS (< 0)	An unspecified error occurred when the function attempted to set the dialog information.
ISERR_FILE_NOT_FOUND (0x80070004)	The bitmap that was indicated by szInfoString was not found.

Additional Information

To preview the effects of a call to DialogSetInfo in an InstallScript installation, run the Dialog Sampler (which is available from the Tools menu’s InstallScript submenu), change the attributes of the dialogs (by clicking the Attributes button), then examine the changes in dialogs such as SdFeatureMult.

DialogSetInfo

InstallShield 2014 Help Library

May 2014