Package ca.corbett.forms.fields

Class FormField

java.lang.Object
ca.corbett.forms.fields.FormField
Direct Known Subclasses:
CheckBoxField, ColorField, ComboField, FileField, FontField, ImagePanelFormField, LabelField, ListField, LogoFormField, LongTextField, NumberField, PanelField, ShortTextField, WaveformConfigField, WaveformPanelFormField
public abstract class FormField extends Object
FormField is an abstract base class which allows for the creation of a form field that wraps one or more Java Swing UI components. Most FormFields ultimately wrap a single Java Swing UI component - for example, TextField wraps a JTextComponent, CheckBoxField wraps a JCheckBox, and so on. However, it's possible to wrap multiple UI components into a single FormField implementation - for example, FileField wraps a text box for displaying the currently selected file or directory, and also a JButton for launching a file chooser dialog.

FormField is designed with extensibility in mind! If you need a specific type of form field that isn't represented by any of the provided implementation classes, you can build your own FormField by extending this class and wrapping whatever UI components you need. Alternatively, you can use PanelField, which wraps an empty JPanel that you can populate with whatever UI components you need.

Validating a FormField

You can use addFieldValidator() to add any number of FieldValidator instances to the FormField. When the containing FormPanel is validated, all the validators on the FormField will be executed, and the results will automatically be displayed in a validation label next to the FormField. Helpful tooltip text will be provided so that the user understands why the field failed to validate.

Responding to field value changes

Often it's handy to be able to respond to form field changes as they are made, rather than waiting until the form is validated and submitted. For example, you might want to control the visibility of field B depending on what value is contained in field A. You can do this by using addValueChangedListener() and responding to the change events as they happen.
Since:
2019-11-23
Author:
scorbo2

  • Field Details

    • DEFAULT_FONT

      protected static final Font DEFAULT_FONT

    • defaultFont

      protected static Font defaultFont

    • valueChangedListeners

      protected final List<ValueChangedListener> valueChangedListeners

    • fieldValidators

      protected final List<FieldValidator<? extends FormField>> fieldValidators

    • identifier

      protected String identifier

    • fieldLabel

      protected final JLabel fieldLabel

    • fieldComponent

      protected JComponent fieldComponent

    • validationLabel

      protected final JLabel validationLabel

    • helpLabel

      protected final JLabel helpLabel

    • margins

      protected final Margins margins

    • isVisible

      protected boolean isVisible

    • isEnabled

      protected boolean isEnabled

    • extraAttributes

      protected final Map<String,Object> extraAttributes

  • Constructor Details

    • FormField

      public FormField()

  • Method Details

    • hasValidationLabel

      public boolean hasValidationLabel()
      By default, all FormFields will show a validation label when validation results are available. Some descendant classes might override this method to return false if a validation label is not applicable (for example, for a LabelField).

      It is strongly recommended that even if a FormField implementing class does not want to show the validation label, it should still return true here if one or more FieldValidator instances have been added to this field. Otherwise, validation errors on the field won't be visible to the user. Suggested implementation for such cases: 

      return !fieldValidators.isEmpty();

    • isMultiLine

      public boolean isMultiLine()
      By default, FormFields occupy a single "line", or row, on the form. However, some FormFields may have a field component that spans multiple lines, like a multi-line text box, or a list, or a custom panel. Descendant classes can override the default false value here. It controls the placement of the field label. For tall form fields, the field label will be anchored to the top-left of its area.

    • shouldExpand

      public boolean shouldExpand()
      By default, FormPanel will allocate only the space that the field component requires. Descendant classes can override the default false value here to indicate that their field component should be allowed to expand as much space as is available to it. For example: PanelField.

    • hasHelpLabel

      public boolean hasHelpLabel()
      Any FormField that has help text set will return true here to indicate that a help label is available. If help text is unset, will return false;

    • hasFieldLabel

      public boolean hasFieldLabel()
      A FormField can have an associated field label which describes the field. To enable this, simply set the fieldLabel's text to a non-blank value. Setting the fieldLabel text to blank or empty will cause this method to return false, indicating the field does not have or want a fieldLabel. For example, a CheckBox field likely does not require an explicit field label, because the checkbox control itself contains a label.

    • getFieldLabel

      public JLabel getFieldLabel()

    • setFieldLabelFont

      public void setFieldLabelFont(Font font)

    • getDefaultFont

      public static Font getDefaultFont()
      Returns the prototype Font that will be used in all new FormField constructors. There is a built-in default value which can be overridden via setDefaultFont().

    • setDefaultFont

      public static void setDefaultFont(Font newFont)
      Sets the default Font to use with all FormField instances created after this call completes. This does not affect any FormField instance that was instantiated before this call. Passing null will revert this property to FormField.DEFAULT_FONT.

    • addFieldValidator

      public FormField addFieldValidator(FieldValidator<? extends FormField> validator)
      Adds a FieldValidator to this FormField.

    • removeFieldValidator

      public void removeFieldValidator(FieldValidator<FormField> validator)
      Removes the given FieldValidator from this FormField.

    • removeAllFieldValidators

      public void removeAllFieldValidators()
      Remove all validators from this FormField.

    • addValueChangedListener

      public FormField addValueChangedListener(ValueChangedListener listener)
      Adds a value changed listener that will be invoked when the field value is changed.

    • removeValueChangedListener

      public void removeValueChangedListener(ValueChangedListener listener)
      Removes the given value changed listener from this FormField.

    • getValidationLabel

      public JLabel getValidationLabel()
      Returns the validation label for this FormField. This is needed by FormPanel in the render() method.

    • getHelpText

      public String getHelpText()
      Returns the help text associated with this field, if any is set.

    • setHelpText

      public FormField setHelpText(String helpText)
      Sets optional help text for this field. If present, the field may show the helpLabel to allow the user to get help for the field. Note that some fields may decide not to render the helpLabel even if helpText is set for the field.

    • getHelpLabel

      public JLabel getHelpLabel()
      Returns the help label for this FormField. This is needed by FormPanel in the render() method.
      Returns:
      A JLabel.

    • setMargins

      public FormField setMargins(Margins margins)

    • getMargins

      public Margins getMargins()

    • setVisible

      public void setVisible(boolean visible)
      Sets the visibility status of all components of this field.
      Parameters:
      visible - Whether to show or hide.

    • isVisible

      public boolean isVisible()
      Reports whether this FormField is visible.

    • setEnabled

      public void setEnabled(boolean enabled)
      Enables or disables all components in this field.
      Parameters:
      enabled - whether to enable or disable the components.

    • isEnabled

      public boolean isEnabled()

    • setIdentifier

      public FormField setIdentifier(String id)
      Sets an internal String identifier for this field. Never shown to the user.
      Parameters:
      id - Any String which hopefully uniquely identifies this field. No validity checks.

    • getIdentifier

      public String getIdentifier()
      Returns the internal String identifier for this field, if one is set.
      Returns:
      A String identifier for this field, or null if not set.

    • getFieldComponent

      public JComponent getFieldComponent()
      Returns the actual JComponent that is wrapped by this field.
      Returns:
      The JComponent that this field wraps.

    • setExtraAttribute

      public FormField setExtraAttribute(String name, Object value)
      Set an arbitrary extra attribute to this form field. The given value is not validated nor used within this class. It's just extra data that can be attached by the caller.
      Parameters:
      name - The unique name of the value to set. Will overwrite any previous value by that name.
      value - The value to set.

    • getExtraAttribute

      public Object getExtraAttribute(String name)
      Returns a named extra attribute's value, if it exists.
      Parameters:
      name - The unique name of the value in question.
      Returns:
      The value associated with that name, or null if no such value.

    • clearExtraAttributes

      public void clearExtraAttributes()
      Removes all extra attributes and their associated values from this FormField.

    • clearExtraAttribute

      public void clearExtraAttribute(String name)
      Removes the value for the named extra attribute.
      Parameters:
      name - The unique name of the attribute in question.

    • setAllExtraAttributes

      public FormField setAllExtraAttributes(Map<String,Object> newAttributes)
      Clears any extra attributes currently held by this form field and then accepts the given list of attributes.
      Parameters:
      newAttributes - A map of String name to some arbitrary Object value.

    • addAllExtraAttributes

      public FormField addAllExtraAttributes(Map<String,Object> newAttributes)
      Adds the map of extra attributes to our existing list. Any name conflicts will result in the existing values being overwritten by the new values.
      Parameters:
      newAttributes - A map of String name to some arbitrary Object value.

    • clearValidationResults

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

    • validate

      public boolean validate()
      Asks all registered FieldValidators (if any) to check the current value of this field to make sure it's valid. If no FieldValidators are registered, then the field is valid by default (i.e. no checking is done). If any validator returns false, then this method will return false.

      Updating the UI: this method will make the validation label to the right of the FormField visible automatically and will set its icon as appropriate. Tooltip text will be available in the case of a failed validation, to explain why the field is invalid.

      Returns:
      True if the field value is valid according to all our validators, false otherwise.

    • isValid

      public boolean isValid()
      Shorthand for validate()
      Returns:
      see validate()

    • preRender

      public void preRender(JPanel container)
      Invoke before rendering this FormField to a container, in case the FormField needs to do some initialization specific to its new container (for example, matching the container's background color or using the container as a parent component for a popup dialog). The default implementation here does nothing. Overriding this method is optional.

    • fireValueChangedEvent

      protected void fireValueChangedEvent()
      Invoked internally to notify all registered actions about a change in the value of this field. If you are extending FormField to create your own implementation, you can invoke this to easily notify all listeners that the value in your field has changed.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object