MessageBox action

The MessageBox action displays a Windows message box. It can be used to ask the user for confirmation, to display general messages, or to display error messages that terminate the installation. In addition to the standard Windows message box features, the InstallMate MessageBox action offers the following enhancements:

The message box result determines how the parent action sequence continues, as shown in the following table.

Notes

Result Effect on parent action sequence
OK, Yes, Close, Ignore, Continue Continues with the next action in the sequence.
No Exits the action sequence.
Cancel, Abort Exits the action sequence. If Fail mode (see below) is set to Fail if Cancel, then the installation is marked as failed.
Retry, Try Again Continues with the previous action in the sequence.

Attributes

The following attributes and options are available.

Attribute Description
Action name Enter the name of the action. This name is only used in InstallMate and is not visible to the user.
Message text Enter the localizable message text for the message box.
Localized Check this box to localize the Message text field and use different message texts for different languages.
Buttons

Select the desired message box buttons from the drop-down list; the message box result corresponds to the button that the user clicked (see table above). The following choices are available:

Buttons Description
OK Display only an OK button.
OK, Cancel Display an OK and a Cancel button.
Yes, No Display a Yes and a No button.
Yes, No, Cancel Display Yes, No, and Cancel buttons.
Retry, Cancel Display a Retry and a Cancel button.
Abort, Retry, Ignore Display Abort, Retry, and Ignore buttons.

Note: The message box buttons are automatically localized for the current installation language, so the actual buttons will show the localized equivalents of OK, Cancel, etc.

Default button

Select the button that must act as the default button from the drop-down list. The available choices refer to the buttons that you selected for the Buttons field, numbered in the order that the buttons appear in that field.

The default button is preselected when the message box appears. If the user presses the Enter key without selecting a different button first, then the default button determines the message box result.

Tip: The default button should be the one that returns the preferred or least dangerous result, because many users press Enter without really reading the message box.

Icon

Select the desired message box icon from the drop-down list. The following choices are available:

Icon Description
None Don't display an icon.
Information Display an "information" icon, typically a stylized i
Question Display a "question" icon, typically a stylized ?
Warning Display a "warning" icon, typically a stylized !
Error Display an "error" icon, typically a stylized X
Time out

Enter the time-out period for the message box in seconds. If the user doesn't close the message box within the time-out period, it will be closed automatically. In that case, the message box returns the default result as specified by Result (below).

  • If you leave this field empty or set it to 0 (zero) or a non-numerical value, then the default time-out period of 300 seconds will be used.
  • To disable the time-out period, enter a large unsigned 32-bit value, for example 0xFFFFFFFF. In that case, the message box will remain on the screen until the user dismisses it by clicking on a button.
Result

Select the default message box result from the drop-down list. The available choices correspond to the possible message box buttons and have the same effect on the execution of the parent action sequence (see table above). The default result is returned under the following circumstances:

  • If the installer is running in silent mode, the MessageBox action does not display the actual message box but immediately returns the default result.
  • If the installer is not running in silent mode but the user does not close the message box within the specified time-out period, then the message box is closed automatically and returns the default result.

Tip: The default result is usually one of the buttons that you selected under Buttons. However, this is not required; you may select a Result that is not among the buttons shown in the message box. This is useful if you want to return a different result for a message box that ends because of a time-out or was suppressed during a silent installation, than for one that is closed explicitly by the user.

For example, you could create a MessageBox action with Buttons set to OK and Result to Cancel, then select Fail mode (below) Fail if Cancel. This would terminate the installation if the message box timed out or if the installer runs in silent mode, but continue if the user was present and clicked OK to close the message box.

Fail mode

Select the desired installation failure mode for the action. The following choices are available:

Fail mode Description
Don't fail No failure behavior.
Fail if Cancel Mark the installation as failed if the message box returns Cancel or Abort, either because the user clicked one of those buttons, or because the default Result caused one of these values to be returned.
Fail if run Mark the installation as failed if the action is run at all. This option is mostly useful if the message box is used for a fatal error message and the execution of the MessageBox action is conditional upon some error condition specified in the Condition field (below).
If the MessageBox action fails, the parent action sequence is terminated and the installation is marked as failed. However, the latter only has an effect after the installer has executed the StartProcessing standard action and before EndProcessing. Outside that bracket (for example, in a user interface sequence that displays dialog boxes prior to starting the installation proper), the installation status is ignored.
Condition

Enter the conditional expression that determines if the action will be executed, or leave empty for unconditional execution.

Tip: You do not have to make the MessageBox action conditional upon a silent install (/q or /q2 command line option; TsuQuiet variable > 0); the message box is automatically suppressed if the installer runs in silent mode. Note that this differs from suppressing the action with a condition:

  • With the automatic silent install suppression Result is returned as the action result, which may affect the parent action sequence as documented above. Furthermore, depending on Fail mode, the installation as a whole may be marked as failed.
  • With a "false" condition, the action is not executed at all and has no effect on its parent action sequence or the installation.

The Condition field takes precedence over the silent install suppression, in that a "false" condition causes the action to be skipped altogether, for silent and interactive installs alike.

Disabled Check this box to disable the action. A disabled action is not included in the installer and not checked during the build. You can use this option to remove actions temporarily from your installer without permanently deleting them. Disabled actions are shown with a grayed-out icon.
Platforms... Click this button to open the Select Installation Platforms dialog box that allows you to select the Windows versions on which the action must be executed. This platform selection acts as an additional condition for the action.

Related topics

Actions, Dialogs, Working with attribute panes