Layout groups can be configured in the form components configuration dialog. This chapter discusses the configuration options for layout groups, for more information on layout groups, see the corresponding help topic.

You can create a layout group from selected form components with the  Create Horizontal Group and  Create Vertical Group actions. The new group will be inserted in place of the selected elements.

You can dissolve a group with the Dissolve Group action. This action is only enabled if the selection consists of a single layout group. The elements contained in the group will be inserted in place of the group. Nested groups will not be dissolved.

Grouping features

Form components can be grouped in horizontal and vertical layout groups and you can nest groups to an arbitrary depth.

Grouping offers the following benefits:

• Custom layout

  Instead of a simple sequence of form components on a form screen, you can use horizontal layout groups to put form components side-by-side. Nesting vertical and horizontal form components allows you to achieve virtually any layout.

  Sometimes, enclosing groups and sibling groups create a cell that cannot be entirely filled by a layout group. With the "Anchor" property you determine where the group should be placed in that case. By default, horizontal layout groups are anchored at "West" and vertical layout groups are anchored at "North-West".

  Layout groups have a configurable cell spacing. For vertical layout groups, this is the vertical gap between two form components (0 pixels by default), for horizontal layout groups this is the horizontal gap between two adjacent form components (5 pixels by default)

  For each layout group, you can specify insets that are inserted around the entire layout group. By default, the insets are zero in all directions.

  By default, a horizontal layout group aligns a leading label of its first form component with the leading label of the first form component from a direct vertical parent group. This is usually appropriate when horizontal groups are used to attach additional form components to the right side. If this alignment is not desired, you can use the "Align first label" property of a horizontal layout group to switch off the alignment.

  Vertical layout groups always break the alignment of leading labels: Within a vertical group, leading labels are aligned, but between vertical groups, the width of leading labels is unrelated.

• Organization

  If you have many form components on a screen, vertical groups emphasize which form components belong together. You can add a common comment to the group.

• Common visibility script

  Groups have a "Visibility script" property that allows you to hide the entire group with a common condition instead of having to repeat the condition for each contained form component.

• Single target for coupled form components

  If a set of form components should be coupled to the selection state of a checkbox or a single radio button, you can select the containing layout group as the target instead of selecting all coupled form components separately.

• Styling

  Layout groups have properties for setting background images and borders, as well as background and foreground colors. Styles use layout groups to achieve visual effects.

Properties of layout groups

Common properties of horizontal and vertical layout groups are:

• Image File [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 [email protected]) 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.

• Image anchor [Configuration]

  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.

• Image edge [Configuration]

  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.

• Image edge background color [Configuration]

  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"

• Image edge border [Configuration]

  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.

• Image edge border color [Configuration]

  The color of the image edge border. Leave empty to choose the default separator color of the current look and feel.

  This property is only visible if "Image edge border" is selected.

• Image edge border width [Configuration]

  The width of the image edge border in pixels.

  This property is only visible if "Image edge border" is selected.

• Image insets [Configuration]

  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.

• Overlap with contained components [Configuration]

  If selected, the image will by 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"

• Background color [Configuration]

  The background color of the layout group. Can be empty.

• Foreground 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.

• Border sides [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.

• Border color [Configuration]

  The color of the drawn border sides. Leave empty to choose the default separator color of the current look and feel.

• Border title [Configuration]

  A title that is displayed in the top-left corner of the border. Leave empty if no title should be displayed.

• Border width [Configuration]

  The width of the drawn border sides in pixels.

• Visibility script [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 [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 [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.

• Cell spacing [Layout]

  The cell spacing determines how many pixels are inserted between single components in the layout group.

Vertical layout groups have the additional properties:

• Make children same width [Layout]

  If all contained elements should have the same width.

and horizontal layout groups have the following specific properties:

• Align first label [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.

• Make children same height [Layout]

  If all contained elements should have the same height.

Tabbed panes

In addition to horizontal and vertical layout groups, you can add tabbed panes to a form. A tabbed pane is added by choosing Tabbed Panes->Add Tabbed Pane from the dropdown menu displayed by the  Add button. Below the tabbed pane, you have to add one or more single tabs by choosing Tabbed Panes->Add Single Tab For Tabbed Pane. Each single tab can then contain arbitrary form components or layout groups.