Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Class java.awt.swing.JTextArea

java.lang.Object
    |
    +----java.awt.Component
            |
            +----java.awt.Container
                    |
                    +----java.awt.swing.JComponent
                            |
                            +----java.awt.swing.text.JTextComponent
                                    |
                                    +----java.awt.swing.JTextArea

public class JTextArea
extends JTextComponent
A TextArea 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. 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 capabilitites 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.

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);
 

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 Swing1.0 applications. It will not be possible to load serialized Swing1.0 objects with future releases of Swing. The JDK1.2 release of Swing will be the compatibility baseline for the serialized form of Swing objects.

See Also:
JTextPane, JEditorPane

Inner Class Summary
 JTextArea.AccessibleJTextArea
The class used to obtain the accessible role for this object.
 
Inner classes inherited from class java.awt.swing.text.JTextComponent
 JTextComponent.AccessibleJTextComponent, JTextComponent.KeyBinding
 
Inner classes inherited from class java.awt.swing.JComponent
 JComponent.AccessibleJComponent
 

Fields inherited from class java.awt.swing.text.JTextComponent
 DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
 
Fields inherited from class java.awt.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
 

Constructor Summary
 JTextArea()
Constructs a new TextArea.
 JTextArea(String text)
Constructs a new TextArea with the specified text displayed.
 JTextArea(int rows, int columns)
Constructs a new empty TextArea with the specified number of rows and columns.
 JTextArea(String text, int rows, int columns)
Constructs a new TextArea with the specified text and number of rows and columns.
 JTextArea(Document doc)
Constructs a new JTextArea with the given document model, and defaults for all of the other arguments.
 JTextArea(Document doc, String text, int rows, int columns)
Constructs a new JTextArea with the specified number of rows and columns, and the given model.
 

Method Summary
void  append(String str)
Appends the given text to the end of the document.
Document  createDefaultModel()
Creates the default implementation of the model to be used at construction if one isn't explicitly given.
AccessibleContext  getAccessibleContext()
Get the AccessibleContext associated with this JTextArea
int  getColumns()
Returns the number of columns in the TextArea.
int  getColumnWidth()
Gets column width.
int  getLineCount()
Determine the number of lines contained.
int  getLineEndOffset(int line)
Determine the offset of the end of the given line.
int  getLineOfOffset(int offset)
Translate an offset into the components text to a line number.
int  getLineStartOffset(int line)
Determine the offset of the start of the given line.
boolean  getLineWrap()
Get the line-wrapping policy of the text area.
Dimension  getMinimumSize()
Returns the minimum size Dimensions of the TextArea.
Dimension  getPreferredScrollableViewportSize()
Returns the preferred size of the viewport if this component is embedded in a JScrollPane.
int  getRowHeight()
Defines the meaning of the height of a row.
int  getRows()
Returns the number of rows in the TextArea.
boolean  getScrollableTracksViewportWidth()
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  getTabSize()
Gets the number of characters used to expand tabs.
String  getUIClassID()
Returns the class ID for the UI.
void  insert(String str, int pos)
Inserts the specified text at the specified position.
boolean  isManagingFocus()
Turns off tab traversal once focus gained.
String  paramString()
Returns the String of parameters for this TextArea.
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  setFont(Font f)
Sets the current font.
void  setLineWrap(boolean wrap)
Set 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.
 
Methods inherited from class java.awt.swing.text.JTextComponent
 addCaretListener, addKeymap, copy, cut, fireCaretUpdate, getAccessibleContext, getActions, getCaret, getCaretColor, getCaretPosition, getDisabledTextColor, getDocument, getFocusAccelerator, getHighlighter, getKeymap, getKeymap, getMargin, getPreferredScrollableViewportSize, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getUI, isEditable, isFocusTraversable, isOpaque, loadKeymap, modelToView, moveCaretPosition, paste, processComponentKeyEvent, read, removeCaretListener, removeKeymap, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setDocument, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setOpaque, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write
 
Methods inherited from class java.awt.swing.JComponent
 addAncestorListener, addNotify, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getUIClassID, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isFocusTraversable, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, processComponentKeyEvent, processFocusEvent, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setAlignmentX, setAlignmentY, setAutoscrolls, setBorder, setBounds, setDebugGraphicsOptions, setDoubleBuffered, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVisible, unregisterKeyboardAction, update, updateUI
 
Methods inherited from class java.awt.Container
 add, add, add, add, add, addContainerListener, addImpl, addNotify, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paint, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setLayout, update, validate, validateTree
 
Methods inherited from class java.awt.Component
 action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getColorModel, getComponentAt, getComponentAt, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getName, getParent, getPeer, getPreferredSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isDisplayable, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paint, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setCursor, setDropTarget, setEnabled, setFont, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, update, validate
 
Methods inherited from class java.lang.Object
 clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JTextArea

public JTextArea()
Constructs a new TextArea.

JTextArea

public JTextArea(String text)
Constructs a new TextArea with the specified text displayed.
Parameters:
text - the text to be displayed

JTextArea

public JTextArea(int rows,
                 int columns)
Constructs a new empty TextArea with the specified number of rows and columns.
Parameters:
rows - the number of rows
columns - the number of columns

JTextArea

public JTextArea(String text,
                 int rows,
                 int columns)
Constructs a new TextArea with the specified text and number of rows and columns.
Parameters:
text - the text to be displayed
rows - the number of rows
columns - the number of columns

JTextArea

public JTextArea(Document doc)
Constructs a new JTextArea with the given document model, and defaults for all of the other arguments.
Parameters:
doc - the model to use

JTextArea

public JTextArea(Document doc,
                 String text,
                 int rows,
                 int columns)
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
text - the text to be displayed
rows - the number of rows
columns - the number of columns
Method Detail

getUIClassID

public String getUIClassID()
Returns the class ID for the UI.
Returns:
the ID
Overrides:
getUIClassID in class JComponent
See Also:
getUIClassID, getUI

createDefaultModel

protected Document createDefaultModel()
Creates the default implementation of the model to be used at construction if one isn't explicitly given.
Returns:
the default document model

setTabSize

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.
Parameters:
size - number of characters to expand to
See Also:
getTabSize

getTabSize

public int getTabSize()
Gets the number of characters used to expand tabs.
Returns:
the number of characters

setLineWrap

public void setLineWrap(boolean wrap)
Set 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.
Parameters:
wrap - indicates if lines should be wrapped.
See Also:
getLineWrap

getLineWrap

public boolean getLineWrap()
Get 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.

getLineOfOffset

public int getLineOfOffset(int offset) throws BadLocationException
Translate an offset into the components text to a line number.
Throws:
BadLocationException - Thrown if the offset is less than zero or greater than the document length.

getLineCount

public int getLineCount()
Determine the number of lines contained.

getLineStartOffset

public int getLineStartOffset(int line) throws BadLocationException
Determine the offset of the start of the given line.
Parameters:
line - The line number to translate. Lines are numbered from 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

public int getLineEndOffset(int line) throws BadLocationException
Determine the offset of the end of the given line.
Parameters:
line - The line number to translate. Lines are numbered from 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

public void insert(String str,
                   int pos)
Inserts the specified text at the specified position.

This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.

Parameters:
str - the text to insert
pos - the position at which to insert
Throws:
IllegalArgumentException - if pos is an invalid position in the model
See Also:
setText, replaceRange

append

public void append(String str)
Appends the given text to the end of the document.

This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.

Parameters:
str - the text to insert
See Also:
insert

replaceRange

public void replaceRange(String str,
                         int start,
                         int end)
Replaces text from the indicated start to end position with the new text specified.

This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.

Parameters:
str - the text to use as the replacement
start - the start position
end - the end position
Throws:
IllegalArgumentException - if part of the range is an invalid position in the model
See Also:
insert, replaceRange

isManagingFocus

public boolean isManagingFocus()
Turns off tab traversal once focus gained.
Returns:
true, to indicate that the focus is being managed
Overrides:
isManagingFocus in class JComponent

getRows

public int getRows()
Returns the number of rows in the TextArea.
Returns:
the number of rows

setRows

public void setRows(int rows)
Sets the number of rows for this TextArea.
Parameters:
rows - the number of rows
Throws:
IllegalArgumentException - if rows is less than 0
See Also:
getRows

getRowHeight

protected int getRowHeight()
Defines the meaning of the height of a row. This defaults to the height of the font.
Returns:
the height

getColumns

public int getColumns()
Returns the number of columns in the TextArea.
Returns:
number of columns

setColumns

public void setColumns(int columns)
Sets the number of columns for this TextArea.
Parameters:
columns - the number of columns
Throws:
IllegalArgumentException - if columns is less than 0
See Also:
getColumns

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

getMinimumSize

public Dimension getMinimumSize()
Returns the minimum size Dimensions of the TextArea. By default this is set to the preferred size.
Returns:
the dimensions
Overrides:
getMinimumSize in class JComponent

setFont

public void setFont(Font f)
Sets the current font. This removes cached row height and column width so the new font will be reflected.
Parameters:
f - the font to use as the current font
Overrides:
setFont in class Component

paramString

protected String paramString()
Returns the String of parameters for this TextArea.
Returns:
the string of parameters
Overrides:
paramString in class Container

getScrollableTracksViewportWidth

public boolean 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.
Returns:
True if a viewport should force the Scrollables width to match its own.
Overrides:
getScrollableTracksViewportWidth in class JTextComponent

getPreferredScrollableViewportSize

public Dimension 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.
Returns:
The preferredSize of a JViewport whose view is this Scrollable.
Overrides:
getPreferredScrollableViewportSize in class JTextComponent
See Also:
getPreferredSize

getScrollableUnitIncrement

public 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. This is implemented to use the vaules returned by the getRowHeight and getColumnWidth methods.

Scrolling containers, like JScrollPane, will use this method each time the user requests a unit scroll.

Parameters:
visibleRect - The view area visible within the viewport
orientation - 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
Overrides:
getScrollableUnitIncrement in class JTextComponent
See Also:
setUnitIncrement, getRowHeight, getColumnWidth

getAccessibleContext

public AccessibleContext getAccessibleContext()
Get the AccessibleContext associated with this JTextArea
Returns:
the AccessibleContext of this JTextArea
Overrides:
getAccessibleContext in class JTextComponent

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.