- All Implemented Interfaces:
ImageObserver
,MenuContainer
,Serializable
,Accessible
,Scrollable
JTextArea
is a multi-line area that displays plain text.
It is intended to be a lightweight component that provides source
compatibility with the java.awt.TextArea
class where it can
reasonably do so.
You can find information and examples of using all the text components in
Using Text Components,
a section in The Java Tutorial.
This component has capabilities not found in the
java.awt.TextArea
class. The superclass should be
consulted for additional capabilities.
Alternative multi-line text classes with
more capabilities are JTextPane
and JEditorPane
.
The java.awt.TextArea
internally handles scrolling.
JTextArea
is different in that it doesn't manage scrolling,
but implements the swing Scrollable
interface. This allows it
to be placed inside a JScrollPane
if scrolling
behavior is desired, and used directly if scrolling is not desired.
The java.awt.TextArea
has the ability to do line wrapping.
This was controlled by the horizontal scrolling policy. Since
scrolling is not done by JTextArea
directly, backward
compatibility must be provided another way. JTextArea
has
a bound property for line wrapping that controls whether or
not it will wrap lines. By default, the line wrapping property
is set to false (not wrapped).
java.awt.TextArea
has two properties rows
and columns
that are used to determine the preferred size.
JTextArea
uses these properties to indicate the
preferred size of the viewport when placed inside a JScrollPane
to match the functionality provided by java.awt.TextArea
.
JTextArea
has a preferred size of what is needed to
display all of the text, so that it functions properly inside of
a JScrollPane
. If the value for rows
or columns
is equal to zero,
the preferred size along that axis is used for
the viewport preferred size along the same axis.
The java.awt.TextArea
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 = ??; JTextArea myArea = ??; myArea.getDocument().addDocumentListener(myListener);
- Newlines
- For a discussion on how newlines are handled, see DefaultEditorKit.
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
.
- Since:
- 1.2
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionprotected class
This class implements accessibility support for theJTextArea
class.Nested classes/interfaces declared in class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Nested classes/interfaces declared in class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces declared in class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces declared in class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
-
Field Summary
Fields declared in class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
Fields declared in class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields declared in class java.awt.Component
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields declared in interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
-
Constructor Summary
ConstructorDescriptionConstructs a new TextArea.JTextArea
(int rows, int columns) Constructs a new empty TextArea with the specified number of rows and columns.Constructs a new TextArea with the specified text displayed.Constructs a new TextArea with the specified text and number of rows and columns.Constructs a new JTextArea with the given document model, and defaults for all of the other arguments (null, 0, 0).Constructs a new JTextArea with the specified number of rows and columns, and the given model. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Appends the given text to the end of the document.protected Document
Creates the default implementation of the model to be used at construction if one isn't explicitly given.Gets the AccessibleContext associated with this JTextArea.int
Returns the number of columns in the TextArea.protected int
Gets column width.int
Determines the number of lines contained in the area.int
getLineEndOffset
(int line) Determines the offset of the end of the given line.int
getLineOfOffset
(int offset) Translates an offset into the components text to a line number.int
getLineStartOffset
(int line) Determines the offset of the start of the given line.boolean
Gets the line-wrapping policy of the text area.Returns the preferred size of the viewport if this component is embedded in a JScrollPane.Returns the preferred size of the TextArea.protected int
Defines the meaning of the height of a row.int
getRows()
Returns the number of rows in the TextArea.boolean
Returns true if a viewport should always force the width of this Scrollable to match the width of the viewport.int
getScrollableUnitIncrement
(Rectangle visibleRect, int orientation, int direction) Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation.int
Gets the number of characters used to expand tabs.Returns the class ID for the UI.boolean
Gets the style of wrapping used if the text area is wrapping lines.void
Inserts the specified text at the specified position.protected String
Returns a string representation of this JTextArea.void
replaceRange
(String str, int start, int end) Replaces text from the indicated start to end position with the new text specified.void
setColumns
(int columns) Sets the number of columns for this TextArea.void
Sets the current font.void
setLineWrap
(boolean wrap) Sets the line-wrapping policy of the text area.void
setRows
(int rows) Sets the number of rows for this TextArea.void
setTabSize
(int size) Sets the number of characters to expand tabs to.void
setWrapStyleWord
(boolean word) Sets the style of wrapping used if the text area is wrapping lines.Methods declared in class javax.swing.text.JTextComponent
addCaretListener, addKeymap, copy, cut, fireCaretUpdate, getActions, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, 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, setDocument, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, viewToModel2D, write
Methods 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, isValidateRoot, 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, scrollRectToVisible, 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
Methods 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, validateTree
Methods 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
-
Constructor Details
-
JTextArea
public JTextArea()Constructs a new TextArea. A default model is set, the initial string is null, and rows/columns are set to 0. -
JTextArea
Constructs a new TextArea with the specified text displayed. A default model is created and rows/columns are set to 0.- Parameters:
text
- the text to be displayed, or null
-
JTextArea
public JTextArea(int rows, int columns) Constructs a new empty TextArea with the specified number of rows and columns. A default model is created, and the initial string is null.- Parameters:
rows
- the number of rows >= 0columns
- the number of columns >= 0- Throws:
IllegalArgumentException
- if the rows or columns arguments are negative.
-
JTextArea
Constructs a new TextArea with the specified text and number of rows and columns. A default model is created.- Parameters:
text
- the text to be displayed, or nullrows
- the number of rows >= 0columns
- the number of columns >= 0- Throws:
IllegalArgumentException
- if the rows or columns arguments are negative.
-
JTextArea
Constructs a new JTextArea with the given document model, and defaults for all of the other arguments (null, 0, 0).- Parameters:
doc
- the model to use
-
JTextArea
Constructs a new JTextArea with the specified number of rows and columns, and the given model. All of the constructors feed through this constructor.- Parameters:
doc
- the model to use, or create a default one if nulltext
- the text to be displayed, null if nonerows
- the number of rows >= 0columns
- the number of columns >= 0- Throws:
IllegalArgumentException
- if the rows or columns arguments are negative.
-
-
Method Details
-
getUIClassID
Returns the class ID for the UI.- Overrides:
getUIClassID
in classJComponent
- Returns:
- the string "TextAreaUI"
- See Also:
-
createDefaultModel
Creates the default implementation of the model to be used at construction if one isn't explicitly given. A new instance of PlainDocument is returned.- Returns:
- the default document model
-
setTabSize
@BeanProperty(preferred=true, description="the number of characters to expand tabs to") public void setTabSize(int size) Sets the number of characters to expand tabs to. This will be multiplied by the maximum advance for variable width fonts. A PropertyChange event ("tabSize") is fired when the tab size changes.- Parameters:
size
- number of characters to expand to- See Also:
-
getTabSize
public int getTabSize()Gets the number of characters used to expand tabs. If the document is null or doesn't have a tab setting, return a default of 8.- Returns:
- the number of characters
-
setLineWrap
@BeanProperty(preferred=true, description="should lines be wrapped") public void setLineWrap(boolean wrap) Sets the line-wrapping policy of the text area. If set to true the lines will be wrapped if they are too long to fit within the allocated width. If set to false, the lines will always be unwrapped. APropertyChange
event ("lineWrap") is fired when the policy is changed. By default this property is false.- Parameters:
wrap
- indicates if lines should be wrapped- See Also:
-
getLineWrap
public boolean getLineWrap()Gets the line-wrapping policy of the text area. If set to true the lines will be wrapped if they are too long to fit within the allocated width. If set to false, the lines will always be unwrapped.- Returns:
- if lines will be wrapped
-
setWrapStyleWord
@BeanProperty(description="should wrapping occur at word boundaries") public void setWrapStyleWord(boolean word) Sets the style of wrapping used if the text area is wrapping lines. If set to true the lines will be wrapped at word boundaries (whitespace) if they are too long to fit within the allocated width. If set to false, the lines will be wrapped at character boundaries. By default this property is false.- Parameters:
word
- indicates if word boundaries should be used for line wrapping- See Also:
-
getWrapStyleWord
public boolean getWrapStyleWord()Gets the style of wrapping used if the text area is wrapping lines. If set to true the lines will be wrapped at word boundaries (ie whitespace) if they are too long to fit within the allocated width. If set to false, the lines will be wrapped at character boundaries.- Returns:
- if the wrap style should be word boundaries instead of character boundaries
- See Also:
-
getLineOfOffset
Translates an offset into the components text to a line number.- Parameters:
offset
- the offset >= 0- Returns:
- the line number >= 0
- Throws:
BadLocationException
- thrown if the offset is less than zero or greater than the document length.
-
getLineCount
Determines the number of lines contained in the area.- Returns:
- the number of lines > 0
-
getLineStartOffset
Determines the offset of the start of the given line.- Parameters:
line
- the line number to translate >= 0- Returns:
- the offset >= 0
- Throws:
BadLocationException
- thrown if the line is less than zero or greater or equal to the number of lines contained in the document (as reported by getLineCount).
-
getLineEndOffset
Determines the offset of the end of the given line.- Parameters:
line
- the line >= 0- Returns:
- the offset >= 0
- Throws:
BadLocationException
- Thrown if the line is less than zero or greater or equal to the number of lines contained in the document (as reported by getLineCount).
-
insert
Inserts the specified text at the specified position. Does nothing if the model is null or if the text is null or empty.- Parameters:
str
- the text to insertpos
- the position at which to insert >= 0- Throws:
IllegalArgumentException
- if pos is an invalid position in the model- See Also:
-
append
Appends the given text to the end of the document. Does nothing if the model is null or the string is null or empty.- Parameters:
str
- the text to insert- See Also:
-
replaceRange
Replaces text from the indicated start to end position with the new text specified. Does nothing if the model is null. Simply does a delete if the new string is null or empty.- Parameters:
str
- the text to use as the replacementstart
- the start position >= 0end
- the end position >= start- Throws:
IllegalArgumentException
- if part of the range is an invalid position in the model- See Also:
-
getRows
public int getRows()Returns the number of rows in the TextArea.- Returns:
- the number of rows >= 0
-
setRows
@BeanProperty(bound=false, description="the number of rows preferred for display") public void setRows(int rows) Sets the number of rows for this TextArea. Calls invalidate() after setting the new value.- Parameters:
rows
- the number of rows >= 0- Throws:
IllegalArgumentException
- if rows is less than 0- See Also:
-
getRowHeight
protected int getRowHeight()Defines the meaning of the height of a row. This defaults to the height of the font.- Returns:
- the height >= 1
-
getColumns
public int getColumns()Returns the number of columns in the TextArea.- Returns:
- 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 for this TextArea. Does an invalidate() after setting the new value.- Parameters:
columns
- the number of columns >= 0- Throws:
IllegalArgumentException
- if columns is less than 0- See Also:
-
getColumnWidth
protected int getColumnWidth()Gets 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 size of the TextArea. This is the maximum of the size needed to display the text and the size requested for the viewport.- Overrides:
getPreferredSize
in classJComponent
- Returns:
- the size
- See Also:
-
setFont
Sets the current font. This removes cached row height and column width so the new font will be reflected, and calls revalidate().- Overrides:
setFont
in classJComponent
- Parameters:
f
- the font to use as the current font- See Also:
-
paramString
Returns a string representation of this JTextArea. 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:
paramString
in classJTextComponent
- Returns:
- a string representation of this JTextArea.
-
getScrollableTracksViewportWidth
Returns true if a viewport should always force the width of this Scrollable to match the width of the viewport. This is implemented to return true if the line wrapping policy is true, and false if lines are not being wrapped.- Specified by:
getScrollableTracksViewportWidth
in interfaceScrollable
- Overrides:
getScrollableTracksViewportWidth
in classJTextComponent
- Returns:
- true if a viewport should force the Scrollables width to match its own.
-
getPreferredScrollableViewportSize
Returns the preferred size of the viewport if this component is embedded in a JScrollPane. This uses the desired column and row settings if they have been set, otherwise the superclass behavior is used.- Specified by:
getPreferredScrollableViewportSize
in interfaceScrollable
- Overrides:
getPreferredScrollableViewportSize
in classJTextComponent
- Returns:
- The preferredSize of a JViewport whose view is this Scrollable.
- See Also:
-
getScrollableUnitIncrement
Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation. This is implemented to use the values returned by thegetRowHeight
andgetColumnWidth
methods.Scrolling containers, like JScrollPane, will use this method each time the user requests a unit scroll.
- Specified by:
getScrollableUnitIncrement
in interfaceScrollable
- Overrides:
getScrollableUnitIncrement
in classJTextComponent
- Parameters:
visibleRect
- the view area visible within the viewportorientation
- Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.direction
- Less than zero to scroll up/left, greater than zero for down/right.- Returns:
- The "unit" increment for scrolling in the specified direction
- Throws:
IllegalArgumentException
- for an invalid orientation- See Also:
-
getAccessibleContext
Gets the AccessibleContext associated with this JTextArea. For JTextAreas, the AccessibleContext takes the form of an AccessibleJTextArea. A new AccessibleJTextArea instance is created if necessary.- Specified by:
getAccessibleContext
in interfaceAccessible
- Overrides:
getAccessibleContext
in classJTextComponent
- Returns:
- an AccessibleJTextArea that serves as the AccessibleContext of this JTextArea
-