The visual appearance of widgets such as buttons, text fields and labels can be customized for installer applications, with a focus on fonts and colors. For the most part, these styles require the FlatLaf cross-platform look and feel to be selected in the Look & Feel step.
Configuring widget styles
Project-wide widget styles are configured on the "Installer->Screen & Actions->Widget Styles" step of the install4j IDE. For each widget style, customizations are grouped into widget categories like "Buttons" or "Labels".
Many widget types have similar customization properties, like "Foreground color" or "Background color". To avoid setting the same colors for all widget types, you can choose common property values in the "Defaults" category. Those values will be used if the widget-specific values are not set.
Most form components show a stylable widget. These form components have a property that corresponds to the relevant widget style category of the project-wide widget style. For example, "Text field" form components have a "Text component widget" style property. Here you can either select a widget style from the drop-down list or choose "Define a custom widget style". In the latter case, the child nodes will show the relevant properties. Note that if you leave any values unset, they fall back to the look and feel default.
A form component can have multiple widget style properties for its sub-widgets. For example, most form components have a leading label for which a label widget style is available.
Window background
While not strictly widgets, windows are present in the widget styles as well. Their background color can be set with the corresponding property in the "Frames and Dialogs" category.
Any color that can be configured in the install4j IDE can have light mode and dark mode variants. The color chooser offers the ability
to define separate colors for light and dark mode, and the text field supports the lr, lg, lb / dr, dg, db
syntax where (l|d)r, (l|d)g, (l|d)b are the light and dark color RGB components.
Widget style selection
Apart from selecting a widget style for each form component, you can also select a widget style for each widget style. By default, new widget styles are associated with the default widget style. You can change the default widget style centrally at any time with the "Set As Default" action in the widget styles step.
When a stylable widget is rendered, the applicable widget style is determined in the following order:
- The inline custom widget style on the form component, if available
- The widget style that has been selected for the current screen. Dialogs that are displayed by actions do not have a screen context.
- The default widget style
All configured widget styles are applied in the preview windows in the install4j IDE, both for screen styles and for screens. The effects of the above configuration steps are shown below.
Merging screen styles from other projects
Similar to screen styles, widget styles can be developed in one project and then be merged into other projects. The merge projects functionality in install4j includes an option to merge styles.
If styles are merged, the drop-down lists for the "Widget Style" properties of screen styles as well as those of the various form components show the merged screen styles as well, prefixed with the project name that was assigned in the merge settings.
If you link to screens or screen groups of merged projects, their contained form components will use their configured widget styles from the merged project only if style merging is enabled. Otherwise, install4j tries to match a widget style by name in the main project.
API
When you develop custom screens or custom form components, you can take advantage of widget styling as well. With the WidgetStyleHandler API you can apply styling to many standard Swing UI components.
If you want the user to select a specific widget style, you can do that with a string property that has a
special widget style ID context.
The IDE will then show a drop-down with all defined widget styles and save the widget style ID to the property.
The WidgetStyleHandler instance offers methods to apply a style from a specific widget style ID.
