Most screens in install4j contain a configurable form. In these screens, you can configure a list of form components along the vertical axis of the form. install4j provides you with properties to control the initialization of form components and the way the user selection is bound to installer variables. With this facility you can easily generate good-looking installer screens that display arbitrary data to the user and request arbitrary information to be entered.

Most standard screens are built with form components and form templates are starting points for your own customizations. Also, you can add empty form screens and add form components to them. For screens that have a configurable form, a header is shown above the screen configuration that shows the number of contained form components as well as buttons for editing them and showing a preview of the form.

The actual configuration of the form components is performed in a separate dialog:

Screens can lay out the contained form in different ways, but for plain form screens, you can configure this with properties of the containing screen. By default, a form is top-aligned and fills the entire available horizontal space. For example, for a set of radio buttons that should be centered horizontally and vertically, the "Fill horizontal space" and "Fill vertical space" properties of the screen must be set to "false" and the horizontal and vertical anchor properties must be set to "Center".

Form components

install4j offers a large number of form components that represent most common components available in Java and some other special components that are useful in the context of an installer.

All components that expect user input have an optional leading label. The components themselves are left-aligned on the entire form. If you leave the label text empty, the form component will occupy the entire horizontal space of the form.

Every form component has configurable insets. For vertical gaps that are meant to separate groups of form components, consider using a "Vertical spacer" form component since it makes the grouping clearer and allows to to reorder form components more easily.

You can preview your form at any time with the Preview Form button. The preview dialog performs all variable replacements of compiler variables and custom localization keys, but not of installer variables. Also, no initialization scripts or screen activation scripts are run. The preview is intended to give you quick feedback about visual aspects of your form. At runtime, the look and feel may be different.

Every form component always has its preferred vertical height. For some form components such as the "List" form component, this preferred vertical size is configurable. If the vertical extent of the form exceeds the available vertical space, a scroll bar is shown. If you want such a form component to fill the entire available vertical space, you can select the "Fill vertical space" property for the form component and deselect the "Scrollable" property of the form screen. In that case, there will be no scroll bar for the form.

User input

If a form component can accept user input, you need some way to access the user selection afterwards. install4j saves user input for such form components to the installer variable whose name is specified in the "Variable name" property. That variable can then be used later on, for example in condition expressions for screens and actions.

If you have a checkbox that saves its user input to a variable called "userSelection", the condition expression

context.getBooleanVariable("userSelection")

will skip the screen or action for which that condition expression is used. The user selection in form components is written to the variables before the validation expression for the screen is called. If you have a text field that saves its input to the variable "fileName", the validation expression

Util.showOptionDialog("Do you really want to delete " + context.getVariable("fileName"),
    new String[] {"Yes", "No"}, JOptionPane.QUESTION_MESSAGE) == 0

used on the same screen will block the advance to the next screen if the user answers with "No".

The values of installer variables accommodate the general type java.lang.Object. Every form component saves its user input in its naturally corresponding data type, for example:

• For check boxes, the type java.lang.Boolean is used. For this special case the context offers the convenience method getBooleanVariable.
• For text fields, the type java.lang.String is used.
• For drop down lists the type java.lang.Integer is used to save the selected index.
• For date spinners, the type java.lang.Date is used.

The description of the value type for each form component that accepts user input is shown in the registry dialog when you select the form component.

Initialization

For each form component, install4j offers several properties that allow you to customize its initial state. However, you may want to access the properties of the underlying UI component or use a more complex logic for modifying the form component.

For this purpose, the "Initialization script" property is provided. Form components can expose a well-known component in the initialization script that allows you to perform these modifications. This so-called "configuration object" is usually contained in the form component itself. For example a "Check box" form component exposes a configurationObject parameter of type javax.swing.JCheckBox and a "Text field" form component exposes a javax.swing.JTextField.

As with actions and screens in general, the possibility that the user moves back and forth in the screen sequence presents a dilemma to install4j. Any form components that accepts user input has a configurable initial value and any form component can have an initialization script. This initialization is performed when the user enters the screen for the first time. Should this initialization be performed again when the user moves back and then enters the screen once again? Since install4j does not know, it initializes every form component only once by default. This policy can be changed with the "Reset initialization on previous" property for each form component.

Depending on factors such as the correct platform, user input in the previous screen or whether the installer runs in console mode, some form components may not be applicable and should be hidden. In the "Visibility script", you can detect such conditions and return false to hide the form components.