javax.swing
Class JTextField

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

public class JTextField

extends javax.swing.text.JTextComponent

implements javax.swing.SwingConstants

JTextField is a lightweight component that allows the editing of a single line of text. It 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 inadvertantly exposing password characters. To provide password-like services a seperate class JPasswordField extends JTextField to provide this service with an independantly 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, centered, or right justified 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 left justified.

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

For compatibility with java.awt.TextField, the VK_ENTER key fires the ActionEvent to the registered ActionListeners. However, awt didn't have default buttons like swing does. If a text field has focus and the VK_ENTER key is pressed, it will fire the fields ActionEvent rather than activate the default button. To disable the compatibility with awt for text fields, the following code fragment will remove the binding of VK_ENTER from the default keymap used by all JTextFields if that is desired.

static {
JTextField f = new JTextField();
KeyStroke enter = KeyStroke.getKeyStroke(KeyEvent.VK_ENTER, 0);
Keymap map = f.getKeymap();
map.removeKeyStrokeBinding(enter);
}

 

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, Serialized Form

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

javax.swing.text.JTextComponent.AccessibleJTextComponent, javax.swing.text.JTextComponent.KeyBinding

Inner classes inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

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

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

Constructor Summary

JTextField()
Constructs a new TextField.

JTextField(javax.swing.text.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.
javax.accessibility.AccessibleContext	getAccessibleContext() Get the AccessibleContext associated with this JTextField.
javax.swing.Action[]	getActions() Fetches the command list for the editor.
int	getColumns() Returns the number of columns in this TextField.
int	getHorizontalAlignment() Returns the horizontal alignment of the text.
javax.swing.BoundedRangeModel	getHorizontalVisibility() Gets the visibility of the text field.
java.awt.Dimension	getPreferredSize() Returns the preferred size Dimensions needed for this TextField.
int	getScrollOffset() Gets the scroll offset.
java.lang.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.
void	postActionEvent() Processes action events occurring on this textfield by dispatching them to any registered ActionListener objects.
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(java.awt.Rectangle r) Scrolls the field left or right.
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	setFont(java.awt.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, addKeymap, copy, cut, 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, isOpaque, loadKeymap, modelToView, moveCaretPosition, paste, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setDocument, setEditable, setEnabled, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setOpaque, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInsets, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, paint, paintImmediately, paintImmediately, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setForeground, setMaximumSize, setMinimumSize, setNextFocusableComponent, setPreferredSize, setRequestFocusEnabled, setToolTipText, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, remove, remove, removeAll, removeContainerListener, setLayout, validate

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, bounds, checkImage, checkImage, contains, createImage, createImage, disable, dispatchEvent, enable, enable, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getInputContext, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, 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, printAll, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, 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

equals, 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.

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(javax.swing.text.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

getUIClassID

public java.lang.String getUIClassID()

Gets the class ID for a UI.

Returns:

the ID ("TextFieldUI")

Overrides:

getUIClassID in class javax.swing.JComponent

See Also:

JComponent.getUIClassID(), UIDefaults#getUI

isValidateRoot

public boolean isValidateRoot()

Calls to revalidate that come from within the textfield itself will be handled by validating the textfield.

Overrides:

isValidateRoot in class javax.swing.JComponent

See Also:

JComponent.revalidate(), JComponent.isValidateRoot()

getHorizontalAlignment

public int getHorizontalAlignment()

Returns the horizontal alignment of the text. Valid keys: JTextField.LEFT (the default), JTextField.CENTER, JTextField.RIGHT.

Returns:

the alignment

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)

Sets the horizontal alignment of the text. Valid keys: JTextField.LEFT (the default), JTextField.CENTER, JTextField.RIGHT. 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 the alignment specified is not a valid key.

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

getPreferredSize

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

Returns:

the dimensions

Overrides:

getPreferredSize in class javax.swing.JComponent

setFont

public void setFont(java.awt.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.

Parameters:

f - the new font

Overrides:

setFont in class javax.swing.JComponent

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

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

setActionCommand

public void setActionCommand(java.lang.String command)

Sets the command string used for action events.

Parameters:

command - the command string

getActions

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

Returns:

the command list

Overrides:

getActions in class javax.swing.text.JTextComponent

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 javax.swing.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(java.awt.Rectangle r)

Scrolls the field left or right.

Parameters:

r - the region to scroll

Overrides:

scrollRectToVisible in class javax.swing.JComponent

getAccessibleContext

public javax.accessibility.AccessibleContext getAccessibleContext()

Get the AccessibleContext associated with this JTextField. Creates a new context if necessary.

Returns:

the AccessibleContext of this JTextField

Overrides:

getAccessibleContext in class javax.swing.text.JTextComponent