Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  Accessible, ImageObserver, MenuContainer, Scrollable, Serializable, SwingConstants

Direct Known Subclasses:
  DefaultTreeCellEditor.DefaultTextField, 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.

For the keyboard keys used by this component in the standard Look and Feel (L&F) renditions, see the JTextField key assignments.

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. A future release of Swing will provide support for long term persistence.

See Also:
  `setActionCommand(java.lang.String)`, `JPasswordField`, `addActionListener(java.awt.event.ActionListener)`, Serialized Form

Inner Class Summary
`protected class` | `JTextField.AccessibleJTextField` This class implements accessibility support for the `JTextField` class.

Inner classes inherited from class javax.swing.text.JTextComponent
`JTextComponent.AccessibleJTextComponent, JTextComponent.KeyBinding`

Inner classes inherited from class javax.swing.JComponent
`JComponent.AccessibleJComponent`

Inner classes inherited from class java.awt.Container
`Container.AccessibleAWTContainer`

Inner classes inherited from class java.awt.Component
`Component.AccessibleAWTComponent`

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, NORTH, NORTH_EAST, NORTH_WEST, 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.
`Action[]` | `getActions()` Fetches the command list for the editor.
`int` | `getColumns()` Returns the number of columns in this TextField.
`protected int` | `getColumnWidth()` Gets 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.
`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 receiver 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` | `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.

Methods inherited from class javax.swing.text.JTextComponent
`addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretPosition, getDisabledTextColor, getDocument, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getPreferredScrollableViewportSize, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getUI, isEditable, isFocusTraversable, loadKeymap, modelToView, moveCaretPosition, paste, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setDocument, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write`

Methods inherited from class javax.swing.JComponent
`addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getVerifyInputWhenFocusTarget, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, hide, isDoubleBuffered, isFocusCycleRoot, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processFocusEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update`

Methods inherited from class java.awt.Container
`add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setLayout, validate, validateTree`

Methods inherited from class java.awt.Component
`action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getInputContext, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### notifyAction

    public static final String notifyAction

  Name of the action to send notification that the contents of the field have been accepted. Typically this is bound to a carriage-return.

Constructor Detail

### JTextField

    public JTextField()

  Constructs a new TextField. A default model is created, the initial string is null, and the number of columns is set to 0.

### JTextField

    public JTextField(String text)

  Constructs a new TextField initialized with the specified text. A default model is created and the number of columns is 0.
  Parameters:
    `text` - the text to be displayed, or null

### JTextField

    public JTextField(int columns)

  Constructs a new empty TextField with the specified number of columns. A default model is created and the initial string is set to null.
  Parameters:
    `columns` - the number of columns to use to calculate the preferred width. If columns is set to zero, the preferred width will be whatever naturally results from the component implementation.

### JTextField

    public JTextField(String text,
                      int columns)

  Constructs a new TextField initialized with the specified text and columns. A default model is created.
  Parameters:
    `text` - the text to be displayed, or null
    `columns` - the number of columns to use to calculate the preferred width. If columns is set to zero, the preferred width will be whatever naturally results from the component implementation.

### JTextField

    public JTextField(Document doc,
                      String text,
                      int columns)

  Constructs a new JTextField that uses the given text storage model and the given number of columns. This is the constructor through which the other constructors feed. If the document is null, a default model is created.
  Parameters:
    `doc` - the text storage to use. If this is null, a default will be provided by calling the createDefaultModel method.
    `text` - the initial string to display, or null
    `columns` - the number of columns to use to calculate the preferred width >= 0. If columns is set to zero, the preferred width will be whatever naturally results from the component implementation.
  Throws:
    `IllegalArgumentException` - if columns < 0

Method Detail

### getUIClassID

    public String getUIClassID()

  Gets the class ID for a UI.
  Overrides:
    `getUIClassID` in class `JComponent`
  Returns:
    the ID ("TextFieldUI")
  See Also:
    `JComponent.getUIClassID()`, `UIDefaults.getUI(javax.swing.JComponent)`

### isValidateRoot

    public boolean isValidateRoot()

  Calls to revalidate that come from within the textfield itself will be handled by validating the textfield, unless the receiver is contained within a JViewport, in which case this returns false.
  Overrides:
    `isValidateRoot` in class `JComponent`
  See Also:
    `JComponent.revalidate()`, `JComponent.isValidateRoot()`

### getHorizontalAlignment

    public int getHorizontalAlignment()

  Returns the horizontal alignment of the text. Valid keys: JTextField.LEFT, JTextField.CENTER, JTextField.RIGHT, JTextField.LEADING and JTextField.TRAILING
  Returns:
    the alignment

### setHorizontalAlignment

    public void setHorizontalAlignment(int alignment)

  Sets the horizontal alignment of the text. Valid keys: JTextField.LEFT, JTextField.CENTER, JTextField.RIGHT, JTextField.LEADING (the default) and JTextField.TRAILING. invalidate() and repaint() are called when the alignment is set, and a PropertyChange event ("horizontalAlignment") is fired.
  Parameters:
    `alignment` - the alignment
  Throws:
    `IllegalArgumentException` - if the alignment specified is not a valid key.

### createDefaultModel

    protected Document createDefaultModel()

  Creates the default implementation of the model to be used at construction if one isn't explicitly given. An instance of PlainDocument is returned.
  Returns:
    the default model implementation

### getColumns

    public int getColumns()

  Returns the number of columns in this TextField.
  Returns:
    the number of columns >= 0

### setColumns

    public void setColumns(int columns)

  Sets the number of columns in this TextField, and then invalidate the layout.
  Parameters:
    `columns` - the number of columns >= 0
  Throws:
    `IllegalArgumentException` - if columns is less than 0

### getColumnWidth

    protected int getColumnWidth()

  Gets the column width. The meaning of what a column is can be considered a fairly weak notion for some fonts. This method is used to define the width of a column. By default this is defined to be the width of the character m for the font used. This method can be redefined to be some alternative amount
  Returns:
    the column width >= 1

### getPreferredSize

    public Dimension getPreferredSize()

  Returns the preferred size Dimensions needed for this TextField. If a non-zero number of columns has been set, the width is set to the columns multiplied by the column width.
  Overrides:
    `getPreferredSize` in class `JComponent`
  Returns:
    the dimensions

### setFont

    public void setFont(Font f)

  Sets the current font. This removes cached row height and column width so the new font will be reflected. revalidate() is called after setting the font.
  Overrides:
    `setFont` in class `JComponent`
  Parameters:
    `f` - the new font

### addActionListener

    public void addActionListener(ActionListener l)

  Adds the specified action listener to receive action events from this textfield.
  Parameters:
    `l` - the action listener

### removeActionListener

    public void removeActionListener(ActionListener l)

  Removes the specified action listener so that it no longer receives action events from this textfield.
  Parameters:
    `l` - the action listener

### fireActionPerformed

    protected void fireActionPerformed()

  Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method. The listener list is processed in last to first order.
  See Also:
    `EventListenerList`

### setActionCommand

    public void setActionCommand(String command)

  Sets the command string used for action events.
  Parameters:
    `command` - the command string

### setAction

    public void setAction(Action a)

  Sets the Action for the ActionEvent source. The new Action replaces any previously set Action but does not affect ActionListeners independantly added with addActionListener(). If the Action is already a registered ActionListener for the ActionEvent source, it is not re-registered. A side-effect of setting the Action is that the ActionEvent source's properties are immediately set from the values in the Action (performed by the method configurePropertiesFromAction()) and subsequently updated as the Action's properties change (via a PropertyChangeListener created by the method createActionPropertyChangeListener().
  Parameters:
    `a` - the Action for the JTextField, or null.
  Since:
    1.3
  See Also:
    `Action`, `getAction()`, `configurePropertiesFromAction(javax.swing.Action)`, `createActionPropertyChangeListener(javax.swing.Action)`

### getAction

    public Action getAction()

  Returns the currently set Action for this ActionEvent source, or null if no Action is set.
  Returns:
    the Action for this ActionEvent source, or null.
  Since:
    1.3
  See Also:
    `Action`, `setAction(javax.swing.Action)`

### configurePropertiesFromAction

    protected void configurePropertiesFromAction(Action a)

  Factory method which sets the ActionEvent source's properties according to values from the Action instance. The properties which are set may differ for subclasses. By default, the properties which get set are Enabled and ToolTipText.
  Parameters:
    `a` - the Action from which to get the properties, or null
  Since:
    1.3
  See Also:
    `Action`, `setAction(javax.swing.Action)`

### createActionPropertyChangeListener

    protected PropertyChangeListener createActionPropertyChangeListener(Action a)

  Factory method which creates the PropertyChangeListener used to update the ActionEvent source as properties change on its Action instance. Subclasses may override this in order to provide their own PropertyChangeListener if the set of properties which should be kept up to date differs from the default properties (Text, Enabled, ToolTipText). Note that PropertyChangeListeners should avoid holding strong references to the ActionEvent source, as this may hinder garbage collection of the ActionEvent source and all components in its containment hierarchy.
  Since:
    1.3
  See Also:
    `Action`, `setAction(javax.swing.Action)`

### getActions

    public Action[] getActions()

  Fetches the command list for the editor. This is the list of commands supported by the plugged-in UI augmented by the collection of commands that the editor itself supports. These are useful for binding to events, such as in a keymap.
  Overrides:
    `getActions` in class `JTextComponent`
  Returns:
    the command list

### postActionEvent

    public void postActionEvent()

  Processes action events occurring on this textfield by dispatching them to any registered ActionListener objects. This is normally called by the controller registered with textfield.

### getHorizontalVisibility

    public BoundedRangeModel getHorizontalVisibility()

  Gets the visibility of the text field. This can be adjusted to change the location of the visible area if the size of the field is greater than the area that was allocated to the field. The fields look-and-feel implementation manages the values of the minimum, maximum, and extent properties on the BoundedRangeModel.
  Returns:
    the visibility
  See Also:
    `BoundedRangeModel`

### getScrollOffset

    public int getScrollOffset()

  Gets the scroll offset.
  Returns:
    the offset >= 0

### setScrollOffset

    public void setScrollOffset(int scrollOffset)

  Sets the scroll offset.
  Parameters:
    `scrollOffset` - the offset >= 0

### scrollRectToVisible

    public void scrollRectToVisible(Rectangle r)

  Scrolls the field left or right.
  Overrides:
    `scrollRectToVisible` in class `JComponent`
  Parameters:
    `r` - the region to scroll

### paramString

    protected String paramString()

  Returns a string representation of this JTextField. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be `null`.
  Overrides:
    `paramString` in class `JTextComponent`
  Returns:
    a string representation of this JTextField.

### getAccessibleContext

    public AccessibleContext getAccessibleContext()

  Gets the AccessibleContext associated with this JTextField. For JTextFields, the AccessibleContext takes the form of an AccessibleJTextField. A new AccessibleJTextField instance is created if necessary.
  Overrides:
    `getAccessibleContext` in class `JTextComponent`
  Returns:
    an AccessibleJTextField that serves as the AccessibleContext of this JTextField

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2001 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.