PlaceBitmap

InstallShield 2018 » InstallScript Language Reference

Project • This information applies to the following project types:

•

InstallScript

•

InstallScript MSI

The PlaceBitmap function inserts an image into the installation window. The image source is specified by szName; it can be a bitmap file (.bmp), metafile (.wmf file), or dynamic link library (.dll).

Syntax

PlaceBitmap ( szName, nID_BITMAP, nDx, nDy, nDrawOp );

Parameters

PlaceBitmap Parameters

Parameter

Description

szName

Specifies the fully qualified name of the bitmap file (.bmp), metafile (.wmf file), or dynamic link library (.dll) of the image to be displayed. InstallShield recognizes bitmap files and metafiles by their file extension. Bitmap files must have the extension .bmp. Metafiles must have the extension .wmf. Dynamic link libraries must have the extension .dll. If a file name is specified with no extension, InstallShield assumes the extension .dll.

To specify an alternate transparent color, place a semicolon after the file name and follow it with a set of RGB color values. (RGB color is specified with three numeric values, separated by commas.) That color is then used as the transparent color for the bitmap specified by szName. Note that it does not affect bitmaps that are already displayed; nor does it become the default transparent color for bitmaps displayed by subsequent calls to PlaceBitmap.

The parameter below specifies white as the transparent color:

SUPPORTDIR ^ "Bitmap.bmp;255,255,255" When nDrawOptions is set to REMOVE, this parameter is ignored.

nID_BITMAP

Specifies the bitmap's resource ID if the bitmap resides in a .dll. If the bitmap source is a metafile or bitmap file, specifies a value that is not in use for an image currently on display; images that are displayed simultaneously must have unique ID numbers. When nDrawOptions is set to REMOVE, this parameter must contain the ID of a displayed image.

nDx

Pass either a number or the CENTERED constant in this parameter:

•

Pass a number to specify the horizontal distance in pixels between the edge of installation window and the edge of the image when nDrawOp is set to LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, or UPPER_RIGHT.

•

Pass the CENTERED constant to center the image on the horizontal axis when nDrawOp is set to LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, or UPPER_RIGHT. The image will be offset from the upper or lower edge of the installation window by the number of pixels specified in nDy. Since the CENTERED constant — when passed in nDx — centers the image horizontally, the argument in nDrawOp will affect only the vertical placement of the image.

nDy

Pass either a number or the CENTERED constant in this parameter:

•

Pass a number to specify the vertical distance in pixels between the edge of installation window and the edge of the image when nDrawOp is set to LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, or UPPER_RIGHT.

•

Pass the CENTERED constant to center the image on the vertical axis when nDrawOp is set to LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, or UPPER_RIGHT. The image will be offset from the right or left edge of the installation window by the number of pixels specified in nDx. Since the CENTERED constant — when passed in nDy — centers the image vertically, the argument in nDrawOp will affect only the horizontal placement of the image.

Note • You can pass the CENTERED constant in both the nDx and nDy parameters to center the image in the installation window. This is equivalent to passing the CENTERED constant in the nDrawOp parameter.

nDrawOp

Specifies the bitmap's placement location, sets placement options, or removes a previously placed bitmap. Pass one of the following predefined constants in this parameter:

•

BITMAPICON—Indicates that the bitmap has transparent parts. You can use the bitwise OR operator ( | ) to combine this constant with any of the other constants except TILED, FULLSCREEN or FULLSCREENSIZE. When BITMAPICON is ORed with one of those constants, the bitwise operation is ignored and BITMAPICON is used.

BITMAPICON has no effect when szName specifies a metafile or a 24-bit bitmap. Note that when you specify BITMAPICON, the bitmap is displayed normally, even if a special effect has been enabled with SetDisplayEffect.

•

TILED—The bitmap is tiled across the main installation window. This constant is normally used to create an installation background. When this constant is specified, location options are ignored and the bitmap is displayed normally, even if a special effect has been enabled with SetDisplayEffect.

•

FULLSCREEN—Draw the image to fill the entire installation window. The image is not resized when its drawn. If a bitmap image is smaller than the InstallShield main window, it is centered in the window and the background is filled with the current background color. The default value is teal; it can be changed using the SetColor function. When this constant is specified, location options are ignored and the bitmap is displayed normally, even if a special effect has been enabled with SetDisplayEffect.

•

FULLSCREENSIZE—Draw and stretch the image to fill the entire installation window. When this constant is specified, location options are ignored and the bitmap is displayed normally, even if a special effect has been enabled with SetDisplayEffect.

nDrawOp (continued)

•

CENTERED—Places the bitmap in the center of the installation window.

•

LOWER_LEFT—Places the bitmap in the lower left corner of the InstallShield installation window.

•

LOWER_RIGHT—Places the bitmap in the lower right corner of the InstallShield installation window.

•

UPPER_LEFT—Places the bitmap in the upper left corner of the InstallShield installation window.

•

UPPER_RIGHT—Places the bitmap in the upper right corner of the InstallShield installation window.

•

REMOVE—Removes a previously placed bitmap or metafile. Any special display effects that have been enabled with SetDisplayEffect are ignored.

Return Values

PlaceBitmap Return Values
Return Value	Description
0	Indicates that the function successfully found and placed the image.
< 0	Indicates that the function was unable to find or place the image.

Comments

InstallShield supports 2-color, 16-color, 256-color and true color (24-bit) bitmaps. Two-color, 16-color and 256-color bitmaps can have transparent portions.

Transparent bitmaps are useful for displaying images that appear to be integrated with the background window. Pixels in the bitmap that match a specified transparent color are not displayed; the background pixel at that location remains visible. In setups, transparent bitmaps that incorporate the company name and its logo in an artful design are often used as titles in the installation window.

To specify a transparent bitmap, you must pass the constant BITMAPICON in the parameter nDrawOp. You must also consider which color in the bitmap is to be transparent. The default transparent color is purple (RGB(255,0,255)). To specify a different transparent color, use the parameter szName as described below.

Because metafiles are drawn rather than placed, they are intrinsically transparent. If BITMAPICON is specified for a metafile, that parameter is ignored.

Note • Many special display effects are available for non-transparent bitmaps by using the SetDisplayEffect function. That function also provides limited display effects for metafiles.

The location of the bitmap within the window can be specified in one of two ways:

•

By passing one of the location constants in the parameter nDrawOp.

•

By passing a vertical and horizontal offset from the edge of the installation window in nDx and nDy.

•

By passing the CENTERED constant in either nDx or nDy in combination with a horizontal or vertical offset.

Always remove any bitmaps or metafiles that are no longer needed by calling PlaceBitmap with the constant REMOVE as the parameter nDrawOp. Removing an unneeded bitmap is recommended even if another bitmap covers that bitmap completely because the palette entries for the first bitmap will not be released until the bitmap is removed.

Tip • A true color bitmap that is displayed on a system running in 16-color or 256-color mode will use only those colors available in the color palette; no additional colors will be allocated for the bitmap, even when additional color palette entries are available. If you anticipate that a setup with 24-bit bitmaps will be run on 16- or 256-color systems, include 16- or 256-color versions of the bitmaps. Then call GetSystemInfo with the COLORS parameter to determine the current color mode before selecting the bitmap to display.

Call SetDisplayEffect to set special effects for non-tiled, full-screen, transparent bitmaps; you can also set limited special effects for metafiles.

InstallShield does not support 24-bit transparent bitmaps. If you include a transparent color in a 24-bit bitmap and specify the BITMAPICON constant, the color will be displayed normally.

When you place a 256-color bitmap on a system running in 256-color mode, InstallShield attempts to allocate the bitmap's color palette into the system color palette. If multiple 256-color bitmaps are placed, InstallShield attempts to merge the color palettes of all visible bitmaps into the system color palette, giving precedence to the most recently placed bitmap. This behavior may cause previously placed bitmaps to change colors when additional bitmaps are displayed.

On a system running in 256-color mode with a 256-color dithered background, bitmaps that include many colors may cause some of the color palette entries used for the background to be reallocated; this can cause a gradient effect to appear in the background. Setups with bitmaps that use many colors should not use a 256-color gradient background if they will run on 256-color systems.

System color palettes exist only on systems that are running in 256-color mode. Systems running in high color (16-bit) or true color (24-bit) modes and systems running under in 65535 (16-bit) color mode do not have a system color palette. On these systems there are no color palette handling issues to consider; colors are displayed directly using the RGB color value. See Preventing Color Distortion for more information.

Because metafiles are rendered, they do not include a custom color palette. When a metafile is displayed on a 256-color system, no color palette handling takes place; the metafile is drawn with the colors currently available in the color palette. For that reason, you should not use metafiles that display colors other than the standard 16 colors in setups that will run on 256-color systems.

PlaceBitmap

InstallShield 2018 Help Library

September 2018