DialogSetInfo

InstallShield 2018 » 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_ALTIMAGE_HIDPI—Specifies a high DPI image to be displayed in the dialog. High DPI image types supported include BMP, GIF, JPEG, PNG, and TIFF. For best results, in order to ensure the image is centered and shifted to the right of the header, use images with an aspect ratio of 2.5:1, similar to the images shipped with InstallShield (where the actual logo portion of the image is approximately half of the image width and the other half is transparent), and note the following image sizing recommendations:

•

For a 100% scaled image, your image should be 180x75

•

For a 200% scaled image, your image should be 360x150

•

For a 250% scaled image, your image should be 450x187, etc.

If transparency is required, image types that support transparency (such as PNG) should be used and szInfoString should specify the name of the image to be displayed (optionally including the path) in the dialog. This parameter applies to all dialogs that display the standard installation image on the left side of the dialog. When DLG_INFO_ALTIMAGE_HIDPI is passed in nInfoType, the following parameter values are expected: szInfoString and nParameter. For more information, see the szInfoString and nParameter descriptions.

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

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.

When DLG_INFO_ALTIMAGE_HIDPI is passed in nInfoType, this parameter specifies the file name of a high DPI image to display, optionally including the path. If no path to the file is specific, the file is assumed to be in SUPPORTDIR. If this file does not exist, DialogSetInfo returns ISERR_FILE_NOT_FOUND.

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

nParameter

Operates in conjunction with nInfoType to specify dialog features.

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 DLG_INFO_ALTIMAGE_HIDPI, nParameter specifies the DPI scaling percentage. For example, pass 200 for a 200% image scale, 150 for a 150% scale, etc. The minimum supported scaling value is 25. If 0 is passed for this value, no image is displayed. If DLG_INFO_ALTIMAGE_REVERT_IMAGE is passed, the previous image used is displayed.

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 image 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 2018 Help Library

September 2018