# Groups

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

## Contents

- [Action group](#action-group) — `com.install4j.runtime.beans.groups.ActionGroup`
- [Horizontal group](#horizontal-group) — `com.install4j.runtime.beans.groups.HorizontalFormComponentGroup`
- [Screen group](#screen-group) — `com.install4j.runtime.beans.groups.ScreenGroup`
- [Single tab](#single-tab) — `com.install4j.runtime.beans.groups.TabGroup`
- [Style group](#style-group) — `com.install4j.runtime.beans.groups.StyleGroup`
- [Tabbed pane](#tabbed-pane) — `com.install4j.runtime.beans.groups.TabbedPaneGroup`
- [Vertical group](#vertical-group) — `com.install4j.runtime.beans.groups.VerticalFormComponentGroup`

---

### Action group
- **Class:** `com.install4j.runtime.beans.groups.ActionGroup`
- **Multiple instances:** yes

An action group contains multiple actions that can be disabled with a single condition expression on the group.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `conditionExpression` — Condition expression | ScriptProperty → boolean | Control Flow | — | This expression is evaluated just before the action is executed. If the expression or script returns false, the entire action group will be skipped. |
| `loop` — Loop | boolean | Control Flow | — | If selected, the action group will be looped. With the child properties you can set an expression that terminates the loop and configure a loop index that is available inside the loop.Note: If actions should be repeated in a loop, their "Can be executed multiple times" property has to be selected. If form components in a screen should be re-initialized on each loop, their "Reset initialization on previous" property has to be selected. |
| `loopIndexStart` — Loop index start value | int | Control Flow | `loop`=true | The start value for the loop index variable that is passed to the "Loop expression" |
| `loopIndexStep` — Loop index step | int | Control Flow | `loop`=true | The step for the loop index variable that is passed to the "Loop expression". At the end of each loop, this step is added to the loop index. It is added before the "Loop expression" is evaluated. To decrement, specify a negative value. |
| `loopExpression` — Loop expression | ScriptProperty → boolean | Control Flow | `loop`=true | This expression is evaluated when the end of the action group is reached. If it returns true, all actions will be repeated. If you leave the expression empty, no loop will be performed. |
| `loopIndexVariableName` — Loop index variable name | String [context=variableName] (variable→ Integer) | Control Flow | `loop`=true | If you want to use the loop index in a action that is contained in the group, you can optionally save the value to an installer variable. Specify the variable name to which the value should be saved as a java.lang.Integer. |
| `onErrorBreakGroup` — On error break group | boolean | Error Handling | — | If selected, and one of the contained actions returns with an error, the control flow will step out of the action group and continue with the next element after the group. This behavior only takes effect if the problematic action has its failure strategy set to "Continue on failure". |
| `retryExpression` — Retry expression | ScriptProperty → boolean | Error Handling | `onErrorBreakGroup`=true | If this expression is set and returns true, the action group is repeated. If the action group is configured to loop, the loop index will not be incremented. |
| `failureStrategy` — Failure strategy | [FailureStrategy](enums.md#failurestrategy) | Error Handling | `onErrorBreakGroup`=true | The failure strategy that should be chosen if the action group fails. The "Error message" property will be used for the option dialog. If you also define a "Default error message", you will get two option dialogs, the first one from the action that causes the failure. |
| `failureAskRetry` — Ask whether to retry the action | boolean | Error Handling | `failureStrategy`=Ask user | If an action fails, ask the user whether to retry the action.This is one button in a message dialog that shows the error message and the available options to react to the failure. |
| `failureAskQuit` — Ask whether to quit | boolean | Error Handling | `failureStrategy`=Ask user | If an action fails, ask the user whether to quit the installer application.This is one button in a message dialog that shows the error message and the available options to react to the failure. |
| `failureAskIgnore` — Ask whether to ignore the failure | boolean | Error Handling | `failureStrategy`=Ask user | If an action fails, ask the user whether to ignore the failure and continue.This is one button in a message dialog that shows the error message and the available options to react to the failure. |
| `errorMessage` — Error message | String | Error Handling | `onErrorBreakGroup`=true | If the action group fails, this error message is displayed to the user. Otherwise, the action group fails silently. |
| `defaultErrorMessage` — Default error message | String | Error Handling | — | A default error message used by all actions that have no dedicated error message. |

### Horizontal group
- **Class:** `com.install4j.runtime.beans.groups.HorizontalFormComponentGroup`
- **Multiple instances:** yes

A horizontal form component group contains one or more form components that are distributed along the horizontal axis.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `visibilityScript` — Visibility script | ScriptProperty → boolean | Initialization | — | A script that determines whether form components in the group (and all descendant components in nested groups) will be visible or not. This works for both GUI and console modes. In GUI mode, the script will be invoked each time just before the form components are initialized. Visibility scripts of nested form components can further hide single form components, but they cannot show them if a parent layout group is already hidden. |
| `insets` — Insets | Insets | Layout | — | The insets around the entire group. The format is top;left;bottom;right, use the drop-down button at the right side to show the insets editor. |
| `anchor` — Anchor | [Anchor](enums.md#anchor) | Layout | — | The position in the available space where the group is anchored in the layout. This is only relevant if the group takes less space than the cell that is created by the surroundings. |
| `cellSpacing` — Cell spacing | int | Layout | — | The cell spacing determines how many pixels are inserted between single components in the layout group. |
| `imageFile` — Image File | ExternalFile suffixes=[png, gif] | Configuration | — | An image that is shown on the edge or as a background. Apart from an image that is anchored to the center of the group, the image can optionally cut off an entire edge from the group. In that case, it is possible to set a background color for the edge stripe so that the image can blend into the surroundings. 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. |
| `imageAnchor` — Image anchor | [Anchor](enums.md#anchor) | Configuration | `imageFile` (custom condition) | The anchor where the image will be attached to in the layout group. If Center is chosen, the image is always displayed in the background. |
| `imageEdgeAxisType` — Image edge | [AxisType](enums.md#axistype) | Configuration | `imageFile` (custom condition) | For corner anchors, you have to select either the horizontal or the vertical edge that will optionally be filled with the image edge background color and that will be cut of from the layout group if the image is not displayed in the background. |
| `imageEdgeBackgroundColor` — Image edge background color | Color | Configuration | `imageFile` (custom condition) | The background color that the image edge should be filled with. If the image terminates with the same color, the image will blend with the background and the entire edge will look like a single visual element.Not available if the anchor is set to "Center" |
| `imageInsets` — Image insets | Insets | Configuration | `imageFile` (custom condition) | The insets around the image. The format is top;left;bottom;right, use the drop-down button at the right side to show the insets editor. |
| `imageOverlap` — Overlap with contained components | boolean | Configuration | `imageFile` (custom condition) | If selected, the image will be used as a background image and form components contained in the layout group will overlap with the image. Otherwise, the image edge will be cut off from the layout group and form components will not overlap with the image. In that case, the insets of the layout group will be applied to the actual content area that excludes the image edge.Not available if the anchor is set to "Center" |
| `imageEdgeBorder` — Image edge border | boolean | Configuration | `imageFile` (custom condition) | If selected, the image edge will be separated by a line border from the content area. Not available if the image overlaps the contained components. |
| `imageEdgeBorderColor` — Image edge border color | Color | Configuration | `imageEdgeBorder`=true | The color of the image edge border. Leave empty to choose the default separator color of the current look and feel. |
| `imageEdgeBorderWidth` — Image edge border width | int | Configuration | `imageEdgeBorder`=true | The width of the image edge border in pixels. |
| `backgroundColor` — Background color | Color | Configuration | — | The background color of the layout group. Can be empty. |
| `foregroundColor` — Foreground color | Color | Configuration | — | The foreground color of the layout group. Can be empty. If set, all contained form components will use this foreground color except those that have an explicitly configured foreground color. |
| `borderSides` — Border sides | BorderSides | Configuration | — | On which sides a line border should be painted around the form component, a list of "top", "right", "bottom" and "left", separated by semicolons. Use the drop-down button to select the sides visually. |
| `borderColor` — Border color | Color | Configuration | `borderSides` (custom condition) | The color of the drawn border sides. Leave empty to choose the default separator color of the current look and feel. |
| `borderWidth` — Border width | int | Configuration | `borderSides` (custom condition) | The width of the drawn border sides in pixels. |
| `borderTitle` — Border title | String | Configuration | `borderSides` (custom condition) | A title that is displayed in the top-left corner of the border. Leave empty if no title should be displayed. |
| `alignFirstLabel` — Align first label | boolean | Layout | — | If the horizontal group is directly added to a vertical group or to the top-level of a form, the leading label in the horizontal group is aligned with other leading labels in the vertical parent group. If this alignment is not desired, you can deselect this property. |
| `makeSameHeight` — Make children same height | boolean | Layout | — | If all contained elements should have the same height. |

### Screen group
- **Class:** `com.install4j.runtime.beans.groups.ScreenGroup`
- **Multiple instances:** yes

A screen group contains multiple screens that can be disabled with a single condition expression on the group.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `conditionExpression` — Condition expression | ScriptProperty → boolean | Control Flow | — | This expression is evaluated just before the screen is displayed. If the expression or script returns false, the entire screen group will be skipped. |
| `loop` — Loop | boolean | Control Flow | — | If selected, the screen group will be looped. With the child properties you can set an expression that terminates the loop and configure a loop index that is available inside the loop.Note: If actions should be repeated in a loop, their "Can be executed multiple times" property has to be selected. If form components in a screen should be re-initialized on each loop, their "Reset initialization on previous" property has to be selected. |
| `loopIndexStart` — Loop index start value | int | Control Flow | `loop`=true | The start value for the loop index variable that is passed to the "Loop expression" |
| `loopIndexStep` — Loop index step | int | Control Flow | `loop`=true | The step for the loop index variable that is passed to the "Loop expression". At the end of each loop, this step is added to the loop index. It is added before the "Loop expression" is evaluated. To decrement, specify a negative value. |
| `loopExpression` — Loop expression | ScriptProperty → boolean | Control Flow | `loop`=true | This expression is evaluated when the end of the screen group is reached. If it returns true, all screens will be repeated. If you leave the expression empty, no loop will be performed. |
| `loopIndexVariableName` — Loop index variable name | String [context=variableName] (variable→ Integer) | Control Flow | `loop`=true | If you want to use the loop index in a screen that is contained in the group, you can optionally save the value to an installer variable. Specify the variable name to which the value should be saved as a java.lang.Integer. |

### Single tab
- **Class:** `com.install4j.runtime.beans.groups.TabGroup`
- **Multiple instances:** yes

A single tab can be added to a tabbed pane group. It can contain any kind of form components

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `visibilityScript` — Visibility script | ScriptProperty → boolean | Initialization | — | A script that determines whether form components in the group (and all descendant components in nested groups) will be visible or not. This works for both GUI and console modes. In GUI mode, the script will be invoked each time just before the form components are initialized. Visibility scripts of nested form components can further hide single form components, but they cannot show them if a parent layout group is already hidden. |
| `insets` — Insets | Insets | Layout | — | The insets around the entire group. The format is top;left;bottom;right, use the drop-down button at the right side to show the insets editor. |
| `anchor` — Anchor | [Anchor](enums.md#anchor) | Layout | — | The position in the available space where the group is anchored in the layout. This is only relevant if the group takes less space than the cell that is created by the surroundings. |
| `cellSpacing` — Cell spacing | int | Layout | — | The cell spacing determines how many pixels are inserted between single components in the layout group. |
| `imageFile` — Image File | ExternalFile suffixes=[png, gif] | Configuration | — | An image that is shown on the edge or as a background. Apart from an image that is anchored to the center of the group, the image can optionally cut off an entire edge from the group. In that case, it is possible to set a background color for the edge stripe so that the image can blend into the surroundings. 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. |
| `imageAnchor` — Image anchor | [Anchor](enums.md#anchor) | Configuration | `imageFile` (custom condition) | The anchor where the image will be attached to in the layout group. If Center is chosen, the image is always displayed in the background. |
| `imageEdgeAxisType` — Image edge | [AxisType](enums.md#axistype) | Configuration | `imageFile` (custom condition) | For corner anchors, you have to select either the horizontal or the vertical edge that will optionally be filled with the image edge background color and that will be cut of from the layout group if the image is not displayed in the background. |
| `imageEdgeBackgroundColor` — Image edge background color | Color | Configuration | `imageFile` (custom condition) | The background color that the image edge should be filled with. If the image terminates with the same color, the image will blend with the background and the entire edge will look like a single visual element.Not available if the anchor is set to "Center" |
| `imageInsets` — Image insets | Insets | Configuration | `imageFile` (custom condition) | The insets around the image. The format is top;left;bottom;right, use the drop-down button at the right side to show the insets editor. |
| `imageOverlap` — Overlap with contained components | boolean | Configuration | `imageFile` (custom condition) | If selected, the image will be used as a background image and form components contained in the layout group will overlap with the image. Otherwise, the image edge will be cut off from the layout group and form components will not overlap with the image. In that case, the insets of the layout group will be applied to the actual content area that excludes the image edge.Not available if the anchor is set to "Center" |
| `imageEdgeBorder` — Image edge border | boolean | Configuration | `imageFile` (custom condition) | If selected, the image edge will be separated by a line border from the content area. Not available if the image overlaps the contained components. |
| `imageEdgeBorderColor` — Image edge border color | Color | Configuration | `imageEdgeBorder`=true | The color of the image edge border. Leave empty to choose the default separator color of the current look and feel. |
| `imageEdgeBorderWidth` — Image edge border width | int | Configuration | `imageEdgeBorder`=true | The width of the image edge border in pixels. |
| `backgroundColor` — Background color | Color | Configuration | — | The background color of the layout group. Can be empty. |
| `foregroundColor` — Foreground color | Color | Configuration | — | The foreground color of the layout group. Can be empty. If set, all contained form components will use this foreground color except those that have an explicitly configured foreground color. |
| `borderSides` — Border sides | BorderSides | Configuration | — | On which sides a line border should be painted around the form component, a list of "top", "right", "bottom" and "left", separated by semicolons. Use the drop-down button to select the sides visually. |
| `borderColor` — Border color | Color | Configuration | `borderSides` (custom condition) | The color of the drawn border sides. Leave empty to choose the default separator color of the current look and feel. |
| `borderWidth` — Border width | int | Configuration | `borderSides` (custom condition) | The width of the drawn border sides in pixels. |
| `borderTitle` — Border title | String | Configuration | `borderSides` (custom condition) | A title that is displayed in the top-left corner of the border. Leave empty if no title should be displayed. |
| `title` — Tab title | String | Tab | — | The title that is displayed on the tab. To configure a keyboard shortcut, prefix the mnemonic character in the title 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 tab with the keyboard. |
| `iconFile` — Tab icon | ExternalFile suffixes=[png, gif] | Tab | — | An image file with an icon that is displayed on the tab. 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. |
| `tooltipText` — Tooltip text | String [context=html] | Tab | — | An optional tooltip text that is displayed when the user hovers with the mouse over the tab. |
| `activationScript` — Activation script | ScriptProperty → void | Tab | — | A script that is executed when the tab is activated. |

### Style group
- **Class:** `com.install4j.runtime.beans.groups.StyleGroup`
- **Multiple instances:** yes

A group of styles. Style groups are only provided for organizational purposes.

### Tabbed pane
- **Class:** `com.install4j.runtime.beans.groups.TabbedPaneGroup`
- **Multiple instances:** yes

A tabbed pane contains a number of single tabs, which in turn contain form components.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `visibilityScript` — Visibility script | ScriptProperty → boolean | Initialization | — | A script that determines whether form components in the group (and all descendant components in nested groups) will be visible or not. This works for both GUI and console modes. In GUI mode, the script will be invoked each time just before the form components are initialized. Visibility scripts of nested form components can further hide single form components, but they cannot show them if a parent layout group is already hidden. |
| `insets` — Insets | Insets | Layout | — | The insets around the entire group. The format is top;left;bottom;right, use the drop-down button at the right side to show the insets editor. |
| `anchor` — Anchor | [Anchor](enums.md#anchor) | Layout | — | The position in the available space where the group is anchored in the layout. This is only relevant if the group takes less space than the cell that is created by the surroundings. |
| `tabPlacement` — Tab placement | [TabPlacement](enums.md#tabplacement) | Tabbed Pane | — | The location where the tabs will be displayed. |
| `tabLayoutPolicy` — Tab layout policy | [TabLayoutPolicy](enums.md#tablayoutpolicy) | Tabbed Pane | — | The layout policy for tabs determined what should be done if there is not enough horizontal space to display all tabs. The default policy "Wrap" creates multiple lines of tabs to accommodate all tabs, the policy "Scroll" shows a scroll button and keeps a single line of tabs. |
| `fillHorizontal` — Fill horizontal space | boolean | Tabbed Pane | — | If set, the tabbed will fill all the available horizontal space regardless of its content, otherwise it will be as wide as required by the preferred size of the contained form components. |
| `fillVertical` — Fill extra vertical space | boolean | Tabbed Pane | — | If set, the tabbed pane 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. If this property is not selected, the tabbed pane will be as high as required by the preferred size of the contained form components. |

### Vertical group
- **Class:** `com.install4j.runtime.beans.groups.VerticalFormComponentGroup`
- **Multiple instances:** yes

A vertical form component group contains one or more form components that are distributed along the vertical axis.

| Property | Type | Category | Visible when | Description |
|---|---|---|---|---|
| `visibilityScript` — Visibility script | ScriptProperty → boolean | Initialization | — | A script that determines whether form components in the group (and all descendant components in nested groups) will be visible or not. This works for both GUI and console modes. In GUI mode, the script will be invoked each time just before the form components are initialized. Visibility scripts of nested form components can further hide single form components, but they cannot show them if a parent layout group is already hidden. |
| `insets` — Insets | Insets | Layout | — | The insets around the entire group. The format is top;left;bottom;right, use the drop-down button at the right side to show the insets editor. |
| `anchor` — Anchor | [Anchor](enums.md#anchor) | Layout | — | The position in the available space where the group is anchored in the layout. This is only relevant if the group takes less space than the cell that is created by the surroundings. |
| `cellSpacing` — Cell spacing | int | Layout | — | The cell spacing determines how many pixels are inserted between single components in the layout group. |
| `imageFile` — Image File | ExternalFile suffixes=[png, gif] | Configuration | — | An image that is shown on the edge or as a background. Apart from an image that is anchored to the center of the group, the image can optionally cut off an entire edge from the group. In that case, it is possible to set a background color for the edge stripe so that the image can blend into the surroundings. 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. |
| `imageAnchor` — Image anchor | [Anchor](enums.md#anchor) | Configuration | `imageFile` (custom condition) | The anchor where the image will be attached to in the layout group. If Center is chosen, the image is always displayed in the background. |
| `imageEdgeAxisType` — Image edge | [AxisType](enums.md#axistype) | Configuration | `imageFile` (custom condition) | For corner anchors, you have to select either the horizontal or the vertical edge that will optionally be filled with the image edge background color and that will be cut of from the layout group if the image is not displayed in the background. |
| `imageEdgeBackgroundColor` — Image edge background color | Color | Configuration | `imageFile` (custom condition) | The background color that the image edge should be filled with. If the image terminates with the same color, the image will blend with the background and the entire edge will look like a single visual element.Not available if the anchor is set to "Center" |
| `imageInsets` — Image insets | Insets | Configuration | `imageFile` (custom condition) | The insets around the image. The format is top;left;bottom;right, use the drop-down button at the right side to show the insets editor. |
| `imageOverlap` — Overlap with contained components | boolean | Configuration | `imageFile` (custom condition) | If selected, the image will be used as a background image and form components contained in the layout group will overlap with the image. Otherwise, the image edge will be cut off from the layout group and form components will not overlap with the image. In that case, the insets of the layout group will be applied to the actual content area that excludes the image edge.Not available if the anchor is set to "Center" |
| `imageEdgeBorder` — Image edge border | boolean | Configuration | `imageFile` (custom condition) | If selected, the image edge will be separated by a line border from the content area. Not available if the image overlaps the contained components. |
| `imageEdgeBorderColor` — Image edge border color | Color | Configuration | `imageEdgeBorder`=true | The color of the image edge border. Leave empty to choose the default separator color of the current look and feel. |
| `imageEdgeBorderWidth` — Image edge border width | int | Configuration | `imageEdgeBorder`=true | The width of the image edge border in pixels. |
| `backgroundColor` — Background color | Color | Configuration | — | The background color of the layout group. Can be empty. |
| `foregroundColor` — Foreground color | Color | Configuration | — | The foreground color of the layout group. Can be empty. If set, all contained form components will use this foreground color except those that have an explicitly configured foreground color. |
| `borderSides` — Border sides | BorderSides | Configuration | — | On which sides a line border should be painted around the form component, a list of "top", "right", "bottom" and "left", separated by semicolons. Use the drop-down button to select the sides visually. |
| `borderColor` — Border color | Color | Configuration | `borderSides` (custom condition) | The color of the drawn border sides. Leave empty to choose the default separator color of the current look and feel. |
| `borderWidth` — Border width | int | Configuration | `borderSides` (custom condition) | The width of the drawn border sides in pixels. |
| `borderTitle` — Border title | String | Configuration | `borderSides` (custom condition) | A title that is displayed in the top-left corner of the border. Leave empty if no title should be displayed. |
| `makeSameWidth` — Make children same width | boolean | Layout | — | If all contained elements should have the same width. |

