# Form components: Special selectors and displays

install4j BeanInfo catalog. Each entry below documents a bean class that can appear inside a `<serializedBean>` element in an install4j project file.

## Contents

- [Directory chooser](#directory-chooser) — `com.install4j.runtime.beans.formcomponents.DirectoryChooserComponent`
- [File associations selector](#file-associations-selector) — `com.install4j.runtime.beans.formcomponents.FileAssociationsComponent`
- [File chooser](#file-chooser) — `com.install4j.runtime.beans.formcomponents.FileChooserComponent`
- [HTML or text display](#html-or-text-display) — `com.install4j.runtime.beans.formcomponents.HtmlDisplayFormComponent`
- [Installation components selector](#installation-components-selector) — `com.install4j.runtime.beans.formcomponents.ComponentSelectorComponent`
- [Installation directory chooser](#installation-directory-chooser) — `com.install4j.runtime.beans.formcomponents.InstallationDirectoryChooserComponent`
- [Installation scope chooser](#installation-scope-chooser) — `com.install4j.runtime.beans.formcomponents.InstallationScopeChooserComponent`
- [License agreement](#license-agreement) — `com.install4j.runtime.beans.formcomponents.LicenseComponent`
- [Log file viewer](#log-file-viewer) — `com.install4j.runtime.beans.formcomponents.LogFileViewerComponent`
- [Program group selector](#program-group-selector) — `com.install4j.runtime.beans.formcomponents.ProgramGroupComponent`
- [Progress display](#progress-display) — `com.install4j.runtime.beans.formcomponents.ProgressComponent`
- [Streamlined installation chooser](#streamlined-installation-chooser) — `com.install4j.runtime.beans.formcomponents.StreamlinedInstallationChooserComponent`
- [Update schedule selector](#update-schedule-selector) — `com.install4j.runtime.beans.formcomponents.UpdateScheduleSelectorComponent`
- [Windows user selector](#windows-user-selector) — `com.install4j.runtime.beans.formcomponents.UserSelectorComponent`

---

### Directory chooser
- **Class:** `com.install4j.runtime.beans.formcomponents.DirectoryChooserComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `variableName` — Variable name | String [context=variableName] (variable→ String) | User input | — | The name of the variable to which the user input is assigned. The type of the variable value is java.lang.String |
| `initialFile` — Initial directory | String | Directory chooser | — | The initially selected directory. The variable value takes precedence, so this value will only be used if the variable value is undefined. Can be empty. |
| `initialBrowserDirectory` — Initial browser directory | String | Directory chooser | — | The initial directory that is shown in the browser if no directory is selected. If empty, the browser will start in the user home directory. If a directory is entered in the text field, the browser will use that path instead. |
| `directoryDescription` — Border title | String | Directory chooser | — | The description of the kind of directory that the user should select, in a few words, e.g. "ABC directory". This will be shown in a titled border around the text field.A border title should not be set together with a leading label. |
| `standardDirectoryName` — Standard directory | String | Directory chooser | — | A directory name that should be appended to the user selection in the directory browser. Should be empty if an existing directory has to be selected. |
| `nextOnEnter` — Next screen on enter | boolean | Directory chooser | — | If selected and the user hits the enter key while the text field is focused, the next screen is activated. |
| `allowSpacesOnUnix` — Allow spaces in directory name | boolean | Unix | — | If selected, spaces are valid characters in the installation directory name for Unix/Linux installers, otherwise an error message is displayed if the user chooses a directory with spaces in it. Some JREs do not work on Unix if installed to a path that contains spaces, so spaces are disallowed by default. |
| `manualEntryAllowed` — Manual entry allowed | boolean | Chooser Dialog | — | If selected, the user can enter the directory manually in the text field. Otherwise, the text field is disabled. |
| `validationScript` — Validation script | ScriptProperty → boolean | User input | — | The script that is executed when the directory is selected with the chooser button and when the user clicks on the Next button of the screen. If the script returns true, the selection is accepted, if it returns false, the selection is discarded. |
| `standardValidation` — Standard validation | boolean | User input | — | If selected, the standard validation for well-formed directory names will be performed. This validation is performed before the validation script and will canonicalize the directory name before passing it to the validation script. |
| `allowEmpty` — Allow empty input | boolean | User input | — | If selected, the user can leave the directory empty or clear the initial directory (if manual entry is allowed) and there will be no validation error. |
| `onlyWritable` — Only accept writable directories | boolean | User input | — | If selected, non-writable directories will be rejected. |

### File associations selector
- **Class:** `com.install4j.runtime.beans.formcomponents.FileAssociationsComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `showSelectionButtons` — Show selection buttons | boolean | Configuration | — | If selected, the screen will show buttons for selecting and deselecting all file associations. |
| `selectionButtonPosition` — Position of selection buttons | [VerticalDockingPosition](enums.md#verticaldockingposition) | Configuration | `showSelectionButtons`=true | The selection buttons can be added at the top or at the bottom of the form component. |
| `fillVertical` — Fill extra vertical space | boolean | Configuration | — | If set, the form component will expand to fill remaining vertical space. Extra vertical space is only available if the form is not scrollable. Custom form screens have a "Scrollable" property, which must be set to false. |

### File chooser
- **Class:** `com.install4j.runtime.beans.formcomponents.FileChooserComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `variableName` — Variable name | String [context=variableName] (variable→ String) | User input | — | The name of the variable to which the user input is assigned. The type of the variable value is java.lang.String |
| `initialFile` — Initial file | String | File chooser | — | The initially selected file. The variable value takes precedence, so this value will only be used if the variable value is undefined. Can be empty. |
| `initialBrowserDirectory` — Initial browser directory | String | File chooser | — | The initial directory that is shown in the browser if no file is selected. If empty, the browser will start in the user home directory. If a file is entered in the text field, the browser will use that path instead. |
| `useFileFilter` — Use file filter | boolean | File chooser | — | If a file filter should be used. Configure the file filter in the nested properties once you enable this option. |
| `fileFilterName` — File filter name | String | File chooser | `useFileFilter`=true | The name of the file filter which is displayed to the user in the drop-down filter list of the file chooser. |
| `filteredExtensions` — Filtered file extension | String[] [context=file extension] | File chooser | `useFileFilter`=true | The list of the filtered file extension. A file extension may be written as *.xml, .xml or xml, all three notations are equivalent. In the edit dialog, you have to enter one item per line. File extensions that are installer variables with array or collection values (e.g. String[], Object[] or List<File>) are expanded as separate file extensions, this allows you to build a variable length list of file extensions at runtime. |
| `manualEntryAllowed` — Manual entry allowed | boolean | Chooser Dialog | — | If selected, the user can enter the file manually in the text field. Otherwise, the text field is disabled. |
| `validationScript` — Validation script | ScriptProperty → boolean | User input | — | The script that is executed when the file is selected with the chooser button and when the user clicks on the Next button of the screen. If the script returns true, the selection is accepted, if it returns false, the selection is discarded. |

### HTML or text display
- **Class:** `com.install4j.runtime.beans.formcomponents.HtmlDisplayFormComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `textSource` — Text source | [TextSource](enums.md#textsource) | HTML or text display | — | The source from which the text is loaded. For multi-language installers, the "File" source is recommended since it is more easily localizable than the direct entry. |
| `displayedTextFile` — Text file | LocalizedExternalFile suffixes=[html, htm, txt, utf8] [context=externalOrInternal] | HTML or text display | `textSource`=File | The file from which the text is loaded. |
| `displayedText` — Text | String [context=html] | HTML or text display | `textSource`=Direct | The text that is displayed in the screen, either plain text or HTML. For HTML, the value should start with <html>, otherwise the plain text will be displayed. The text is displayed in a scrollable text area. |
| `documentUpdateCaretPosition` — Caret position after update | [DocumentUpdateCaretPosition](enums.md#documentupdatecaretposition) | HTML or text display | — | Selects how the caret position should be moved when the displayed document is updated.For example, you could use a "Run executable or batch file" action and redirect its output to a variable, choosing the option to update the variable after each line. By selecting the value "End of document" and setting the text to the installer variable, the output of the process would be displayed live. |
| `variableName` — Variable name | String [context=variableName] (variable→ String) | HTML or text display | — | Optionally, you can save the actually displayed text to a variable. Enter the variable name without the installer prefix and the dollar sign. This is useful if you display localized text and want to save the actually displayed text with a "Write text to a file" action later on. |
| `height` — Height | int | HTML or text display | — | The height of the HTML display in pixels. |
| `fillVertical` — Fill extra vertical space | boolean | HTML or text display | — | If set, the form component will expand to fill remaining vertical space. Extra vertical space is only available if the form is not scrollable. Custom form screens have a "Scrollable" property, which must be set to false. |
| `widgetStyleId` — Text component style | String [context=widgetStyleIdOrCustom] | HTML or text display | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | TextComponentWidgetStyle | HTML or text display | `widgetStyleId` (custom condition) | widgetStyle |

### Installation components selector
- **Class:** `com.install4j.runtime.beans.formcomponents.ComponentSelectorComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** no

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `selectionChangedScript` — Selection change script | ScriptProperty → void | Component Selector | — | A script that is invoked each time the selection state of a component is changed. If a component has dependencies that are changed as well, or if entire folders are toggled, this script will be called repeatedly, once for each installation component whose selection state is changed. If the dependency parameter is false, this tells you that the corresponding installation component belongs to the node that the user has actually toggled. If a folder is toggled, dependency will be true for all installation components. |
| `boldDescription` — Bold font | boolean | Description | — | Use a bold font for the descriptions |
| `italicDescription` — Italic font | boolean | Description | — | Use an italic font for the descriptions |
| `smallerDescription` — Smaller font | boolean | Description | — | Use a smaller font for the descriptions |
| `fillVertical` — Fill extra vertical space | boolean | Component Selector | — | If set, the form component will expand to fill remaining vertical space. Extra vertical space is only available if the form is not scrollable. Custom form screens have a "Scrollable" property, which must be set to false. |

### Installation directory chooser
- **Class:** `com.install4j.runtime.beans.formcomponents.InstallationDirectoryChooserComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `checkFreeSpace` — Insufficient disk space warning | boolean | Disk Space | — | Show a warning message if there is no sufficient disk space for the installation on the selected target drive. |
| `showRequiredDiskSpace` — Show required disk space | boolean | Disk Space | — | Show the disk space required for the installation. You should switch this off if your installation includes other data sources. |
| `showFreeDiskSpace` — Show free disk space | boolean | Disk Space | — | Show the disk space that is available on the selected drive or partition. This setting is only effective for Windows, macOS and Linux. |
| `suggestAppDir` — Suggest application directory | boolean | Application ID | — | When the user chooses a directory, always append the default application directory configured in the media file wizard. You should only switch this off if you substitute a different installation directory in the screen validation. |
| `existingDirWarning` — Existing directory warning | boolean | Application ID | — | Ask the user whether to install the application in the selected directory if it already exists and the installation is not an update. |
| `validateApplicationId` — Validate application id | boolean | Application ID | — | Check if another application is installed in the selected directory or if the application is not the correct target for an add-on installer. |
| `checkWritable` — Check if directory is writable | boolean | Application ID | — | Check if the directory is writable with the currently available privileges and show a warning message if it is not. If you deselect this option, and the directory is not writable, you should execute a "Request privileges" action before installing files to the installation directory. |
| `noWritableCheckIfInstallingForAllUsers` — Do not check when installing for all users | boolean | Application ID | `checkWritable`=true | If the installer variable "sys.installForAllUsers" has been set to true, do not perform the check if the installation directory is writable. This is relevant if you have a "Installation scope chooser form component or screen and you have a "Request privileges" action later in the project that will obtain the necessary privileges. |
| `allowSpacesOnUnix` — Allow spaces in directory name | boolean | Unix | — | If selected, spaces are valid characters in the installation directory name for Unix/Linux installers, otherwise an error message is displayed if the user chooses a directory with spaces in it. Some JREs do not work on Unix if installed to a path that contains spaces, so spaces are disallowed by default. |
| `manualEntryAllowed` — Manual entry allowed | boolean | Chooser Dialog | — | If selected, the user can enter the installation directory manually in the text field. Otherwise, the text field is disabled. |
| `validationScript` — Validation script | ScriptProperty → boolean | User input | — | The script that is executed when the installation directory is selected with the chooser button and when the user clicks on the Next button of the screen. If the script returns true, the selection is accepted, if it returns false, the selection is discarded. |
| `standardValidation` — Standard validation | boolean | User input | — | If selected, the standard validation for well-formed directory names will be performed. This validation is performed before the validation script and will canonicalize the directory name before passing it to the validation script. |

### Installation scope chooser
- **Class:** `com.install4j.runtime.beans.formcomponents.InstallationScopeChooserComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

A pair of radio buttons offering the user a choice whether to install to a user-specific location or whether to install for all users. The initial selection depends on the "sys.installForAllUsers" variable. Because user-specific installations do not require elevated privileges, that variable is set to false by default unless the installation directory is set to a non-writable directory due to an update installation or with the -dir parameter on the command line.When user clicks Next, the "sys.installForAllUsers" variable is updated according to the user selection. It can be used by the "Set installation directory" action with its "Installation scope" property set to "According to the sys.installForAllUsers variable" to adjust the installation directory

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `selectionScript` — Selection script | ScriptProperty → void | User input | — | Invoked when the user changes the selection or when the screen is activated and this form component is visible. |

### License agreement
- **Class:** `com.install4j.runtime.beans.formcomponents.LicenseComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `textSource` — Text source | [TextSource](enums.md#textsource) | License agreement | — | The source from which the license is loaded. For multi-language installers, the "File" source is recommended since it is more easily localizable than the direct entry. |
| `displayedTextFile` — License file | LocalizedExternalFile suffixes=[html, htm, txt, utf8] [context=externalOrInternal] | License agreement | `textSource`=File | The file from which the license is loaded. |
| `displayedText` — License | String [context=html] | License agreement | `textSource`=Direct | The license that is displayed in the screen, either plain text or HTML. For HTML, the value should start with <html>, otherwise the plain text will be displayed. The text is displayed in a scrollable text area. |
| `documentUpdateCaretPosition` — Caret position after update | [DocumentUpdateCaretPosition](enums.md#documentupdatecaretposition) | License agreement | — | Selects how the caret position should be moved when the displayed document is updated.For example, you could use a "Run executable or batch file" action and redirect its output to a variable, choosing the option to update the variable after each line. By selecting the value "End of document" and setting the text to the installer variable, the output of the process would be displayed live. |
| `variableName` — Variable name | String [context=variableName] (variable→ String) | License agreement | — | Optionally, you can save the actually displayed text to a variable. Enter the variable name without the installer prefix and the dollar sign. This is useful if you display localized text and want to save the actually displayed text with a "Write text to a file" action later on. |
| `height` — Height | int | License agreement | — | The height of the HTML display in pixels. |
| `fillVertical` — Fill extra vertical space | boolean | License agreement | — | If set, the form component will expand to fill remaining vertical space. Extra vertical space is only available if the form is not scrollable. Custom form screens have a "Scrollable" property, which must be set to false. |
| `widgetStyleId` — Text component style | String [context=widgetStyleIdOrCustom] | License agreement | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | TextComponentWidgetStyle | License agreement | `widgetStyleId` (custom condition) | widgetStyle |
| `acceptInitiallySelected` — Initially accepted | boolean | License agreement | — | If selected, the "Accept" radio button is initially selected. |
| `readAllRequired` — User must scroll to bottom | boolean | License agreement | — | If selected, the user can only accept the license if the text area with the license text has been previously scrolled to the bottom. Has no effect if the "Initially selected" property is selected. |
| `radioButtonsAxisType` — Radio buttons axis | [AxisType](enums.md#axistype) | License agreement | — | The axis along which the radio buttons for accepting the license agreement are layouted. |

### Log file viewer
- **Class:** `com.install4j.runtime.beans.formcomponents.LogFileViewerComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

A text area that shows the contents of a text file. 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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `file` — Log file | File suffixes=[log, txt] | Log file viewer | — | The text file that should be displayed. It does not have to exist when the form is shown. |
| `encoding` — Log file encoding | String | Log file viewer | — | The character set name as recognized by java.nio.Charset.forName(...). Values supported by all JREs include "US-ASCII" "ISO-8859-1", "UTF-8" and "UTF-16". If empty, the native encoding of the runtime platform will be used. |
| `maxLines` — Maximum number of displayed lines | int | Log file viewer | — | The maximum number of lines that should be kept in the text display. Excess lines are removed from the beginning. |
| `rows` — Text area rows | int | Log file viewer | — | The height of the text area, expressed as a multiple of line heights. Must be greater than zero.This property only has an effect if the "Fill extra vertical space" property is not selected. |
| `fillVertical` — Fill extra vertical space | boolean | Log file viewer | — | If set, the form component will expand to fill remaining vertical space. Extra vertical space is only available if the form is not scrollable. Custom form screens have a "Scrollable" property, which must be set to false. |
| `widgetStyleId` — Text component style | String [context=widgetStyleIdOrCustom] | Log file viewer | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | TextComponentWidgetStyle | Log file viewer | `widgetStyleId` (custom condition) | widgetStyle |

### Program group selector
- **Class:** `com.install4j.runtime.beans.formcomponents.ProgramGroupComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `variableName` — Variable name for selection | String [context=variableName] (variable→ String) | Program group selector | — | The name of the variable to which the selected program group is saved when the user advances to the next screen. |
| `initialProgramGroup` — Initial program group | String | Program group selector | — | The initially selected program group. Can be empty if no program group should be initially selected. |
| `allUsers` — Program groups for all users | boolean | Program group selector | — | If selected, the program groups for all users are shown, otherwise the program groups for the current user are shown. |
| `showWarningIfExists` — Show warning if program group exists | boolean | Program group selector | — | If selected, a warning will be shown if the selected program group already exists. |
| `fillVertical` — Fill extra vertical space | boolean | Program group selector | — | If set, the form component will expand to fill remaining vertical space. Extra vertical space is only available if the form is not scrollable. Custom form screens have a "Scrollable" property, which must be set to false. |

### Progress display
- **Class:** `com.install4j.runtime.beans.formcomponents.ProgressComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `hideInitially` — Hide initially | boolean | Configuration | — | If selected, the progress bar is hidden when the form is shown. When the actions attached to the screen are executed, the progress bar is made visible. |
| `statusVisible` — Status line visible | boolean | Configuration | — | If selected, the status line is visible. |
| `initialStatusMessage` — Initial status message | String | Configuration | `statusVisible`=true | The initial status message displayed by the progress screen. You can change this message with "Set messages" actions or by invoking Context.getProgressInterface().setStatusMessage("..."). |
| `detailVisible` — Detail line visible | boolean | Configuration | — | If selected, the detail line is visible. |
| `initialDetailMessage` — Initial detail message | String | Configuration | `detailVisible`=true | The initial detail message displayed by the progress screen. You can change this message with "Set messages" actions or by invoking Context.getProgressInterface().setDetailMessage("..."). |
| `widgetStyleId` — Progress bar widget style | String [context=widgetStyleIdOrCustom] | Configuration | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `widgetStyle` — widgetStyle | ProgressBarWidgetStyle | Configuration | `widgetStyleId` (custom condition) | widgetStyle |

### Streamlined installation chooser
- **Class:** `com.install4j.runtime.beans.formcomponents.StreamlinedInstallationChooserComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

A pair of radio buttons offering the user a choice whether to perform a streamlined installation with default settings or to customize the installation. If the installation should be streamlined, the installer variable sys.streamlinedInstallation is set to true. Several standard screens use that installer variable in their default condition expression.The "Streamlined installation strategy" property offers an alternative mode where the streamlining is only offered for update installations.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `streamlinedInstallationStrategy` — Streamlined installation strategy | [StreamlinedInstallationStrategy](enums.md#streamlinedinstallationstrategy) | Configuration | — | Determines when a streamlined installation strategy is offered that skips non-essential screens.If a streamlined installation is selected by the user, the installer variable sys.streamlinedInstallation will be set to Boolean.TRUE. The default condition expressions on the "Installation location" screen and the "Create program group" screen are set so that the screens are skipped in that case. If set to "Offer streamlined installation only for update", a streamlined installation will only be offered for if context.isUpdateInstallation() returns true. In that case, the user will be presented with the choice to update the existing installation or select a new installation directory. Note that this only works reliably if a "Set installation directory" with update installation checking enabled was already executed at this point. |
| `updateAlertSelection` — Initially selected choice | [UpdateAlertSelection](enums.md#updatealertselection) | Configuration | `streamlinedInstallationStrategy`=Offer streamlined installation only for update | Determines the initially selected radio button if an update installation is found. |
| `customizationSelection` — Initially selected choice | [CustomizationSelection](enums.md#customizationselection) | Configuration | `streamlinedInstallationStrategy`=Always offer streamlined installation | Determines the initially selected radio button for the streamlining question. |
| `selectionScript` — Selection script | ScriptProperty → void | User input | — | Invoked when the user changes the selection or when the screen is activated and this form component is visible. |

### Update schedule selector
- **Class:** `com.install4j.runtime.beans.formcomponents.UpdateScheduleSelectorComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. To configure a keyboard shortcut, prefix the mnemonic character in the label text with &, e.g."&User". The prefixed character will be underlined and the platform-specific keyboard shortcut (e.g. ALT+[character] on Windows) will allow the user to quickly navigate to this form component with the keyboard. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `requestFocus` — Request focus | boolean | User input | — | If selected, the form component will request the focus after the form is activated. If you have multiple form components in a single form that have this property selected, the result is undefined. |
| `initialUpdateSchedule` — Initial update schedule | [UpdateSchedule](enums.md#updateschedule) | Configuration | — | The initially selected update schedule. If the user has already installed the application before, the currently active selection by the user will be selected and this value will be ignored. |

### Windows user selector
- **Class:** `com.install4j.runtime.beans.formcomponents.UserSelectorComponent`
- **Category:** Special selectors and displays
- **Multiple instances:** yes

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.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `labelText` — Text | String | Label | — | The text of the label. Can be empty. |
| `labelWidgetStyleId` — Label widget style | String [context=widgetStyleIdOrCustom] | Label | — | If no explicit widget style is set, the widget style from the active screen style is used.You can also set an explicit custom style for this widget. |
| `labelWidgetStyle` — labelWidgetStyle | LabelWidgetStyle | Label | `labelWidgetStyleId` (custom condition) | labelWidgetStyle |
| `labelIconFile` — Icon | ExternalFile suffixes=[png, gif] | Label | — | An image file with an icon for the label label. Can be empty.To add a high-resolution image, create a file with double the resolution and an additional @2x after the name (e.g. image.png and image@2x.png) next to the selected image. To use different images in dark mode, add files with an additional _dark suffix (e.g. image_dark.png and image@2x_dark.png) The install4j runtime JAR file i4jruntime.jar contains a number of image files that you can reference here by prefixing the icon file name with "icon:". For example, icon:lock_open_32.png loads a 32x32 icon showing an open lock. |
| `helpText` — Help text | String [context=html] | Help | — | If a text is entered into this property, a tooltip label with a help icon will be created on the right side of the form component that will display the help text when the user hovers with the mouse above the icon. The text can be plain text or HTML. For multi-line labels, use HTML like this: <html>This is line one<br>This is line two</tt></html>. |
| `variableName` — Variable name | String [context=variableName] | User input | — | The name of the variable to which the user input is assigned. The variable value will be a string with the selected SID, or, if multiple selection is enabled, a string array of SIDs. |
| `showUsers` — Show users | boolean | Configuration | — | Show users in the native user selection dialog. |
| `showGroups` — Show groups | boolean | Configuration | — | Show users in the native user selection dialog. |
| `showWellKnownPrincipals` — Show well-known principals | boolean | Configuration | — | Show well-known principals like "SYSTEM" or "SERVICE" in the native user selection dialog. |
| `multipleSelection` — Multiple selection | boolean | Configuration | — | If selected, multiple users or groups can be selected. The variable type is a string array of SIDs in that case, otherwise it is a string with the single selected SID. Multiple selection cannot be combined with the "Create User" option. |
| `onlyLocal` — Only local objects | boolean | Configuration | — | If selected, only local users and groups will be displayed. |
| `showCreateButton` — Show "Create User" button | boolean | Configuration | `showUsers`=true | If selected, a button to create a new user will be displayed next to the "Browse" button. On clicking that button, a separate dialog will be shown where the new user can be configured. |
| `userCreatedVariableName` — Variable for user creation flag | String [context=variableName] (variable→ Boolean) | Configuration | `showCreateButton`=true | The name of the variable which will be set to Boolean.TRUE if the selected user has been created by the user. If the selected user has not been created, the variable value will be set to Boolean.FALSE. This is useful if you would like to determine if the uninstaller should delete the user. Users can be deleted with the install4j API.This variable name can be empty, in which case the creation status will not be saved. |
| `localGroupVariableName` — Variable for local group | String [context=variableName] (variable→ String) | Configuration | `showCreateButton`=true | The name of the variable which will be set to the local group used for a newly created user. This variable name can be empty, in which case the created local group name will not be saved. |
| `groupCreatedVariableName` — Variable for group creation flag | String [context=variableName] (variable→ Boolean) | Configuration | `showCreateButton`=true | The name of the variable which will be set to Boolean.TRUE if a group for the selected user has been created by the user. If the selected user has not been created or if an existing group was used, the variable value will be set to Boolean.FALSE. This is useful if you would like to determine if the uninstaller should delete the local group. Groups can be deleted with the install4j API.This variable name can be empty, in which case the creation status will not be saved. |
| `passwordFormComponentId` — Password form component | String [context=formComponent] | Configuration | `showCreateButton`=true | A text field or password field form component that should be updated with the password that was chosen for the created user. If not selected, no such update will be performed. |

