Class VTextField

All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
Direct Known Subclasses:
TimeTextField, WholeNumbTextField

public class VTextField extends JTextField
Verified Text field. This class implements a text field that handles invalid text according to an error policy and that calls a method onAccepted() when text is valid and either the focus changes or the text was changed by calling setText(String), or when the user presses a key such as the "Enter"/"Return" key. The method handleError() is called when input verification fails after the keyboard focus is lost, but not after setText(String) is called and input verification fails. The default behavior for handleError() (if there is an error) simply restores the previous value and (if possible) keeps the keyboard focus on the text field.

To configure this text field to verify its contents, one must call the method setInputVerifier(InputVerifier). To restrict the input to particular characters, this text field's document should be a subclass of AbstractDocument and the document's AbstractDocument.setDocumentFilter(javax.swing.text.DocumentFilter) should be called. If a document filter is used, illegal characters must not be included in a string passed to JTextComponent.setText(String) as the the new text will be ignored. Characters that will be illegal once a document filter is installed can be passed to a contructor, but doing this can result in unexpected behavior if JTextComponent.getText() is called and that text is reused in calls to JTextComponent.setText(String). Consequently, it is advisable for strings passed to the constructor to contain only characters that will be allowable after the document filter is installed.

See Also:
  • Constructor Details

    • VTextField

      public VTextField(int ncols)
      Class constructor specifying the field size..
      Parameters:
      ncols - the number of columns in the text field.
    • VTextField

      public VTextField()
      Class constructor.
    • VTextField

      public VTextField(String text)
      Class constructor giving an initial string.
      Parameters:
      text - the initial text
    • VTextField

      public VTextField(String text, int ncols)
      Class constructor giving an initial string and field size.
      Parameters:
      text - the initial text
      ncols - the number of columns in the text field.
    • VTextField

      public VTextField(Document doc, String text, int ncols)
      Class constructor for a document model, initial string and field size.
      Parameters:
      doc - the document model
      text - the initial text
      ncols - the number of columns in the text field.
  • Method Details

    • setErrorPolicy

      public void setErrorPolicy(VTextField.ErrorPolicy ep) throws IllegalStateException
      Set the error policy
      Parameters:
      ep - the error policy
      Throws:
      IllegalStateException - empty text fields allowed, but the argument was ErrorPolicy.CLEAR_VALUE
      See Also:
    • handleError

      protected boolean handleError()
      Handle an error. If this method is overridden it should return true only if it has attempted to correct the error. Correcting the error will typically require calling setText(String) with the corrected value (this method will check its argument).
      Returns:
      return true if a value has been provided; false to keep the old value.
      See Also:
    • onAccepted

      protected void onAccepted() throws Exception
      Accept input. This method will be called when input is accepted, either by terminating the input with the "Enter" or "Return" key, or by changing the focus to another component in this application. Note that selecting a window in a separate application may not trigger this method.

      The default method does nothing, but may be overridden to perform some operation when the value of the text field changes to a new accepted value. During error correction, this may happen multiple times. It can also happen if the method setText(String) is called. While this method can throw an exception, it is called in such a way that the exception will normally be caught by this class' methods and processed silently if at all.

      When an instance of this class is constructed and the text field is empty, an initial call to this method is suppressed.

      Throws:
      Exception - an error occurred
    • setText

      public void setText(String str)
      Set the text field if the field would be accepted. As a special case, when getAllowEmptyTextField() returns truethe text may be set to an empty string in order to clear the field. Otherwise, if the input is valid, onAccepted() will be called, but if the text is not valid, the existing value will be preserved. The method onAccepted() must handle the case where the text field is empty when getAllowEmptyTextField() returns true.

      If the input is not valid, as determined by the value of getAllowEmptyTextField() or by an input verifier, the previous value is preserved.

      While the method onAccepted() is being called, this method simply sets the text with no constraints on its value. In this case, the caller must ensure that the argument is a valid one.

      Overrides:
      setText in class JTextComponent
      Parameters:
      str - the value for the string.
      Throws:
      IllegalArgumentException - The input is not valid
    • setAllowEmptyTextField

      public void setAllowEmptyTextField(boolean value) throws IllegalStateException
      Set whether or not empty text fields are allowed. The default setting is true. This method affects how text is accepted. Fields may be temporarily empty while editing them. In addition, a field may be empty when an instance of this class is constructed, in which case onAccepted() will not be called until the text is changed.
      Parameters:
      value - true if empty text fields are allowed; false otherwise
      Throws:
      IllegalStateException
    • getAllowEmptyTextField

      public boolean getAllowEmptyTextField()
      Determine if empty text fields are allowed.
      Returns:
      true if empty text fields are allowed; false otherwise.
    • getValidatedText

      public String getValidatedText()
      Get the text field. This does a validity test and if the text is not valid, the old value is used. If handleError is overridden, the value may be corrected if not valid.

      The method onAccepted() will be called if the input is valid. If this method is called when the text field is empty and when getAllowEmptyTextField() returns false, handleError() will be called.

      Returns:
      the text displayed if it is valid; otherwise the text before the last editing operation.
    • fireActionPerformed

      protected void fireActionPerformed()
      Overrides:
      fireActionPerformed in class JTextField
    • removeActionListener

      public void removeActionListener(ActionListener listener)
      Overrides:
      removeActionListener in class JTextField
    • setInputVerifier

      public void setInputVerifier(InputVerifier verifier)
      Set the input verifier. This should be used to determine the validity of the text field's contents. An internal input verifier is actually used and that input verifier uses the one set by this method, with the internal verifier handling some aspects of a change of focus.
      Overrides:
      setInputVerifier in class JComponent
      Parameters:
      verifier - the input verifier; null if the input should always be accepted.