javax.swing
Class JTextArea

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.text.JTextComponent
                  extended by 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
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
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
 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