RadioButtons User Interface Dialog Box
RadioButtons dialog boxes are used to present up to four mutually exclusive choices to a user and return the value of the selected choice during installation. Three RadioButtons dialog boxes are available: RadioButtons (2 buttons), RadioButtons (3 buttons), and RadioButtons (4 buttons). These three dialog boxes are identical except for the number of option (radio) buttons; each can be added only once for each deployment project.
The dialog boxes contain two, three, or four option buttons with associated labels, plus additional labels to present information to the user. The text for these labels is specified at design time in the Properties window. Additional properties are provided for each option button to set a default value and to set the default option button.
The following illustration shows a typical RadioButtons (2 buttons) dialog box, as it would appear during installation.
RadioButtons (2 buttons) dialog box
.gif "Deployment UI splash screen")
Properties
The following properties are available for the RadioButtons dialog box.
Property |
Description |
|---|---|
BannerBitmap |
Specifies a bitmap or JPEG image to be displayed in the banner area. In the above illustration, the default bitmap is shown. For more information, see BannerBitmap Property. |
BannerText |
Specifies the text to be displayed in the banner area. In the above illustration, this corresponds to "This is the banner text." |
BodyText |
Specifies the text to be displayed above the option buttons. In the above illustration, this corresponds to "This is the body text." |
Button1Label |
Specifies the text to be displayed next to the first option button. In the above illustration, this corresponds to "First option". |
Button1Value |
Specifies a value for the first option button. This is the value that will be returned by the ButtonProperty property if the first option button is selected. |
Button2Label |
Specifies the text to be displayed next to the second option button. In the above illustration, this corresponds to "Second option". |
Button2Value |
Specifies a value for the second option button. This is the value that will be returned by the ButtonProperty property if the second option button is selected. |
Button3Label |
Specifies the text to be displayed next to the third option button. Not available for the RadioButtons (2 buttons) dialog box. |
Button3Value |
Specifies a value for the third option button. This is the value that will be returned by the ButtonProperty property if the third option button is selected. Not available for the RadioButtons (2 buttons) dialog box. |
Button4Label |
Specifies the text to be displayed next to the fourth option button. Not available for the RadioButtons (2 buttons) or RadioButtons (3 buttons) dialog boxes. |
Button4Value |
Specifies a value for the fourth option button. This is the value that will be returned by the ButtonProperty property if the fourth option button is selected. Not available for the RadioButtons (2 buttons) or RadioButtons (3 buttons) dialog boxes. |
ButtonProperty |
Specifies a property name used to retrieve the value of the selected option button. This property can be used in conditions. For more information, see Conditional Deployment. |
DefaultValue |
Specifies which option button will initially be selected when the dialog box is displayed. |
Controlling the Appearance of the RadioButtons Dialog Box
Several properties control how the RadioButtons dialog box will appear to the user during installation.
The BannerBitmap property controls the image that appears in the upper right corner of the dialog box. The position and size of the image are fixed.
Tip
For a consistent user interface, the same image should be used for all dialog boxes in an installer.
The BannerText property controls the text that is displayed in the banner across the top of the dialog box. The position, size, and font size are fixed. The text will wrap but cannot be more than two lines.
The BodyText property controls the text that appears just below the banner portion of the dialog box. The position, size, and font size are fixed. The text will wrap but cannot be more than four lines.
The ButtonNLabel properties control the text in the option button labels. The position and font size are fixed, and the text will not wrap.
Tip
For dialog boxes that may be localized, allow extra space for the text expansion. A word in one language may translate into a much longer word in another language, causing the text to be cut off.
Retrieving User Choices with RadioButtons Dialog Box Properties
When the installer containing the RadioButtons dialog box is run, the user can choose an option; you can then use that choice to control another phase of installation.
For example, you might create a RadioButtons (2 buttons) dialog box that gives the user a choice of installing an optional file. In this case, you would set the Button1Label property to "Install optional file" and the Button2Label property to "Do not install optional file". You would leave the Button1Value and Button2Value properties at their default values of 1 and 2, respectively.
If you thought that users usually would not want to install the optional file, you could set the DefaultValue property to 2 so that it would be selected by default.
In the File System Editor, you would set the Condition property for the optional file to the default value of the ButtonProperty property (BUTTON2) plus the Button1Value property (1): BUTTON2=1.
During installation, the Condition property for the file will be evaluated. If the user selects the first option button, the ButtonProperty property will return the Button1Value and the file will be installed; otherwise, the condition will evaluate to false and the file will not be installed.
See Also
Concepts
Deployment and the Run-Time User Interface
Installation Dialog Box Restrictions