FileDocCategorySizeDatePackage
TextArea.javaAPI DocJava SE 6 API22567Tue Jun 10 00:25:18 BST 2008java.awt

TextArea

public class TextArea extends TextComponent
A TextArea object is a multi-line region that displays text. It can be set to allow editing or to be read-only.

The following image shows the appearance of a text area:

A TextArea showing the word 'Hello!'

This text area could be created by the following line of code: 

new TextArea("Hello", 5, 40);

version
1.81, 06/16/06
author
Sami Shaio
since
JDK1.0

Fields Summary
int
rows
The number of rows in the TextArea. This parameter will determine the text area's height. Guaranteed to be non-negative.
int
columns
The number of columns in the TextArea. A column is an approximate average character width that is platform-dependent. This parameter will determine the text area's width. Guaranteed to be non-negative.
private static final String
base
private static int
nameCounter
public static final int
SCROLLBARS_BOTH
Create and display both vertical and horizontal scrollbars.
public static final int
SCROLLBARS_VERTICAL_ONLY
Create and display vertical scrollbar only.
public static final int
SCROLLBARS_HORIZONTAL_ONLY
Create and display horizontal scrollbar only.
public static final int
SCROLLBARS_NONE
Do not create or display any scrollbars for the text area.
private int
scrollbarVisibility
Determines which scrollbars are created for the text area. It can be one of four values : SCROLLBARS_BOTH = both scrollbars.
SCROLLBARS_HORIZONTAL_ONLY = Horizontal bar only.
SCROLLBARS_VERTICAL_ONLY = Vertical bar only.
SCROLLBARS_NONE = No scrollbars.
private static Set
forwardTraversalKeys
Cache the Sets of forward and backward traversal keys so we need not look them up each time.
private static Set
backwardTraversalKeys
private static final long
serialVersionUID
private int
textAreaSerializedDataVersion
The textArea Serialized Data Version.
Constructors Summary
public TextArea()
Constructs a new text area with the empty string as text. This text area is created with scrollbar visibility equal to {@link #SCROLLBARS_BOTH}, so both vertical and horizontal scrollbars will be visible for this text area.

exception
HeadlessException if GraphicsEnvironment.isHeadless returns true
see
java.awt.GraphicsEnvironment#isHeadless()


               
        

     
        /* ensure that the necessary native libraries are loaded */
        Toolkit.loadLibraries();
        if (!GraphicsEnvironment.isHeadless()) {
            initIDs();
        }
        forwardTraversalKeys = KeyboardFocusManager.initFocusTraversalKeysSet(
            "ctrl TAB",
            new HashSet());
        backwardTraversalKeys = KeyboardFocusManager.initFocusTraversalKeysSet(
            "ctrl shift TAB",
            new HashSet());
    
	this("", 0, 0, SCROLLBARS_BOTH);
public TextArea(String text)
Constructs a new text area with the specified text. This text area is created with scrollbar visibility equal to {@link #SCROLLBARS_BOTH}, so both vertical and horizontal scrollbars will be visible for this text area.

param
text the text to be displayed; if text is null, the empty string "" will be displayed
exception
HeadlessException if GraphicsEnvironment.isHeadless returns true
see
java.awt.GraphicsEnvironment#isHeadless()

	this(text, 0, 0, SCROLLBARS_BOTH);
public TextArea(int rows, int columns)
Constructs a new text area with the specified number of rows and columns and the empty string as text. A column is an approximate average character width that is platform-dependent. The text area is created with scrollbar visibility equal to {@link #SCROLLBARS_BOTH}, so both vertical and horizontal scrollbars will be visible for this text area.

param
rows the number of rows
param
columns the number of columns
exception
HeadlessException if GraphicsEnvironment.isHeadless returns true
see
java.awt.GraphicsEnvironment#isHeadless()

	this("", rows, columns, SCROLLBARS_BOTH);
public TextArea(String text, int rows, int columns)
Constructs a new text area with the specified text, and with the specified number of rows and columns. A column is an approximate average character width that is platform-dependent. The text area is created with scrollbar visibility equal to {@link #SCROLLBARS_BOTH}, so both vertical and horizontal scrollbars will be visible for this text area.

param
text the text to be displayed; if text is null, the empty string "" will be displayed
param
rows the number of rows
param
columns the number of columns
exception
HeadlessException if GraphicsEnvironment.isHeadless returns true
see
java.awt.GraphicsEnvironment#isHeadless()

        this(text, rows, columns, SCROLLBARS_BOTH);
public TextArea(String text, int rows, int columns, int scrollbars)
Constructs a new text area with the specified text, and with the rows, columns, and scroll bar visibility as specified. All TextArea constructors defer to this one.

The TextArea class defines several constants that can be supplied as values for the scrollbars argument:

  • SCROLLBARS_BOTH,
  • SCROLLBARS_VERTICAL_ONLY,
  • SCROLLBARS_HORIZONTAL_ONLY,
  • SCROLLBARS_NONE.
Any other value for the scrollbars argument is invalid and will result in this text area being created with scrollbar visibility equal to the default value of {@link #SCROLLBARS_BOTH}.

param
text the text to be displayed; if text is null, the empty string "" will be displayed
param
rows the number of rows; if rows is less than 0, rows is set to 0
param
columns the number of columns; if columns is less than 0, columns is set to 0
param
scrollbars a constant that determines what scrollbars are created to view the text area
since
JDK1.1
exception
HeadlessException if GraphicsEnvironment.isHeadless returns true
see
java.awt.GraphicsEnvironment#isHeadless()

	super(text);

        this.rows = (rows >= 0) ? rows : 0;
        this.columns = (columns >= 0) ? columns : 0;

        if (scrollbars >= SCROLLBARS_BOTH && scrollbars <= SCROLLBARS_NONE) {
       	    this.scrollbarVisibility = scrollbars;
        } else {
            this.scrollbarVisibility = SCROLLBARS_BOTH;
        }

	setFocusTraversalKeys(KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
			      forwardTraversalKeys);
	setFocusTraversalKeys(KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
			      backwardTraversalKeys);
Methods Summary
public voidaddNotify()
Creates the TextArea's peer. The peer allows us to modify the appearance of the TextArea without changing any of its functionality.

        synchronized (getTreeLock()) {
	    if (peer == null)
	        peer = getToolkit().createTextArea(this);
	    super.addNotify();
	}
public voidappend(java.lang.String str)
Appends the given text to the text area's current text.

Note that passing null or inconsistent parameters is invalid and will result in unspecified behavior.

param
str the non-null text to append
see
java.awt.TextArea#insert
since
JDK1.1

    	appendText(str);
public synchronized voidappendText(java.lang.String str)

deprecated
As of JDK version 1.1, replaced by append(String).

	if (peer != null) {
	    insertText(str, getText().length());
	} else {
	    text = text + str;
	}
java.lang.StringconstructComponentName()
Construct a name for this component. Called by getName when the name is null.

        synchronized (getClass()) {
	    return base + nameCounter++;
	}
public javax.accessibility.AccessibleContextgetAccessibleContext()
Returns the AccessibleContext associated with this TextArea. For text areas, the AccessibleContext takes the form of an AccessibleAWTTextArea. A new AccessibleAWTTextArea instance is created if necessary.

return
an AccessibleAWTTextArea that serves as the AccessibleContext of this TextArea
since
1.3

        if (accessibleContext == null) {
            accessibleContext = new AccessibleAWTTextArea();
        }
        return accessibleContext;
public intgetColumns()
Returns the number of columns in this text area.

return
the number of columns in the text area
see
#setColumns(int)
see
#getRows()

	return columns;
public java.awt.DimensiongetMinimumSize(int rows, int columns)
Determines the minimum size of a text area with the specified number of rows and columns.

param
rows the number of rows
param
columns the number of columns
return
the minimum dimensions required to display the text area with the specified number of rows and columns
see
java.awt.Component#getMinimumSize
since
JDK1.1

    	return minimumSize(rows, columns);
public java.awt.DimensiongetMinimumSize()
Determines the minimum size of this text area.

return
the preferred dimensions needed for this text area
see
java.awt.Component#getPreferredSize
since
JDK1.1

	return minimumSize();
public java.awt.DimensiongetPreferredSize(int rows, int columns)
Determines the preferred size of a text area with the specified number of rows and columns.

param
rows the number of rows
param
columns the number of columns
return
the preferred dimensions required to display the text area with the specified number of rows and columns
see
java.awt.Component#getPreferredSize
since
JDK1.1

    	return preferredSize(rows, columns);
public java.awt.DimensiongetPreferredSize()
Determines the preferred size of this text area.

return
the preferred dimensions needed for this text area
see
java.awt.Component#getPreferredSize
since
JDK1.1

	return preferredSize();
public intgetRows()
Returns the number of rows in the text area.

return
the number of rows in the text area
see
#setRows(int)
see
#getColumns()
since
JDK1

	return rows;
public intgetScrollbarVisibility()
Returns an enumerated value that indicates which scroll bars the text area uses.

The TextArea class defines four integer constants that are used to specify which scroll bars are available. TextArea has one constructor that gives the application discretion over scroll bars.

return
an integer that indicates which scroll bars are used
see
java.awt.TextArea#SCROLLBARS_BOTH
see
java.awt.TextArea#SCROLLBARS_VERTICAL_ONLY
see
java.awt.TextArea#SCROLLBARS_HORIZONTAL_ONLY
see
java.awt.TextArea#SCROLLBARS_NONE
see
java.awt.TextArea#TextArea(java.lang.String, int, int, int)
since
JDK1.1

        return scrollbarVisibility;
private static native voidinitIDs()
Initialize JNI field and method ids

public voidinsert(java.lang.String str, int pos)
Inserts the specified text at the specified position
in this text area.

Note that passing null or inconsistent
parameters is invalid and will result in unspecified
behavior.
param
str the non-null text to insert
param
pos the position at which to insert
see
java.awt.TextComponent#setText
see
java.awt.TextArea#replaceRange
see
java.awt.TextArea#append
since
JDK1.1
    	insertText(str, pos);
    
public synchronized voidinsertText(java.lang.String str, int pos)
deprecated
As of JDK version 1.1,
replaced by insert(String, int).
	TextAreaPeer peer = (TextAreaPeer)this.peer;
	if (peer != null) {
	    peer.insertText(str, pos);
	} else {
	    text = text.substring(0, pos) + str + text.substring(pos);
	}
    
public java.awt.DimensionminimumSize(int rows, int columns)
deprecated
As of JDK version 1.1,
replaced by getMinimumSize(int, int).
        synchronized (getTreeLock()) {
	    TextAreaPeer peer = (TextAreaPeer)this.peer;
	    return (peer != null) ? 
		       peer.minimumSize(rows, columns) :
		       super.minimumSize();
        }
    
public java.awt.DimensionminimumSize()
deprecated
As of JDK version 1.1,
replaced by getMinimumSize().
        synchronized (getTreeLock()) {
	    return ((rows > 0) && (columns > 0)) ? 
			minimumSize(rows, columns) :
			super.minimumSize();
        }
    
protected java.lang.StringparamString()
Returns a string representing the state of this TextArea.
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 be
null.
return
the parameter string of this text area
	String sbVisStr;
	switch (scrollbarVisibility) {
	    case SCROLLBARS_BOTH:
		sbVisStr = "both";
		break;
	    case SCROLLBARS_VERTICAL_ONLY:
		sbVisStr = "vertical-only";
		break;
	    case SCROLLBARS_HORIZONTAL_ONLY:
		sbVisStr = "horizontal-only";
		break;
	    case SCROLLBARS_NONE:
		sbVisStr = "none";
		break;
	    default:
		sbVisStr = "invalid display policy";
	}

	return super.paramString() + ",rows=" + rows +
	    ",columns=" + columns +
	  ",scrollbarVisibility=" + sbVisStr;
    
public java.awt.DimensionpreferredSize(int rows, int columns)
deprecated
As of JDK version 1.1,
replaced by getPreferredSize(int, int).
        synchronized (getTreeLock()) {
	    TextAreaPeer peer = (TextAreaPeer)this.peer;
	    return (peer != null) ? 
		       peer.preferredSize(rows, columns) :
		       super.preferredSize();
        }
    
public java.awt.DimensionpreferredSize()
deprecated
As of JDK version 1.1,
replaced by getPreferredSize().
        synchronized (getTreeLock()) {
	    return ((rows > 0) && (columns > 0)) ? 
			preferredSize(rows, columns) :
			super.preferredSize();
        }
    
private voidreadObject(java.io.ObjectInputStream s)
Read the ObjectInputStream.
exception
HeadlessException if
GraphicsEnvironment.isHeadless() returns
true
see
java.awt.GraphicsEnvironment#isHeadless

                      
       
         
    
        // HeadlessException will be thrown by TextComponent's readObject
        s.defaultReadObject();

        // Make sure the state we just read in for columns, rows, 
        // and scrollbarVisibility has legal values
        if (columns < 0) {
            columns = 0;
        }
        if (rows < 0) {
            rows = 0;
        }

        if ((scrollbarVisibility < SCROLLBARS_BOTH) || 
            (scrollbarVisibility > SCROLLBARS_NONE)) {
            this.scrollbarVisibility = SCROLLBARS_BOTH;
        }

	if (textAreaSerializedDataVersion < 2) {
	    setFocusTraversalKeys(KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
				  forwardTraversalKeys);
	    setFocusTraversalKeys(KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
				  backwardTraversalKeys);
	}
    
public voidreplaceRange(java.lang.String str, int start, int end)
Replaces text between the indicated start and end positions
with the specified replacement text. The text at the end
position will not be replaced. The text at the start
position will be replaced (unless the start position is the
same as the end position).
The text position is zero-based. The inserted substring may be
of a different length than the text it replaces.

Note that passing null or inconsistent
parameters is invalid and will result in unspecified
behavior.
param
str the non-null text to use as
the replacement
param
start the start position
param
end the end position
see
java.awt.TextArea#insert
since
JDK1.1
	replaceText(str, start, end);
    
public synchronized voidreplaceText(java.lang.String str, int start, int end)
deprecated
As of JDK version 1.1,
replaced by replaceRange(String, int, int).
	TextAreaPeer peer = (TextAreaPeer)this.peer;
	if (peer != null) {
	    peer.replaceText(str, start, end);
	} else {
	    text = text.substring(0, start) + str + text.substring(end);
	}
    
public voidsetColumns(int columns)
Sets the number of columns for this text area.
param
columns the number of columns
see
#getColumns()
see
#setRows(int)
exception
IllegalArgumentException if the value
supplied for columns
is less than 0
since
JDK1.1
	int oldVal = this.columns;
	if (columns < 0) {
	    throw new IllegalArgumentException("columns less than zero.");
	}
	if (columns != oldVal) {
	    this.columns = columns;
	    invalidate();
	}
    
public voidsetRows(int rows)
Sets the number of rows for this text area.
param
rows the number of rows
see
#getRows()
see
#setColumns(int)
exception
IllegalArgumentException if the value
supplied for rows
is less than 0
since
JDK1.1
	int oldVal = this.rows;
	if (rows < 0) {
	    throw new IllegalArgumentException("rows less than zero.");
	}
	if (rows != oldVal) {
	    this.rows = rows;
	    invalidate();
	}