Advanced Features

see example: QuickStart

The only requirement of a custom swing widget is the need for a parameterless constructor. The widget can either replace a standard one or be added as a generic type. Basically, a new/changed mapping from generic type to custom class has to be added to the ComponentTypeMap and in some cases a new/changed PresentationCustomizer needs to be added to the CustomizerMap.

To make the changes available for the builder, it's necessary to subclass the default maps (see custom.forms.view.* in the examples), add the new maps to the builder's classpath and set appropriate system properties. The properties (their keys are defined in ResourceKeys) can be set as commandline parameters or from a properties file "resources/forms.properties" that is searched in the builder's classpath. An example of a properties file is included with the examples.

The same approach can be used when loading a form from a FormDescription. But often it's easier to simply replace the mapping directly in the shared Maps. F.i. replace the standard textfield with a custom implementation:

FormFactory.getUIFactory().getComponentTypeMap().addComponentType("TextField", "custom.forms.view.JExtraTextField");

The JGoodies Forms Framework has a concept of LayoutStyle: certain sizes are defined to depend on the OS at runtime and the FormFactory creates logical Row/ColumnSpecs and Borders using those sizes. Defining the layout grid in terms of logical types helps to make an ui consistent with style guides (which may be defined by the OS or some custom needs)

SwingEmpire FormBuilder/FormLoader enhances the style concept in persisting and reading a logical type "style-immutable". A "related gap" persisted in one LayoutStyle will be interpreted as "related gap" in another LayoutStyle even if the concrete encoding is different (f.i. 3dlu in Mac, 4dlu in Win).

The mapping between logical styles and the relevant encoding is controlled by a StyleMap. A custom mapping of a style type to a concrete encoding can be added/removed/modified. FormBuilder comes with an integrated Style Editor to do (startable with the menu item Tools/StyleEditor). Customized StyleMaps can be saved/loaded to/from files and used/modified directly by the builder at design-time.

Most applications will not need to bother to know about custom StyleMaps: the Row/Column/LayoutBorder is persisted as a typeKey/encoding pair for non-default styles. The internal loading mechanism will first check if the style type is known, if so use the StyleMaps encoding or use the persisted encoding if the Style is unknown.

There are contexts where changing Styles on-the-fly might be needed, f.i. when adapting label column widths on localization. Then applications can load the StyleMap just as any other resource with the appropriate FormLoader method. Overwriting the custom style in the StyleMap and re-loading the forms will reflect the changes. QuickStartStyled.java in the examples package demonstrates how to do so.

JGoodiesStyleMap does not allow to change the OS-dependent pre-defined styles of a LayoutStyle: if you really want to change them the way to go is to implement a custom LayoutStyle and make the Forms Framework use it. This high hurdle is deliberate ...

Note: implementing custom StyleMaps is no longer the primary recommendation (though still possible). If you do so the usage is quite analogous to the handling of custom component types: Basically add a custom style to the StyleMap, either by subclassing JGoodiesStyleMap or by simply calling its adder-methods at runtime.

see: custom.forms.io.*