Package ca.corbett.forms

Class FormPanel

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
ca.corbett.forms.FormPanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public final class FormPanel extends JPanel
FormPanel wraps a collection of FormFields and manages the following functions:
  • Layout management - you don't need to write manual GridBagLayout code to use a FormPanel. Just add your FormFields to the panel and the layout will be handled automatically.
  • Form validation - assuming you've added FieldValidator instances to your FormFields as needed, you don't need to write much manual validation code, and you don't need to write any UI code to show validation results. Just call validateForm() or isFormValid(), and the validators will be invoked automatically.
  • Optional inline help - every FormField can have optional help text which the FormPanel will render inline in the form of an information icon next to the field, which will show tooltip help text.
  • Generic FormField handling - the FormField class is highly extensible, so you can very easily provide your own FormField implementation for custom display and editing of data.

Handling oversized forms

You can easily add a FormPanel to a JScrollPane to provide for scrollbars in the case where the form is unreasonably large.

Alignment

The Alignment property of the FormPanel controls how the entire form is aligned within the panel. You can choose left, center, or right horizontal alignment, and top, center, or bottom vertical alignment.

Additionally, the setBorderMargin() method allows you to specify extra pixel margins around the entire form, to keep it away from the edges of its container.

More documentation

The swing-extras-book contains much more documentation regarding the use of FormPanel, FormField, and related classes. Additionally, the built-in demo application showcases many of the features of this library.

Since:
2019-11-24
Author:
scorbo2
See Also:

  • Field Details

  • Constructor Details

    • FormPanel

      public FormPanel()
      Creates a new, empty FormPanel with TOP_CENTER Alignment.

    • FormPanel

      public FormPanel(Alignment alignment)
      Creates a new, empty FormPanel with the given Alignment.

  • Method Details

    • setBorderMargin

      public FormPanel setBorderMargin(int margin)
      An optional pixel margin for the FormPanel itself to keep it away from the edges of its container. The default value is zero, meaning no extra margins will be applied. Note that any value given here is added to whatever margins are already present on each individual FormField. This value does not replace those values. So, you can still indent a FormField from the others by setting its left margin on a left-aligned form, even if the FormPanel itself already specifies a border margin. The two values are added together in that case.
      Parameters:
      margin - The margin, in pixels, to apply to the FormPanel. Negative values are treated as 0.
      Returns:
      This FormPanel instance, to allow method chaining.

    • setBorderMargin

      public FormPanel setBorderMargin(Margins margins)
      Sets optional pixel margins for the FormPanel itself to keep it away from the edges of its container. The default value is zero, meaning no extra margins will be applied. Note that any value given here is added to whatever margins are already present on each individual FormField. This value does not replace those values. So, you can still indent a FormField from the others by setting its left margin on a left-aligned form, even if the FormPanel itself already specifies a border margin. The two values are added together in that case.

      Note: the Margins class defines an internalSpacing property. That property is ignored for FormPanel margin calculations. We only care about top, left, bottom, and right. "internalSpacing" is only relevant within individual FormField instances.

      Parameters:
      margins - The Margins instance defining the margins to apply. Negative values are treated as 0.
      Returns:
      This FormPanel instance, to allow method chaining.

    • getBorderMargin

      public Margins getBorderMargin()
      Returns the optional border margin to be applied as described in setBorderMargin. The actual instance is returned, so callers can modify individual properties.

    • getFormFields

      public List<FormField> getFormFields()
      Returns a copy of the list of FormFields contained in this panel. A copy of the list is returned to avoid client modification of the list itself.
      Returns:
      A copy of the list of form fields for this form panel.

    • getFormField

      public FormField getFormField(String identifier)
      Finds and returns a specific FormField by its identifier, if it exists. No validation of the FormField identifier is done in this class! If more than one FormField has the same identifier, this method will return whichever one it finds first. If a field does not have an identifier, it will not be considered by this method.
      Parameters:
      identifier - The field identifier to search for.
      Returns:
      A FormField matching that identifier, or null if not found.

    • findFormField

      public FormField findFormField(String identifier)
      Synonym for getFormField(String identifier).
      Parameters:
      identifier - The identifier to search for.
      Returns:
      A FormField matching that identifier, or null if not found.

    • removeAllFormFields

      public FormPanel removeAllFormFields()
      Removes all FormFields from this FormPanel and re-renders it.
      Returns:
      This FormPanel instance, to allow method chaining.

    • removeAll

      public void removeAll()
      Overridden here so we can also remove all FormField instances. This is effectively the same as calling removeAllFormFields() and it will trigger a re-render.
      Overrides:
      removeAll in class Container

    • setEnabled

      public void setEnabled(boolean enabled)
      Overridden here so we can enable/disable all FormField instances when we receive a setEnabled request.
      Overrides:
      setEnabled in class JComponent
      Parameters:
      enabled - true if this component should be enabled, false otherwise

    • add

      public FormPanel add(List<FormField> fields)
      Synonym for addAll(List<FormField> fields).

    • addAll

      public FormPanel addAll(List<FormField> fields)
      Adds the specified list of FormFields to this FormPanel.

    • add

      public FormPanel add(FormField field)
      Adds the specified FormField to this FormPanel.

    • getFieldCount

      public int getFieldCount()
      Returns the number of FormFields contained in this panel.

    • clearValidationResults

      public FormPanel clearValidationResults()
      Invoke this to clear the validation label off any previously validated field. Useful for when resetting a form to its initial state.

    • isFormValid

      public boolean isFormValid()
      Validates each FormField by invoking all FieldValidators that are attached to it, then returns the overall result. The return will be true if all FieldValidators for all FormFields validated successfully.

    • validateForm

      public FormPanel validateForm()
      Shorthand for isFormValid()

    • setAlignment

      public FormPanel setAlignment(Alignment alignment)
      Changes the Alignment property of this FormPanel and re-renders it.

    • getAlignment

      public Alignment getAlignment()
      Returns the Alignment property of this FormPanel.

    • forceRerender

      @Deprecated(since="swing-extras 2.7", forRemoval=true) public FormPanel forceRerender()
      Deprecated, for removal: This API element is subject to removal in a future version.
      As of swing-extras 2.7. This method will be removed in a future release.
      This is an obsolete method from an earlier version of swing-forms. It is scheduled for removal in a future release.

    • getMultiLineFieldExtraTopMargin

      public int getMultiLineFieldExtraTopMargin()
      Returns the extra top margin, in pixels, that will be applied to multi-line field labels to better align them with their associated field components.

    • setMultiLineFieldExtraTopMargin

      public FormPanel setMultiLineFieldExtraTopMargin(int multiLineFieldExtraTopMargin)
      There's a very slight misalignment issue with field labels on multi-line FormField implementations due to the way GridBagLayout anchors components. This property allows you to specify an extra top margin, in pixels, to be applied to multi-line field labels to better align them with their associated field components. The default value is 4 pixels, which is usually sufficient. You can set this to zero if you don't want any extra margin applied.
      Parameters:
      multiLineFieldExtraTopMargin - The extra top margin, in pixels, for multi-line field labels.
      Returns:
      This FormPanel instance, to allow method chaining.