ImageObserver
, MenuContainer
, Serializable
, Accessible
, Scrollable
, SwingConstants
DefaultTreeCellEditor.DefaultTextField
, JFormattedTextField
, JPasswordField
@JavaBean(defaultProperty="UIClassID", description="A component which allows for the editing of a single line of text.") public class JTextField extends JTextComponent implements SwingConstants
JTextField
is a lightweight component that allows the editing
of a single line of text.
For information on and examples of using text fields,
see
How to Use Text Fields
in The Java Tutorial.
JTextField
is intended to be source-compatible
with java.awt.TextField
where it is reasonable to do so. This
component has capabilities not found in the java.awt.TextField
class. The superclass should be consulted for additional capabilities.
JTextField
has a method to establish the string used as the
command string for the action event that gets fired. The
java.awt.TextField
used the text of the field as the command
string for the ActionEvent
.
JTextField
will use the command
string set with the setActionCommand
method if not null
,
otherwise it will use the text of the field as a compatibility with
java.awt.TextField
.
The method setEchoChar
and getEchoChar
are not provided directly to avoid a new implementation of a
pluggable look-and-feel inadvertently exposing password characters.
To provide password-like services a separate class JPasswordField
extends JTextField
to provide this service with an independently
pluggable look-and-feel.
The java.awt.TextField
could be monitored for changes by adding
a TextListener
for TextEvent
's.
In the JTextComponent
based
components, changes are broadcasted from the model via a
DocumentEvent
to DocumentListeners
.
The DocumentEvent
gives
the location of the change and the kind of change if desired.
The code fragment might look something like:
DocumentListener myListener = ??;
JTextField myArea = ??;
myArea.getDocument().addDocumentListener(myListener);
The horizontal alignment of JTextField
can be set to be left
justified, leading justified, centered, right justified or trailing justified.
Right/trailing justification is useful if the required size
of the field text is smaller than the size allocated to it.
This is determined by the setHorizontalAlignment
and getHorizontalAlignment
methods. The default
is to be leading justified.
How the text field consumes VK_ENTER events depends on whether the text field has any action listeners. If so, then VK_ENTER results in the listeners getting an ActionEvent, and the VK_ENTER event is consumed. This is compatible with how AWT text fields handle VK_ENTER events. If the text field has no action listeners, then as of v 1.3 the VK_ENTER event is not consumed. Instead, the bindings of ancestor components are processed, which enables the default button feature of JFC/Swing to work.
Customized fields can easily be created by extending the model and changing the default model provided. For example, the following piece of code will create a field that holds only upper case characters. It will work even if text is pasted into from the clipboard or it is altered via programmatic changes.
public class UpperCaseField extends JTextField {
public UpperCaseField(int cols) {
super(cols);
}
protected Document createDefaultModel() {
return new UpperCaseDocument();
}
static class UpperCaseDocument extends PlainDocument {
public void insertString(int offs, String str, AttributeSet a)
throws BadLocationException {
if (str == null) {
return;
}
char[] upper = str.toCharArray();
for (int i = 0; i < upper.length; i++) {
upper[i] = Character.toUpperCase(upper[i]);
}
super.insertString(offs, new String(upper), a);
}
}
}
Warning: 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
.
setActionCommand(java.lang.String)
,
JPasswordField
,
addActionListener(java.awt.event.ActionListener)
Modifier and Type | Class | Description |
---|---|---|
protected class |
JTextField.AccessibleJTextField |
This class implements accessibility support for the
JTextField class. |
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Container.AccessibleAWTContainer
JComponent.AccessibleJComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Modifier and Type | Field | Description |
---|---|---|
static String |
notifyAction |
Name of the action to send notification that the
contents of the field have been accepted.
|
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor | Description |
---|---|
JTextField() |
Constructs a new
TextField . |
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. |
JTextField(Document doc,
String text,
int columns) |
Constructs a new
JTextField that uses the given text
storage model and the given number of columns. |
Modifier and Type | Method | Description |
---|---|---|
protected void |
actionPropertyChanged(Action action,
String propertyName) |
Updates the textfield's state in response to property changes in
associated action.
|
void |
addActionListener(ActionListener l) |
Adds the specified action listener to receive
action events from this textfield.
|
protected void |
configurePropertiesFromAction(Action a) |
Sets the properties on this textfield to match those in the specified
Action . |
protected PropertyChangeListener |
createActionPropertyChangeListener(Action a) |
Creates and returns a
PropertyChangeListener that is
responsible for listening for changes from the specified
Action and updating the appropriate properties. |
protected Document |
createDefaultModel() |
Creates the default implementation of the model
to be used at construction if one isn't explicitly
given.
|
protected void |
fireActionPerformed() |
Notifies all listeners that have registered interest for
notification on this event type.
|
AccessibleContext |
getAccessibleContext() |
Gets the
AccessibleContext associated with this
JTextField . |
Action |
getAction() |
Returns the currently set
Action for this
ActionEvent source, or null
if no Action is set. |
ActionListener[] |
getActionListeners() |
Returns an array of all the
ActionListener s added
to this JTextField with addActionListener(). |
Action[] |
getActions() |
Fetches the command list for the editor.
|
int |
getColumns() |
Returns the number of columns in this
TextField . |
protected int |
getColumnWidth() |
Returns the column width.
|
int |
getHorizontalAlignment() |
Returns the horizontal alignment of the text.
|
BoundedRangeModel |
getHorizontalVisibility() |
Gets the visibility of the text field.
|
Dimension |
getPreferredSize() |
Returns the preferred size
Dimensions needed for this
TextField . |
int |
getScrollOffset() |
Gets the scroll offset, in pixels.
|
String |
getUIClassID() |
Gets the class ID for a UI.
|
boolean |
isValidateRoot() |
Calls to
revalidate that come from within the
textfield itself will
be handled by validating the textfield, unless the textfield
is contained within a JViewport ,
in which case this returns false. |
protected String |
paramString() |
Returns a string representation of this
JTextField . |
void |
postActionEvent() |
Processes action events occurring on this textfield by
dispatching them to any registered
ActionListener objects. |
void |
removeActionListener(ActionListener l) |
Removes the specified action listener so that it no longer
receives action events from this textfield.
|
void |
scrollRectToVisible(Rectangle r) |
Scrolls the field left or right.
|
void |
setAction(Action a) |
Sets the
Action for the ActionEvent source. |
void |
setActionCommand(String command) |
Sets the command string used for action events.
|
void |
setColumns(int columns) |
Sets the number of columns in this
TextField ,
and then invalidate the layout. |
void |
setDocument(Document doc) |
Associates the editor with a text document.
|
void |
setFont(Font f) |
Sets the current font.
|
void |
setHorizontalAlignment(int alignment) |
Sets the horizontal alignment of the text.
|
void |
setScrollOffset(int scrollOffset) |
Sets the scroll offset, in pixels.
|
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, 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, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
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, validateTree
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, 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, 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, update
addCaretListener, addInputMethodListener, 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, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, restoreComposedText, saveComposedText, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, viewToModel2D, write
public static final String notifyAction
public JTextField()
TextField
. A default model is created,
the initial string is null
,
and the number of columns is set to 0.public JTextField(String text)
TextField
initialized with the
specified text. A default model is created and the number of
columns is 0.text
- the text to be displayed, or null
public JTextField(int columns)
TextField
with the specified
number of columns.
A default model is created and the initial string is set to
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 implementationpublic JTextField(String text, int columns)
TextField
initialized with the
specified text and columns. A default model is created.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 implementationpublic JTextField(Document doc, String text, int columns)
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.doc
- the text storage to use; if this is null
,
a default will be provided by calling the
createDefaultModel
methodtext
- 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 implementationIllegalArgumentException
- if columns
< 0@BeanProperty(bound=false) public String getUIClassID()
getUIClassID
in class JComponent
JComponent.getUIClassID()
,
UIDefaults.getUI(javax.swing.JComponent)
@BeanProperty(expert=true, description="the text document model") public void setDocument(Document doc)
setDocument
in class JTextComponent
doc
- the document to display/editJTextComponent.getDocument()
public boolean isValidateRoot()
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.isValidateRoot
in class JComponent
JViewPort
return false, otherwise return trueJComponent.revalidate()
,
JComponent.isValidateRoot()
,
Container.isValidateRoot()
public int getHorizontalAlignment()
JTextField.LEFT
JTextField.CENTER
JTextField.RIGHT
JTextField.LEADING
JTextField.TRAILING
@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)
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.alignment
- the alignmentIllegalArgumentException
- if alignment
is not a valid keyprotected Document createDefaultModel()
PlainDocument
is returned.public int getColumns()
TextField
.@BeanProperty(bound=false, description="the number of columns preferred for display") public void setColumns(int columns)
TextField
,
and then invalidate the layout.columns
- the number of columns >= 0IllegalArgumentException
- if columns
is less than 0protected int getColumnWidth()
public Dimension getPreferredSize()
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.getPreferredSize
in class JComponent
JComponent.setPreferredSize(java.awt.Dimension)
,
ComponentUI
public void setFont(Font f)
revalidate
is called after setting the font.setFont
in class JComponent
f
- the new fontComponent.getFont()
public void addActionListener(ActionListener l)
l
- the action listener to be addedpublic void removeActionListener(ActionListener l)
l
- the action listener to be removed@BeanProperty(bound=false) public ActionListener[] getActionListeners()
ActionListener
s added
to this JTextField with addActionListener().ActionListener
s added or an empty
array if no listeners have been addedprotected void fireActionPerformed()
EventListenerList
public void setActionCommand(String command)
command
- the command string@BeanProperty(visualUpdate=true, description="the Action instance connected with this ActionEvent source") public void setAction(Action a)
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.
Setting the Action
results in immediately changing
all the properties described in
Swing Components Supporting Action
.
Subsequently, the textfield's properties are automatically updated
as the Action
's properties change.
This method uses three other methods to set
and help track the Action
's property values.
It uses the configurePropertiesFromAction
method
to immediately change the textfield's properties.
To track changes in the Action
's property values,
this method registers the PropertyChangeListener
returned by createActionPropertyChangeListener
. The
default PropertyChangeListener
invokes the
actionPropertyChanged
method when a property in the
Action
changes.
a
- the Action
for the JTextField
,
or null
Action
,
getAction()
,
configurePropertiesFromAction(javax.swing.Action)
,
createActionPropertyChangeListener(javax.swing.Action)
,
actionPropertyChanged(javax.swing.Action, java.lang.String)
public Action getAction()
Action
for this
ActionEvent
source, or null
if no Action
is set.Action
for this ActionEvent
source,
or null
Action
,
setAction(javax.swing.Action)
protected void configurePropertiesFromAction(Action a)
Action
. Refer to
Swing Components Supporting Action
for more
details as to which properties this sets.a
- the Action
from which to get the properties,
or null
Action
,
setAction(javax.swing.Action)
protected void actionPropertyChanged(Action action, String propertyName)
PropertyChangeListener
returned from
createActionPropertyChangeListener
. Subclasses do not normally
need to invoke this. Subclasses that support additional Action
properties should override this and
configurePropertiesFromAction
.
Refer to the table at
Swing Components Supporting Action
for a list of
the properties this method sets.
action
- the Action
associated with this textfieldpropertyName
- the name of the property that changedAction
,
configurePropertiesFromAction(javax.swing.Action)
protected PropertyChangeListener createActionPropertyChangeListener(Action a)
PropertyChangeListener
that is
responsible for listening for changes from the specified
Action
and 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
.
a
- the textfield's actionPropertyChangeListener
that is responsible for
listening for changes from the specified Action
and
updating the appropriate propertiesAction
,
setAction(javax.swing.Action)
@BeanProperty(bound=false) public Action[] getActions()
getActions
in class JTextComponent
public void postActionEvent()
ActionListener
objects.
This is normally called by the controller registered with
textfield.@BeanProperty(bound=false) public BoundedRangeModel getHorizontalVisibility()
The fields look-and-feel implementation manages
the values of the minimum, maximum, and extent
properties on the BoundedRangeModel
.
BoundedRangeModel
public int getScrollOffset()
public void setScrollOffset(int scrollOffset)
scrollOffset
- the offset >= 0public void scrollRectToVisible(Rectangle r)
scrollRectToVisible
in class JComponent
r
- the region to scrollJViewport
protected String paramString()
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
.paramString
in class JTextComponent
JTextField
@BeanProperty(bound=false) public AccessibleContext getAccessibleContext()
AccessibleContext
associated with this
JTextField
. For JTextFields
,
the AccessibleContext
takes the form of an
AccessibleJTextField
.
A new AccessibleJTextField
instance is created
if necessary.getAccessibleContext
in interface Accessible
getAccessibleContext
in class JTextComponent
AccessibleJTextField
that serves as the
AccessibleContext
of this JTextField
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps