- All Implemented Interfaces:
ImageObserver,MenuContainer,Serializable,Accessible,Scrollable,SwingConstants
- Direct Known Subclasses:
DefaultTreeCellEditor.DefaultTextField,JFormattedTextField,JPasswordField
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: 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
has been added to the java.beans package.
Please see XMLEncoder.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected classThis class implements accessibility support for theJTextFieldclass.Nested classes/interfaces declared in class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBindingNested classes/interfaces declared in class javax.swing.JComponent
JComponent.AccessibleJComponentNested classes/interfaces declared in class java.awt.Container
Container.AccessibleAWTContainerNested classes/interfaces declared in class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringName of the action to send notification that the contents of the field have been accepted.Fields declared in class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEYFields declared in class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOWFields declared in class java.awt.Component
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENTFields declared in interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTHFields declared in 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 -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a newTextField.JTextField(int columns) Constructs a new emptyTextFieldwith the specified number of columns.JTextField(String text) Constructs a newTextFieldinitialized with the specified text.JTextField(String text, int columns) Constructs a newTextFieldinitialized with the specified text and columns.JTextField(Document doc, String text, int columns) Constructs a newJTextFieldthat uses the given text storage model and the given number of columns. -
Method Summary
Modifier and TypeMethodDescriptionprotected voidactionPropertyChanged(Action action, String propertyName) Updates the textfield's state in response to property changes in associated action.voidAdds the specified action listener to receive action events from this textfield.protected voidSets the properties on this textfield to match those in the specifiedAction.protected PropertyChangeListenerCreates and returns aPropertyChangeListenerthat is responsible for listening for changes from the specifiedActionand updating the appropriate properties.protected DocumentCreates the default implementation of the model to be used at construction if one isn't explicitly given.protected voidNotifies all listeners that have registered interest for notification on this event type.Gets theAccessibleContextassociated with thisJTextField.Returns the currently setActionfor thisActionEventsource, ornullif noActionis set.Returns an array of all theActionListeners added to this JTextField with addActionListener().Action[]Fetches the command list for the editor.intReturns the number of columns in thisTextField.protected intReturns the column width.intReturns the horizontal alignment of the text.Gets the visibility of the text field.Returns the preferred sizeDimensionsneeded for thisTextField.intGets the scroll offset, in pixels.Gets the class ID for a UI.booleanCalls torevalidatethat come from within the textfield itself will be handled by validating the textfield, unless the textfield is contained within aJViewport, in which case this returns false.protected StringReturns a string representation of thisJTextField.voidProcesses action events occurring on this textfield by dispatching them to any registeredActionListenerobjects.voidRemoves the specified action listener so that it no longer receives action events from this textfield.voidScrolls the field left or right.voidSets theActionfor theActionEventsource.voidsetActionCommand(String command) Sets the command string used for action events.voidsetColumns(int columns) Sets the number of columns in thisTextField, and then invalidate the layout.voidsetDocument(Document doc) Associates the editor with a text document.voidSets the current font.voidsetHorizontalAlignment(int alignment) Sets the horizontal alignment of the text.voidsetScrollOffset(int scrollOffset) Sets the scroll offset, in pixels.Methods declared in class javax.swing.text.JTextComponent
addCaretListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, modelToView2D, moveCaretPosition, paste, print, print, print, read, removeCaretListener, removeKeymap, replaceSelection, restoreComposedText, saveComposedText, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, viewToModel2D, writeMethods declared in class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, updateMethods declared in class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTreeMethods declared in class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
-
Field Details
-
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:
-
-
Constructor Details
-
JTextField
public JTextField()Constructs a newTextField. A default model is created, the initial string isnull, and the number of columns is set to 0. -
JTextField
Constructs a newTextFieldinitialized with the specified text. A default model is created and the number of columns is 0.- Parameters:
text- the text to be displayed, ornull
-
JTextField
public JTextField(int columns) Constructs a new emptyTextFieldwith the specified number of columns. A default model is created and the initial string is set tonull.- 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
Constructs a newTextFieldinitialized with the specified text and columns. A default model is created.- Parameters:
text- the text to be displayed, ornullcolumns- 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
Constructs a newJTextFieldthat 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 isnull, a default model is created.- Parameters:
doc- the text storage to use; if this isnull, a default will be provided by calling thecreateDefaultModelmethodtext- the initial string to display, ornullcolumns- the number of columns to use to calculate the preferred width >= 0; ifcolumnsis set to zero, the preferred width will be whatever naturally results from the component implementation- Throws:
IllegalArgumentException- ifcolumns< 0
-
-
Method Details
-
getUIClassID
Gets the class ID for a UI.- Overrides:
getUIClassIDin classJComponent- Returns:
- the string "TextFieldUI"
- See Also:
-
setDocument
@BeanProperty(expert=true, description="the text document model") 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:
setDocumentin classJTextComponent- Parameters:
doc- the document to display/edit- See Also:
-
isValidateRoot
public boolean isValidateRoot()Calls torevalidatethat come from within the textfield itself will be handled by validating the textfield, unless the textfield is contained within aJViewport, in which case this returns false.- Overrides:
isValidateRootin classJComponent- Returns:
- if the parent of this textfield is a
JViewPortreturn false, otherwise return true - See Also:
-
getHorizontalAlignment
public int getHorizontalAlignment()Returns the horizontal alignment of the text. Valid keys are:JTextField.LEFTJTextField.CENTERJTextField.RIGHTJTextField.LEADINGJTextField.TRAILING
- Returns:
- the horizontal alignment
-
setHorizontalAlignment
@BeanProperty(preferred=true, enumerationValues={"JTextField.LEFT","JTextField.CENTER","JTextField.RIGHT","JTextField.LEADING","JTextField.TRAILING"}, description="Set the field alignment to LEFT, CENTER, RIGHT, LEADING (the default) or TRAILING") public void setHorizontalAlignment(int alignment) Sets the horizontal alignment of the text. Valid keys are:JTextField.LEFTJTextField.CENTERJTextField.RIGHTJTextField.LEADINGJTextField.TRAILING
invalidateandrepaintare called when the alignment is set, and aPropertyChangeevent ("horizontalAlignment") is fired.- Parameters:
alignment- the alignment- Throws:
IllegalArgumentException- ifalignmentis not a valid key
-
createDefaultModel
Creates the default implementation of the model to be used at construction if one isn't explicitly given. An instance ofPlainDocumentis returned.- Returns:
- the default model implementation
-
getColumns
public int getColumns()Returns the number of columns in thisTextField.- Returns:
- the number of columns >= 0
-
setColumns
@BeanProperty(bound=false, description="the number of columns preferred for display") public void setColumns(int columns) Sets the number of columns in thisTextField, and then invalidate the layout.- Parameters:
columns- the number of columns >= 0- Throws:
IllegalArgumentException- ifcolumnsis 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
Returns the preferred sizeDimensionsneeded for thisTextField. If a non-zero number of columns has been set, the width is set to the columns multiplied by the column width.- Overrides:
getPreferredSizein classJComponent- Returns:
- the dimension of this textfield
- See Also:
-
setFont
Sets the current font. This removes cached row height and column width so the new font will be reflected.revalidateis called after setting the font.- Overrides:
setFontin classJComponent- Parameters:
f- the new font- See Also:
-
addActionListener
Adds the specified action listener to receive action events from this textfield.- Parameters:
l- the action listener to be added
-
removeActionListener
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
Returns an array of all theActionListeners 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:
-
setActionCommand
Sets the command string used for action events.- Parameters:
command- the command string
-
setAction
@BeanProperty(visualUpdate=true, description="the Action instance connected with this ActionEvent source") public void setAction(Action a) Sets theActionfor theActionEventsource. The newActionreplaces any previously setActionbut does not affectActionListenersindependently added withaddActionListener. If theActionis already a registeredActionListenerfor theActionEventsource, it is not re-registered.Setting the
Actionresults in immediately changing all the properties described in Swing Components SupportingAction. Subsequently, the textfield's properties are automatically updated as theAction's properties change.This method uses three other methods to set and help track the
Action's property values. It uses theconfigurePropertiesFromActionmethod to immediately change the textfield's properties. To track changes in theAction's property values, this method registers thePropertyChangeListenerreturned bycreateActionPropertyChangeListener. The defaultPropertyChangeListenerinvokes theactionPropertyChangedmethod when a property in theActionchanges.- Parameters:
a- theActionfor theJTextField, ornull- Since:
- 1.3
- See Also:
-
getAction
Returns the currently setActionfor thisActionEventsource, ornullif noActionis set.- Returns:
- the
Actionfor thisActionEventsource, ornull - Since:
- 1.3
- See Also:
-
configurePropertiesFromAction
Sets the properties on this textfield to match those in the specifiedAction. Refer to Swing Components SupportingActionfor more details as to which properties this sets.- Parameters:
a- theActionfrom which to get the properties, ornull- Since:
- 1.3
- See Also:
-
actionPropertyChanged
Updates the textfield's state in response to property changes in associated action. This method is invoked from thePropertyChangeListenerreturned fromcreateActionPropertyChangeListener. Subclasses do not normally need to invoke this. Subclasses that support additionalActionproperties should override this andconfigurePropertiesFromAction.Refer to the table at Swing Components Supporting
Actionfor a list of the properties this method sets.- Parameters:
action- theActionassociated with this textfieldpropertyName- the name of the property that changed- Since:
- 1.6
- See Also:
-
createActionPropertyChangeListener
Creates and returns aPropertyChangeListenerthat is responsible for listening for changes from the specifiedActionand updating the appropriate properties.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- Returns:
- a
PropertyChangeListenerthat is responsible for listening for changes from the specifiedActionand updating the appropriate properties - Since:
- 1.3
- See Also:
-
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:
getActionsin classJTextComponent- Returns:
- the command list
-
postActionEvent
public void postActionEvent()Processes action events occurring on this textfield by dispatching them to any registeredActionListenerobjects. This is normally called by the controller registered with textfield. -
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:
-
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
Scrolls the field left or right.- Overrides:
scrollRectToVisiblein classJComponent- Parameters:
r- the region to scroll- See Also:
-
paramString
Returns a string representation of thisJTextField. 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 benull.- Overrides:
paramStringin classJTextComponent- Returns:
- a string representation of this
JTextField
-
getAccessibleContext
Gets theAccessibleContextassociated with thisJTextField. ForJTextFields, theAccessibleContexttakes the form of anAccessibleJTextField. A newAccessibleJTextFieldinstance is created if necessary.- Specified by:
getAccessibleContextin interfaceAccessible- Overrides:
getAccessibleContextin classJTextComponent- Returns:
- an
AccessibleJTextFieldthat serves as theAccessibleContextof thisJTextField
-