javax.swing

Class JTextArea

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.text.JTextComponent

javax.swing.JTextArea

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, Accessible, Scrollable

public class JTextArea
extends JTextComponent

The JTextArea component provides a multi-line area for displaying and editing plain text. The component is designed to act as a lightweight replacement for the heavyweight java.awt.TextArea component, which provides similar functionality using native widgets.

This component has additional functionality to the AWT class. It follows the same design pattern as seen in other text components, such as JTextField, JTextPane and JEditorPane, and embodied in JTextComponent. These classes separate the text (the model) from its appearance within the onscreen component (the view). The text is held within a javax.swing.text.Document object, which can also maintain relevant style information where necessary. As a result, it is the document that should be monitored for textual changes, via DocumentEvents delivered to registered DocumentListeners, rather than this component.

Unlike java.awt.TextArea, JTextArea does not handle scrolling. Instead, this functionality is delegated to a JScrollPane, which can contain the text area and handle scrolling when required. Likewise, the word wrapping functionality of the AWT component is converted to a property of this component and the rows and columns properties are used in calculating the preferred size of the scroll pane's view port.

See Also:

TextArea, JTextComponent, JTextField, JTextPane, JEditorPane, Document, DocumentEvent, DocumentListener, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	JTextArea.AccessibleJTextArea Provides accessibility support for JTextArea.

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

JTextComponent.AccessibleJTextComponent, JTextComponent.KeyBinding

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields inherited from class javax.swing.text.JTextComponent

DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
JTextArea() Creates a new JTextArea object.
JTextArea(Document doc) Creates a new JTextArea object.
JTextArea(Document doc, String text, int rows, int columns) Creates a new JTextArea object.
JTextArea(int rows, int columns) Creates a new JTextArea object.
JTextArea(String text) Creates a new JTextArea object.
JTextArea(String text, int rows, int columns) Creates a new JTextArea object.

Method Summary

Methods

Modifier and Type	Method and Description
void	append(String toAppend) Appends the supplied text to the current contents of the document model.
protected Document	createDefaultModel() Creates the default document model.
AccessibleContext	getAccessibleContext() Returns the accessible context associated with the JTextArea.
int	getColumns() Returns the current number of columns.
protected int	getColumnWidth()
int	getLineCount()
int	getLineEndOffset(int line)
int	getLineOfOffset(int offset)
int	getLineStartOffset(int line)
boolean	getLineWrap() Checks whether line wrapping is enabled.
Dimension	getPreferredScrollableViewportSize() Returns the preferred size of that text component in the case it is embedded within a JScrollPane.
Dimension	getPreferredSize() Returns the preferred size for the JTextArea.
protected int	getRowHeight()
int	getRows() Returns the current number of rows.
boolean	getScrollableTracksViewportWidth() Returns true if the width of this component should be forced to match the width of a surrounding view port.
int	getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction) Returns the increment that is needed to expose exactly one new line of text.
int	getTabSize() Returns the number of characters used for a tab.
String	getUIClassID() Returns the UI class ID string.
boolean	getWrapStyleWord() Checks whether word style wrapping is enabled.
void	insert(String string, int position) Inserts the supplied text at the specified position.
void	replaceRange(String text, int start, int end)
void	setColumns(int columns) Sets the number of rows.
void	setLineWrap(boolean flag) Enables/disables line wrapping.
void	setRows(int rows) Sets the number of rows.
void	setTabSize(int newSize) Sets the number of characters used for a tab to the supplied value.
void	setWrapStyleWord(boolean flag) Enables/Disables word style wrapping.

Methods inherited from class javax.swing.text.JTextComponent

addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getActions, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getFocusAccelerator, getHighlighter, getInputMethodListeners, getKeymap, getKeymap, getMargin, getNavigationFilter, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paramString, paste, read, removeCaretListener, removeInputMethodListener, removeKeymap, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setDocument, setDragEnabled, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, 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, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setNextFocusableComponent, setOpaque, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from 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, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

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, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, 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, processMouseEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Constructor Detail

JTextArea

public JTextArea()

Creates a new JTextArea object.

JTextArea

public JTextArea(String text)

Creates a new JTextArea object.

Parameters:

text - the initial text

JTextArea

public JTextArea(int rows,
         int columns)

Creates a new JTextArea object.

Parameters:

rows - the number of rows

columns - the number of cols

Throws:

IllegalArgumentException - if rows or columns are negative

JTextArea

public JTextArea(String text,
         int rows,
         int columns)

Creates a new JTextArea object.

Parameters:

text - the initial text

rows - the number of rows

columns - the number of cols

Throws:

IllegalArgumentException - if rows or columns are negative

JTextArea

public JTextArea(Document doc)

Creates a new JTextArea object.

Parameters:

doc - the document model to use

JTextArea

public JTextArea(Document doc,
         String text,
         int rows,
         int columns)

Creates a new JTextArea object.

Parameters:

doc - the document model to use

text - the initial text

rows - the number of rows

columns - the number of cols

Throws:

IllegalArgumentException - if rows or columns are negative

Method Detail

append

public void append(String toAppend)

Appends the supplied text to the current contents of the document model.

Parameters:

toAppend - the text to append

createDefaultModel

protected Document createDefaultModel()

Creates the default document model.

Returns:

a new default model

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()

Returns true if the width of this component should be forced to match the width of a surrounding view port. When line wrapping is turned on, this method returns true.

Specified by:

getScrollableTracksViewportWidth in interface Scrollable

Overrides:

getScrollableTracksViewportWidth in class JTextComponent

Returns:

true if lines are wrapped.

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                             int orientation,
                             int direction)

Returns the increment that is needed to expose exactly one new line of text. This is implemented here to return the values of getRowHeight() and getColumnWidth(), depending on the value of the argument direction.

Specified by:

getScrollableUnitIncrement in interface Scrollable

Overrides:

getScrollableUnitIncrement in class JTextComponent

Parameters:

visibleRect - the view area that is visible in the viewport

orientation - either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL

direction - less than zero for up/left scrolling, greater than zero for down/right scrolling

Returns:

the increment that is needed to expose exactly one new row or column of text

Throws:

IllegalArgumentException - if orientation is invalid

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()

Returns the preferred size of that text component in the case it is embedded within a JScrollPane. This uses the column and row settings if they are explicitly set, or fall back to the superclass's behaviour.

Specified by:

getPreferredScrollableViewportSize in interface Scrollable

Overrides:

getPreferredScrollableViewportSize in class JTextComponent

Returns:

the preferred size of that text component in the case it is embedded within a JScrollPane

getUIClassID

public String getUIClassID()

Returns the UI class ID string.

Overrides:

getUIClassID in class JTextComponent

Returns:

the string "TextAreaUI"

See Also:

JComponent.setUI(javax.swing.plaf.ComponentUI), JComponent.updateUI()

getColumns

public int getColumns()

Returns the current number of columns.

Returns:

number of columns

setColumns

public void setColumns(int columns)

Sets the number of rows.

Parameters:

columns - number of columns

Throws:

IllegalArgumentException - if columns is negative

getRows

public int getRows()

Returns the current number of rows.

Returns:

number of rows

setRows

public void setRows(int rows)

Sets the number of rows.

Parameters:

rows - number of rows

Throws:

IllegalArgumentException - if rows is negative

getLineWrap

public boolean getLineWrap()

Checks whether line wrapping is enabled.

Returns:

true if line wrapping is enabled, false otherwise

setLineWrap

public void setLineWrap(boolean flag)

Enables/disables line wrapping.

Parameters:

flag - true to enable line wrapping, false otherwise

getWrapStyleWord

public boolean getWrapStyleWord()

Checks whether word style wrapping is enabled.

Returns:

true if word style wrapping is enabled, false otherwise

setWrapStyleWord

public void setWrapStyleWord(boolean flag)

Enables/Disables word style wrapping.

Parameters:

flag - true to enable word style wrapping, false otherwise

getTabSize

public int getTabSize()

Returns the number of characters used for a tab. This defaults to 8.

Returns:

the current number of spaces used for a tab.

setTabSize

public void setTabSize(int newSize)

Sets the number of characters used for a tab to the supplied value. If a change to the tab size property occurs (i.e. newSize != tabSize), a property change event is fired.

Parameters:

newSize - The new number of characters to use for a tab.

getColumnWidth

protected int getColumnWidth()

getLineCount

public int getLineCount()

getLineStartOffset

public int getLineStartOffset(int line)
                       throws BadLocationException

Throws:

BadLocationException

getLineEndOffset

public int getLineEndOffset(int line)
                     throws BadLocationException

Throws:

BadLocationException

getLineOfOffset

public int getLineOfOffset(int offset)
                    throws BadLocationException

Throws:

BadLocationException

getRowHeight

protected int getRowHeight()

insert

public void insert(String string,
          int position)

Inserts the supplied text at the specified position. Nothing happens in the case that the model or the supplied string is null or of zero length.

Parameters:

string - The string of text to insert.

position - The position at which to insert the supplied text.

Throws:

IllegalArgumentException - if the position is < 0 or greater than the length of the current text.

replaceRange

public void replaceRange(String text,
                int start,
                int end)

getPreferredSize

public Dimension getPreferredSize()

Returns the preferred size for the JTextArea. This is the maximum of the size that is needed to display the content and the requested size as per getColumns() and getRows().

Overrides:

getPreferredSize in class JComponent

Returns:

the preferred size of the JTextArea

See Also:

Component.setPreferredSize(java.awt.Dimension), Component.getPreferredSize(), Component.isPreferredSizeSet(), ComponentUI.getPreferredSize(JComponent)

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns the accessible context associated with the JTextArea.

Specified by:

getAccessibleContext in interface Accessible

Overrides:

getAccessibleContext in class JTextComponent

Returns:

the accessible context associated with the JTextArea