SprintfBox

InstallShield 2014 » InstallScript Language Reference

Project: This information applies to the following project types:

•

Basic MSI

•

InstallScript

•

InstallScript MSI

The SprintfBox function presents a message box containing one of three icons, a title, and a formatted message. The message can contain variables that are formatted according to commands that you enter.

SprintfBox is similar to MessageBox, but SprintfBox permits much more flexible control over displayed items.

Caution: Multiple null-delimited strings should not be used, except for passing to external functionality.

The SprintfBox function uses the Microsoft Windows API MessageBox to create the message box. The operating environment, not InstallShield, determines the size and location of the message box. The operating environment also generates the text for the OK button in the local language (the language that the operating system is running under). You cannot change the text in this button. For more information regarding the use of Windows MessageBox types, consult the description of the MessageBox Windows API function in the appropriate Windows SDK.

Note the following when using Windows message box constants:

•

Some Windows MessageBox type constants are predefined in the ISRTWindows.h file that is provided in the InstallShield Program Files Folder\Script\Isrt\Include folder. This file is automatically included in your installation when you include Ifx.h in your script. You do not need to redefine any constants that are defined in ISRTWindows.h; doing so will result in a compiler warning. To determine which constants are predefined, refer to the ISRTWindows.h file.

•

To use constants that are not defined in ISRTWindows.h, you must define them (using #define) in the declaration block of your installation script. You cannot simply include the Windows.h file that is usually part of a C++ program. The values that you need to assign to the undefined constants can generally be found in an include file that is provided with the appropriate Windows SDK or development tool. (For Microsoft Visual C++, most constants can be found in the Winuser.h file, which is located in the InstallShield Program Files Folder\Script\Resource folder.)

•

Windows and InstallShield message box constants cannot be used together in an installation. If an InstallShield message box constant is combined with a Windows message box constant using the OR operator (|), the Windows message box constant is ignored.

•

Some Windows message box styles are not supported on some Windows platforms. To determine whether a particular style is supported on the operating systems targeted by the installation, consult the appropriate Windows SDK.

Syntax

SprintfBox ( nType, szTitle, szFormat [,arg] [,...] );

Parameters

SprintfBox Parameters

Parameter

Description

nType

Specifies the type of icon to display in the message box. Pass one of the following predefined constants in this parameter:

•

INFORMATION

•

WARNING

•

SEVERE

Advanced developers familiar with the Windows APIs can specify any style of message box by using the native message box style constants in the parameter nType. See the description for the MessageBox or WinMessageBox API in the programming manual for your operating environment. If you are using any of the native message box styles, the InstallShield SprintfBox function returns the return value from the Windows API. Therefore, you must use the Windows API return values in your script.

For example, if you pass YES|NO|CANCEL as the first parameter, the SprintfBox message box has Yes, No, and Cancel buttons. The respective button return values, as defined by the Windows API MessageBox, are 6 (IDYES), 7 (IDNO), and 2 (IDCANCEL). You must use the appropriate constant values in your script, either as number literals, or as constants defined as the number literals in the declare block of your script.

Tip: Advanced developers can use MB_STYLE directly as the first parameter of the SprintfBox function to replace the constants SEVERE, WARNING, or INFORMATION. The value of MB_STYLE is listed in the Windows.h file. You can either enter the value directly in the parameter nType, or you can use the #define preprocessor directive to define the constants associated with the value.

szTitle

Specifies the title of the message box. To display the default title Error, pass a null string ("") in this parameter.

szFormat

Specifies a string that includes a format specifier for each argument to be included in the message.

arg

Specifies up to 10 arguments to be included in the message. There must be one argument for each format specifier in the message; the type of each argument must match the type of its respective format specifier. SprintfBox generates a compiler error or fails at run time under the following conditions:

•

More than 10 format specifiers and arguments are specified: compiler error.

•

The number of arguments does not match the number of format specifiers. When a specifier does not have a corresponding argument, the resulting string contains unpredictable characters in the specifier's position. When there are more arguments than specifiers, the excess arguments are not inserted into the resulting string.

•

A variable does not match the type of its respective format specifier.

•

A character itself is passed, rather than its numeric ASCII value or the return from the STRTOCHAR function, with the format specifier %c.

Return Values

The return value is not significant unless you are using standard Microsoft Windows message box styles. If you are using these styles, the return value is the same as the return value from the MessageBox API functions.

Additional Information

The dialog that is displayed by the SprintfBox function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

SprintfBox

InstallShield 2014 Help Library

May 2014