Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

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:

java.awt.image.ImageObserver, Scrollable, java.io.Serializable, SwingConstants

Direct Known Subclasses:

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.

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.

See Also:

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

Nested Class Summary

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

JTextComponent.KeyBinding

Field Summary

static java.lang.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

listenerList, TOOL_TIP_TEXT_KEY, 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, java.lang.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(java.lang.String text)
Constructs a new TextField initialized with the specified text.

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

Method Summary

void	addActionListener(java.awt.event.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 java.beans.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.
Action	getAction() Returns the currently set Action for this ActionEvent source, or null if no Action is set.
java.awt.event.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.
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.
void	paint(java.awt.Graphics g) Invoked by Swing to draw components.
protected void	paintBorder(java.awt.Graphics g) Paints the component's border.
protected void	paintComponent(java.awt.Graphics g) Calls the UI delegate's paint method, if the UI delegate is non-null.
void	paintComponents(java.awt.Graphics g)
protected java.lang.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.
protected void	printBorder(java.awt.Graphics g) Prints the component's border.
protected void	printComponent(java.awt.Graphics g) This is invoked during a printing operation.
void	printComponents(java.awt.Graphics g)
void	removeActionListener(java.awt.event.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(java.lang.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, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, viewToModel, write

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getSize, getToolTipText, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, isDoubleBuffered, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, paintChildren, paintImmediately, paintImmediately, print, printAll, printChildren, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDefaultLocale, setDoubleBuffered, setEnabled, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, areFocusTraversalKeysSet, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, list, list, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

addComponentListener, addFocusListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getCursor, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getSize, getToolkit, getTreeLock, hasFocus, imageUpdate, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, list, list, list, paintAll, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processMouseEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, setBounds, setBounds, setCursor, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

notifyAction

public static final java.lang.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.

See Also:

Constant Field Values

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(java.lang.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(java.lang.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,
                  java.lang.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:

java.lang.IllegalArgumentException - if columns < 0

Method Detail

setDocument

public void setDocument(Document doc)

Associates the editor with a text document. The currently registered factory is used to build a view for the document, which gets displayed by the editor after revalidation. A PropertyChange event ("document") is propagated to each listener.

Overrides:

setDocument in class JTextComponent

Parameters:

doc - the document to display/edit

See Also:

JTextComponent.getDocument()

isValidateRoot

public 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.

Overrides:

isValidateRoot in class JComponent

Returns:

if the parent of this textfield is a JViewPort return false, otherwise return true

See Also:

JComponent.revalidate(), JComponent.isValidateRoot()

getHorizontalAlignment

public int getHorizontalAlignment()

Returns the horizontal alignment of the text. Valid keys are:

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

Returns:

the horizontal alignment

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)

Sets the horizontal alignment of the text. Valid keys are:

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

invalidate and repaint are called when the alignment is set, and a PropertyChange event ("horizontalAlignment") is fired.

Parameters:

alignment - the alignment

Throws:

java.lang.IllegalArgumentException - if alignment 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.

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:

java.lang.IllegalArgumentException - if columns is less than 0

getColumnWidth

protected int getColumnWidth()

Returns 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 dimension of this textfield

See Also:

JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

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

See Also:

Component.getFont()

addActionListener

public void addActionListener(java.awt.event.ActionListener l)

Adds the specified action listener to receive action events from this textfield.

Parameters:

l - the action listener to be added

removeActionListener

public void removeActionListener(java.awt.event.ActionListener l)

Removes the specified action listener so that it no longer receives action events from this textfield.

Parameters:

l - the action listener to be removed

getActionListeners

public java.awt.event.ActionListener[] getActionListeners()

Returns an array of all the ActionListeners added to this JTextField with addActionListener().

Returns:

all of the ActionListeners added or an empty array if no listeners have been added

Since:

1.4

fireActionPerformed

protected void fireActionPerformed()

Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created. The listener list is processed in last to first order.

See Also:

EventListenerList

setActionCommand

public void setActionCommand(java.lang.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 independently 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 java.beans.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.

Parameters:

a - the Action from which to get the properties, or null

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, in pixels.

Returns:

the offset >= 0

setScrollOffset

public void setScrollOffset(int scrollOffset)

Sets the scroll offset, in pixels.

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

See Also:

JViewport

paramString

protected java.lang.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

paintComponent

protected final void paintComponent(java.awt.Graphics g)

Description copied from class: JComponent

Calls the UI delegate's paint method, if the UI delegate is non-null. We pass the delegate a copy of the Graphics object to protect the rest of the paint code from irrevocable changes (for example, Graphics.translate).

Overrides:

paintComponent in class JComponent

Parameters:

g - the Graphics object to protect

See Also:

JComponent.paint(java.awt.Graphics), ComponentUI

paintBorder

protected final void paintBorder(java.awt.Graphics g)

Description copied from class: JComponent

Paints the component's border.

Overrides:

paintBorder in class JComponent

Parameters:

g - the Graphics context in which to paint

See Also:

JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

paintComponents

public final void paintComponents(java.awt.Graphics g)

paint

public final void paint(java.awt.Graphics g)

Description copied from class: JComponent

Invoked by Swing to draw components. Applications should not invoke paint directly, but should instead use the repaint method to schedule the component for redrawing.

This method actually delegates the work of painting to three protected methods: paintComponent, paintBorder, and paintChildren. They're called in the order listed to ensure that children appear on top of component itself. Generally speaking, the component and its children should not paint in the insets area allocated to the border. Subclasses can just override this method, as always.

Overrides:

paint in class JComponent

Parameters:

g - the Graphics context in which to paint

See Also:

JComponent.paintBorder(java.awt.Graphics), JComponent.paintChildren(java.awt.Graphics), JComponent.getComponentGraphics(java.awt.Graphics), JComponent.repaint(long, int, int, int, int)

printComponent

protected final void printComponent(java.awt.Graphics g)

Description copied from class: JComponent

This is invoked during a printing operation. This is implemented to invoke paintComponent on the component.

Overrides:

printComponent in class JComponent

Parameters:

g - the Graphics context in which to paint

See Also:

JComponent.print(java.awt.Graphics)

printBorder

protected final void printBorder(java.awt.Graphics g)

Description copied from class: JComponent

Prints the component's border. This is implemented to invoke paintBorder on the component.

Overrides:

printBorder in class JComponent

Parameters:

g - the Graphics context in which to paint

See Also:

JComponent.print(java.awt.Graphics)

printComponents

public final void printComponents(java.awt.Graphics g)