javax.swing
Class JTextField

java.lang.Object   
  java.awt.Component   
      java.awt.Container   
          javax.swing.JComponent   
              javax.swing.text.JTextComponent   
                  javax.swing.JTextField

All Implemented Interfaces:

ImageObserver , MenuContainer , Serializable , Accessible , Scrollable , SwingConstants

Direct Known Subclasses:

DefaultTreeCellEditor.DefaultTextField , JFormattedTextField , JPasswordField

public class JTextField
extends JTextComponent   
implements SwingConstants   

JTextField is a lightweight component that allows the editing of a single line of text. For information on and examples of using text fields, see How to Use Text Fields in The Java Tutorial.

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: 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 XMLEncoder .

See Also:

setActionCommand(java.lang.String) , JPasswordField , addActionListener(java.awt.event.ActionListener) , Serialized Form

Nested Class Summary

protected class

JTextField.AccessibleJTextField This class implements accessibility support for the JTextField class.

Nested classes/interfaces inherited from class javax.swing.text.JTextComponent

JTextComponent.AccessibleJTextComponent , JTextComponent.KeyBinding

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent , Component.BltBufferStrategy , Component.FlipBufferStrategy

Field Summary

static String

notifyAction Name of the action to send notification that the contents of the field have been accepted.

Fields inherited from class javax.swing.text.JTextComponent

DEFAULT_KEYMAP , FOCUS_ACCELERATOR_KEY

Fields inherited from class javax.swing.JComponent

accessibleContext , listenerList , TOOL_TIP_TEXT_KEY , ui , UNDEFINED_CONDITION , WHEN_ANCESTOR_OF_FOCUSED_COMPONENT , WHEN_FOCUSED , WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT , CENTER_ALIGNMENT , LEFT_ALIGNMENT , RIGHT_ALIGNMENT , TOP_ALIGNMENT

Fields inherited from interface javax.swing.SwingConstants

BOTTOM , CENTER , EAST , HORIZONTAL , LEADING , LEFT , NEXT , NORTH , NORTH_EAST , NORTH_WEST , PREVIOUS , RIGHT , SOUTH , SOUTH_EAST , SOUTH_WEST , TOP , TRAILING , VERTICAL , WEST

Fields inherited from interface java.awt.image.ImageObserver

ABORT , ALLBITS , ERROR , FRAMEBITS , HEIGHT , PROPERTIES , SOMEBITS , WIDTH

Constructor Summary

JTextField ()
Constructs a new TextField.

JTextField (Document doc, String text, int columns)
Constructs a new JTextField that uses the given text storage model and the given number of columns.

JTextField (int columns)
Constructs a new empty TextField with the specified number of columns.

JTextField (String text)
Constructs a new TextField initialized with the specified text.

JTextField (String text, int columns)
Constructs a new TextField initialized with the specified text and columns.

Method Summary

void	addActionListener (ActionListener l) Adds the specified action listener to receive action events from this textfield.
protected void	configurePropertiesFromAction (Action a) Factory method which sets the ActionEvent source's properties according to values from the Action instance.
protected PropertyChangeListener	createActionPropertyChangeListener (Action a) Factory method which creates the PropertyChangeListener used to update the ActionEvent source as properties change on its Action instance.
protected Document	createDefaultModel () Creates the default implementation of the model to be used at construction if one isn't explicitly given.
protected void	fireActionPerformed () Notifies all listeners that have registered interest for notification on this event type.
AccessibleContext	getAccessibleContext () Gets the AccessibleContext associated with this JTextField.
Action	getAction () Returns the currently set Action for this ActionEvent source, or null if no Action is set.
ActionListener []	getActionListeners () Returns an array of all the ActionListeners added to this JTextField with addActionListener().
Action []	getActions () Fetches the command list for the editor.
int	getColumns () Returns the number of columns in this TextField.
protected int	getColumnWidth () Returns the column width.
int	getHorizontalAlignment () Returns the horizontal alignment of the text.
BoundedRangeModel	getHorizontalVisibility () Gets the visibility of the text field.
Dimension	getPreferredSize () Returns the preferred size Dimensions needed for this TextField.
int	getScrollOffset () Gets the scroll offset, in pixels.
String	getUIClassID () Gets the class ID for a UI.
boolean	isValidateRoot () Calls to revalidate that come from within the textfield itself will be handled by validating the textfield, unless the textfield is contained within a JViewport, in which case this returns false.
protected String	paramString () Returns a string representation of this JTextField.
void	postActionEvent () Processes action events occurring on this textfield by dispatching them to any registered ActionListener objects.
void	removeActionListener (ActionListener l) Removes the specified action listener so that it no longer receives action events from this textfield.
void	scrollRectToVisible (Rectangle r) Scrolls the field left or right.
void	setAction (Action a) Sets the Action for the ActionEvent source.
void	setActionCommand (String command) Sets the command string used for action events.
void	setColumns (int columns) Sets the number of columns in this TextField, and then invalidate the layout.
void	setDocument (Document doc) Associates the editor with a text document.
void	setFont (Font f) Sets the current font.
void	setHorizontalAlignment (int alignment) Sets the horizontal alignment of the text.
void	setScrollOffset (int scrollOffset) Sets the scroll offset, in pixels.

Methods inherited from class javax.swing.text.JTextComponent

addCaretListener , addInputMethodListener , addKeymap , copy , cut , fireCaretUpdate , getCaret , getCaretColor , getCaretListeners , getCaretPosition , getDisabledTextColor , getDocument , getDragEnabled , getFocusAccelerator , getHighlighter , getInputMethodRequests , getKeymap , getKeymap , getMargin , getNavigatio