Java Doc for JTextField.java in  » 6.0-JDK-Core » swing » javax » swing » Java Source Code / Java DocumentationJava Source Code and Java Documentation

JTextField is intended to be source-compatible with java.awt.TextField where it is reasonable to do so. This component has capabilities not found in the java.awt.TextField class. The superclass should be consulted for additional capabilities.

JTextField has a method to establish the string used as the command string for the action event that gets fired. The java.awt.TextField used the text of the field as the command string for the ActionEvent. JTextField will use the command string set with the setActionCommand method if not null, otherwise it will use the text of the field as a compatibility with java.awt.TextField.

The method setEchoChar and getEchoChar are not provided directly to avoid a new implementation of a pluggable look-and-feel inadvertently exposing password characters. To provide password-like services a separate class JPasswordField extends JTextField to provide this service with an independently pluggable look-and-feel.

The java.awt.TextField could be monitored for changes by adding a TextListener for TextEvent's. In the JTextComponent based components, changes are broadcasted from the model via a DocumentEvent to DocumentListeners. The DocumentEvent gives the location of the change and the kind of change if desired. The code fragment might look something like:

     DocumentListener myListener = ??;
     JTextField myArea = ??;
     myArea.getDocument().addDocumentListener(myListener);
 

The horizontal alignment of JTextField can be set to be left justified, leading justified, centered, right justified or trailing justified. Right/trailing justification is useful if the required size of the field text is smaller than the size allocated to it. This is determined by the setHorizontalAlignment and getHorizontalAlignment methods. The default is to be leading justified.

How the text field consumes VK_ENTER events depends on whether the text field has any action listeners. If so, then VK_ENTER results in the listeners getting an ActionEvent, and the VK_ENTER event is consumed. This is compatible with how AWT text fields handle VK_ENTER events. If the text field has no action listeners, then as of v 1.3 the VK_ENTER event is not consumed. Instead, the bindings of ancestor components are processed, which enables the default button feature of JFC/Swing to work.

Customized fields can easily be created by extending the model and changing the default model provided. For example, the following piece of code will create a field that holds only upper case characters. It will work even if text is pasted into from the clipboard or it is altered via programmatic changes.

  public class UpperCaseField extends JTextField {
  
      public UpperCaseField(int cols) {
          super(cols);
      }
  
      protected Document createDefaultModel() {
  	      return new UpperCaseDocument();
      }
  
      static class UpperCaseDocument extends PlainDocument {
  
          public void insertString(int offs, String str, AttributeSet a) 
  	          throws BadLocationException {
  
  	          if (str == null) {
  		      return;
  	          }
  	          char[] upper = str.toCharArray();
  	          for (int i = 0; i < upper.length; i++) {
  		      upper[i] = Character.toUpperCase(upper[i]);
  	          }
  	          super.insertString(offs, new String(upper), a);
  	      }
      }
  }
 

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder .
author:
   Timothy Prinzing
version:
   1.101 05/05/07
See Also:   JTextField.setActionCommand
See Also:   JPasswordField
See Also:   JTextField.addActionListener

Warning: If you subclass this do not create an anonymous inner class.

Setting the Action results in immediately changing all the properties described in Swing Components Supporting Action. Subsequently, the textfield's properties are automatically updated as the Action's properties change.

This method uses three other methods to set and help track the Action's property values. It uses the configurePropertiesFromAction method to immediately change the textfield's properties. To track changes in the Action's property values, this method registers the PropertyChangeListener returned by createActionPropertyChangeListener.

Refer to the table at Swing Components Supporting Action for a list of the properties this method sets.
Parameters:
  action - the Action associated with this textfield
Parameters:
  propertyName - the name of the property that changed
since:
   1.6
See Also:   Action
See Also:   JTextField.configurePropertiesFromAction

Warning: If you subclass this do not create an anonymous inner class. If you do the lifetime of the textfield will be tied to that of the Action.
Parameters:
  a - the textfield's action
since:
   1.3
See Also:   Action
See Also:   JTextField.setAction

• JTextField.LEFT
• JTextField.CENTER
• JTextField.RIGHT
• JTextField.LEADING
• JTextField.TRAILING

The fields look-and-feel implementation manages the values of the minimum, maximum, and extent properties on the BoundedRangeModel. the visibility
See Also:   BoundedRangeModel

Setting the Action results in immediately changing all the properties described in Swing Components Supporting Action. Subsequently, the textfield's properties are automatically updated as the Action's properties change.

This method uses three other methods to set and help track the Action's property values. It uses the configurePropertiesFromAction method to immediately change the textfield's properties. To track changes in the Action's property values, this method registers the PropertyChangeListener returned by createActionPropertyChangeListener. The default PropertyChangeListener invokes the actionPropertyChanged method when a property in the Action changes.
Parameters:
  a - the Action for the JTextField,or null
since:
   1.3
See Also:   Action
See Also:   JTextField.getAction
See Also:   JTextField.configurePropertiesFromAction
See Also:   JTextField.createActionPropertyChangeListener
See Also:   JTextField.actionPropertyChanged
See Also:   

• JTextField.LEFT
• JTextField.CENTER
• JTextField.RIGHT
• JTextField.LEADING
• JTextField.TRAILING