Package jmri.util.swing

Class ValidatedTextField

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.text.JTextComponent
javax.swing.JTextField
jmri.util.swing.ValidatedTextField
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
public class ValidatedTextField extends JTextField
Extends JTextField to provide a data validation function and a colorization function.

Supports two types of validated field: a generic text fields with length and/or character set limited by a Java regular expression or an integral numeric field with minimum and maximum allowed values.

See Also:

  • Field Details

  • Constructor Details

    • ValidatedTextField

      public ValidatedTextField(Integer len, boolean forceUppercase, String validationRegExpr, String validationErrorMessage)
      Provides a validated text field, where the validation mechanism requires a String value which passes the matching defined in validationRegExpr .

      Validation occurs as part of the process of focus leaving the field. When validation fails, the focus remains within the field, and the field foreground and background colors are changed.

      When focus leaves the field and the field value is valid, the value will be checked against the "Last Queried Value". If the current field value matches the "Last Queried Value", the field is colored using the default field foreground and background colors. If instead the current field value does not match the "Last Queried Value", the field background color is changed to reflect that the value is not yet saved. Use the setLastQueriedValue(String) method to set the value for this comparison.

      Parameters:
      len - defines the width of the text field entry box, in characters
      forceUppercase - determines if all alphabetic characters are forced to uppercase
      validationRegExpr - defines a java regular expression which is used when validating the text input. A string such as "^[0-9]{2}[a-zA-Z]{3,4}$" would require the text field to be a 5 or 6 character string which starts with exactly two digits and followed by either 3 or 4 upper-case or lower-case letters
      validationErrorMessage - is passed as an argument to the property change listener for the instantiating class

    • ValidatedTextField

      public ValidatedTextField(Integer len, boolean allow0LengthValue, boolean forceUppercase, Integer minValue, Integer maxValue, String validationRegExpr, String validationErrorMessage)
      Provides a validated text field, where the validation mechanism requires a String value which passes the matching defined in validationRegExpr, and where the string begins with a number which must be within a specified integral range.

      Validation occurs as part of the process of focus leaving the field. When validation fails, the focus remains within the field, and the field foreground and background colors are changed.

      When focus leaves the field and the field value is valid, the value will be checked against the "Last Queried Value". If the current field value matches the "Last Queried Value", the field is colorized using the default field foreground and background colors. If instead the current field value does not match the "Last Queried Value", the field background color is changed to reflect that the value is not yet saved. Use the setLastQueriedValue() method to set the value for this comparison.

      Parameters:
      len - defines the width of the text field entry box, in characters.
      allow0LengthValue - determines if a value of 0 characters is allowed as a valid value.
      forceUppercase - determines if all alphabetic characters are forced to uppercase.
      minValue - is the smallest allowed value.
      maxValue - is the largest allowed value.
      validationRegExpr - defines a java regular expression which is used when validating the text input. A string such as "^[0-9]{2}[a-zA-Z]{3,4}$" would require the text field to be a 5 or 6 character string which starts with exactly two digits and followed by either 3 or 4 upper-case or lower-case letters.
      validationErrorMessage - is passed as an argument to the property change listener for the instantiating class.

    • ValidatedTextField

      public ValidatedTextField(Integer len, boolean allow0LengthValue, Integer minValue, Integer maxValue, String validationErrorMessage)
      Provides a validated text field for integral values, where the validation mechanism requires a numeric value between a minimum and maximum value.

      Validation occurs as part of the process of focus leaving the field. When validation fails, the focus remains within the field, and the field foreground and background colors are changed.

      When focus leaves the field and the field value is valid, the value will be checked against the "Last Queried Value". If the current field value matches the "Last Queried Value", the field is colored using the default field foreground and background colors. If instead the current field value does not match the "Last Queried Value", the field background color is changed to reflect that the value is not yet saved. Use the setLastQueriedValue() method to set the value for this comparison.

      Parameters:
      len - defines the width of the text field entry box, in characters
      allow0LengthValue - determines if a value of 0 characters is allowed as a valid value
      minValue - is the smallest allowed value
      maxValue - is the largest allowed value
      validationErrorMessage - is passed as an argument to the property change listener for the instantiating class.

    • ValidatedTextField

      public ValidatedTextField(Integer len, int minAcceptableVal, int maxAcceptableVal, String validationErrorMessage)
      Provide a validated text field, where the validation mechanism requires a Numeric value which is a hexadecimal value which is valid and within a given numeric range.

      Validation occurs as part of the process of focus leaving the field. When validation fails, the focus remains within the field, and the field foreground and background colors are changed.

      When focus leaves the field and the field value is valid, the value will be checked against the "Last Queried Value". If the current field value matches the "Last Queried Value", the field is colored using the default field foreground and background colors. If instead the current field value does not match the "Last Queried Value", the field background color is changed to reflect that the value is not yet saved. Use the setLastQueriedValue(String) method to set the value for this comparison.

      Parameters:
      len - the length of the field
      minAcceptableVal - defines the lowest acceptable value
      maxAcceptableVal - defines the lowest acceptable value
      validationErrorMessage - is passed as an argument to the property change listener for the instantiating class

  • Method Details

    • isValid

      public boolean isValid()
      Validate the field information. Does not make any GUI changes. A field value that is zero-length is considered invalid.
      Overrides:
      isValid in class Component
      Returns:
      true if current field information is valid; otherwise false

    • setLastQueriedValue

      public void setLastQueriedValue(String lastQueriedValue)
      Set the "Last Queried Value". This value is used by the colorization process when focus is exiting the field.
      Parameters:
      lastQueriedValue - the last value verified
      See Also:

    • getLastQueriedValue

      public String getLastQueriedValue()
      Retrieve the current value of the "Last Queried Value".
      Returns:
      the last value verified
      See Also:

    • setValidateRegExp

      public void setValidateRegExp(String validationRegExpr)
      Set the "validationRegExp".
      Parameters:
      validationRegExpr - new validation pattern
      See Also:

    • getValidateRegExp

      public String getValidateRegExp()
      Retrieve the current "validationRegExp". Used in eg. Add Turnout to attach a manager-specific pattern without redrawing the pane
      Returns:
      the current validation pattern
      See Also:

    • setInvalidBackgroundColor

      public void setInvalidBackgroundColor(Color c)
      Set the color used for the field background when the field value is invalid.
      Parameters:
      c - background Color to be used when the value is invalid