Configuring Form Components


Form components are configurable units that can be added to a form screen. In this chapter, the functionality and configuration options on the form components dialog are discussed, the underlying concepts are discussed in a different help topic.

Form elements are added by clicking the  Add button.

In the popup window you can select whether to add

You can preview a form screen with the  Preview button which is also available on the property page of a screen. For screens that embed forms, the preview may not show the actual screen. However, the layout of the form itself will be the same at runtime.

Properties of form components

Common properties of form components are:

Available form components

The following standard form components are available in install4j:

  Category: Action components

  Button

A standard button with an optional leading label. When the user clicks on the button, an action script is executed.

  Dark mode switcher

A button that switches between dark and light mode. If the current look and feel does not support switching between dark and light mode, the button is invisible.

  Hyperlink URL label

A label that displays a hyperlink. When the user clicks on the hyperlink, the appropriate action is performed, depending on the protocol of the URL.

  Hyperlink action label

A label that displays a hyperlink. When the user clicks on the hyperlink, an action script is executed

  Category: Labels and spacers

  Horizontal separator

A horizontal separator with an optional label.

  Key value pair label

A pair of labels. The first ('key') label aligns with other leading labels on the form, the second ('value') label consumes the remaining horizontal space,

  Label

A single label. It is left-aligned with leading labels from other form components and extends beyond other leading labels.

  Leading label

A form component that only has a leading label and no central component. This can also be used to create standalone help tooltips.

  Multi-line HTML label

A multi-line label that wraps text as needed and displays simple HTML. In particular you can include HTML links that open a browser.

  Multi-line label

A multi-line label that wraps text as needed.

  Spring

An invisible spring that can be used in horizontal and vertical layout groups to push subsequent components to the right or to the bottom

  Vertical spacer

An invisible vertical spacer of configurable height.

  Category: Option selectors

  Check box

A check box with an optional leading label. The user selection (Boolean.TRUE or Boolean.FALSE) is saved to a variable.

  Combo box

A combo box with an optional leading label. The user can enter arbitrary text into the combo box. The user selection (the selected item as a string) is saved to a variable.

  Drop-down list

A drop-down list with an optional leading label. The user selection (the selected index as a java.lang.Integer) is saved to a variable.

  List

A list with an optional leading label. The user selection (the selected indices) is saved to a variable.

  Radio button group

A number of radio buttons in a common button group with an optional leading label. The user selection (the selected index as a java.lang.Integer) is saved to a variable.

  Single radio button

A single radio button with an optional leading label. If selected, a specified string is saved to a variable. If you place multiple instances of this form component on a form screen and give them the same variable name, they will form a radio button group.

  Category: Sliders and spinners

  Slider

A slider with an optional leading label. The user input (a java.lang.Integer) is saved to a variable.

  Spinner of dates

A spinner with date and time values with an optional leading label. The user input is saved to a variable.

  Spinner of enumerated values

A spinner with enumerated values with an optional leading label. The user input is saved to a variable.

  Spinner of integer values

A spinner with integer values with an optional leading label. The user input is saved to a variable.

  Category: Special selectors and displays

  Directory chooser

A directory chooser with an optional leading label. The user selection is saved to a variable.

  File associations selector

A form component that displays a list of all subsequent file association actions and asks the user which associations should be made. This form component will be empty if there are no corresponding file association actions after this screen.

  File chooser

A file chooser with an optional leading label. The user selection is saved to a variable.

  HTML or text display

A scroll panel that displays HTML or plain text. The HTML or plain text is easily localizable because the file selection allows you to enter separate files for all supported languages.

  Installation components selector

A form component that displays all installation components and asks the user which components should be installed.

  Installation directory chooser

An installation directory chooser with an optional display of required and free space. The user selection is set as the installation directory.

  License agreement

A form component that displays a license agreement to the user, either plain text or HTML. The license agreement must be accepted before the next screen can be shown.

  Log file viewer

A text area that shows the contents of a text file. The the viewer follows additions to the file like the UNIX command tail -f, with a configurable maximum number of displayed lines.

The log file does not have to exist when the form is shown, it can be created later on. Also, the file can be deleted and re-created. Modifications before the previously observed end of the file will not be picked up by the viewer unless the length of the file decreases.

  PDF display

Displays a PDF file in an embedded cross-platform PDF viewer.

  Program group selector

A form component that allows the user to select a program group on Microsoft Windows.

  Progress display

An progress display that can show the progress of the actions attached to the containing screen.

  Update alert

A pair of radio buttons offering the user a choice whether to update an existing installation or not. If the existing installation should be updated, the installer variable sys.confirmedUpdateInstallation is set to true. Several standard screens use that installer variable in their default condition expression.

  Update schedule selector

Drop-down box that lets the user select an update schedule for your application. You can use the com.install4j.api.update.UpdateScheduleRegistry class in your application to check if you should launch an updater. Please see the Javadoc for more information. Please note that simply adding this form component does not automatically launch an updater at regular intervals.

  Windows user selector

A component for selecting Windows users or groups in the native Windows user dialog. Optionally, you can display a button to create a new user. The selection is saved as a SID to a string variable. If multiple selection is enabled, the result is a string array of SIDs.

This component does not do anything in console mode, since it requires the native Windows dialog for selecting users and groups.

  Category: Text fields

  Password field

A password text field with an optional leading label. The user input is displayed with '*' characters. The user input is saved to a variable.

  Text area

A text area with an optional leading label. The user input is saved to a variable.

  Text field

A text field with an optional leading label. The user input is saved to a variable.

  Text field with date format

A text field with an optional leading label and a date format. The user input (a java.util.Date) is saved to a variable.

  Text field with format mask

A text field with an optional leading label and an arbitrary format mask. The user input is saved to a variable. The default mask is that of an SSN. For more information, please see the javadoc of javax.swing.text.MaskFormatter.

  Text field with integer format

A text field with an optional leading label and an integer format. The user input is saved to a variable with type java.lang.Long.

  Text file editor

A text area for editing a file. If the file does not exist, a configurable initial text is presented to the user and the file is created. The file is saved when the user clicks on the "Next" button.

  Console handler

Allows you to interact with the user in a console installer. All standard form components expose appropriate behavior in console mode, however, there are situations where you need to fine-tune your console installer with additional messages or questions. In GUI or unattended mode, this form component does not have any effect.