javax.swing

Class JTextArea

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

Nested Class Summary
protected classJTextArea.AccessibleJTextArea
Provides accessibility support for JTextArea.
Constructor Summary
JTextArea()
Creates a new JTextArea object.
JTextArea(String text)
Creates a new JTextArea object.
JTextArea(int rows, int columns)
Creates a new JTextArea object.
JTextArea(String text, int rows, int columns)
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.
Method Summary
voidappend(String toAppend)
Appends the supplied text to the current contents of the document model.
protected DocumentcreateDefaultModel()
Creates the default document model.
AccessibleContextgetAccessibleContext()
Returns the accessible context associated with the JTextArea.
intgetColumns()
Returns the current number of columns.
protected intgetColumnWidth()
intgetLineCount()
intgetLineEndOffset(int line)
intgetLineOfOffset(int offset)
intgetLineStartOffset(int line)
booleangetLineWrap()
Checks whether line wrapping is enabled.
DimensiongetPreferredScrollableViewportSize()
Returns the preferred size of that text component in the case it is embedded within a JScrollPane.
DimensiongetPreferredSize()
Returns the preferred size for the JTextArea.
protected intgetRowHeight()
intgetRows()
Returns the current number of rows.
booleangetScrollableTracksViewportWidth()
Returns true if the width of this component should be forced to match the width of a surrounding view port.
intgetScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction)
Returns the increment that is needed to expose exactly one new line of text.
intgetTabSize()
Returns the number of characters used for a tab.
StringgetUIClassID()
Returns the UI class ID string.
booleangetWrapStyleWord()
Checks whether word style wrapping is enabled.
voidinsert(String string, int position)
Inserts the supplied text at the specified position.
voidreplaceRange(String text, int start, int end)
voidsetColumns(int columns)
Sets the number of rows.
voidsetLineWrap(boolean flag)
Enables/disables line wrapping.
voidsetRows(int rows)
Sets the number of rows.
voidsetTabSize(int newSize)
Sets the number of characters used for a tab to the supplied value.
voidsetWrapStyleWord(boolean flag)
Enables/Disables word style wrapping.

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

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns the accessible context associated with the JTextArea.

Returns: the accessible context associated with the JTextArea

getColumns

public int getColumns()
Returns the current number of columns.

Returns: number of columns

getColumnWidth

protected int getColumnWidth()

getLineCount

public int getLineCount()

getLineEndOffset

public int getLineEndOffset(int line)

getLineOfOffset

public int getLineOfOffset(int offset)

getLineStartOffset

public int getLineStartOffset(int line)

getLineWrap

public boolean getLineWrap()
Checks whether line wrapping is enabled.

Returns: true if line wrapping is enabled, false otherwise

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.

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

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 {@link #getColumns} and {@link #getRows}.

Returns: the preferred size of the JTextArea

getRowHeight

protected int getRowHeight()

getRows

public int getRows()
Returns the current number of rows.

Returns: number of rows

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.

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 {@link #getRowHeight} and {@link #getColumnWidth}, depending on the value of the argument direction.

Parameters: visibleRect the view area that is visible in the viewport orientation either {@link SwingConstants#VERTICAL} or {@link 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

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.

getUIClassID

public String getUIClassID()
Returns the UI class ID string.

Returns: the string "TextAreaUI"

getWrapStyleWord

public boolean getWrapStyleWord()
Checks whether word style wrapping is enabled.

Returns: true if word style wrapping is enabled, false otherwise

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)

setColumns

public void setColumns(int columns)
Sets the number of rows.

Parameters: columns number of columns

Throws: IllegalArgumentException if columns is negative

setLineWrap

public void setLineWrap(boolean flag)
Enables/disables line wrapping.

Parameters: flag true to enable line wrapping, false otherwise

setRows

public void setRows(int rows)
Sets the number of rows.

Parameters: rows number of rows

Throws: IllegalArgumentException if rows is negative

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.

setWrapStyleWord

public void setWrapStyleWord(boolean flag)
Enables/Disables word style wrapping.

Parameters: flag true to enable word style wrapping, false otherwise