/*
* @(#)TextArea.java 1.62 06/10/10
*
* Copyright 1990-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version
* 2 only, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License version 2 for more details (a copy is
* included at /legal/license.txt).
*
* You should have received a copy of the GNU General Public License
* version 2 along with this work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*
*/
package java.awt;
import java.io.ObjectOutputStream;
import java.io.ObjectInputStream;
import java.io.IOException;
import java.util.Set;
import java.util.TreeSet;
import sun.awt.peer.TextAreaPeer;
import sun.awt.PeerBasedToolkit;
/**
* A <code>TextArea</code> object is a multi-line region
* that displays text. It can be set to allow editing or
* to be read-only.
* <p>
* The following image shows the appearance of a text area:
* <p>
* <img src="doc-files/TextArea-1.gif"
* ALIGN=center HSPACE=10 VSPACE=7>
* <p>
* This text area could be created by the following line of code:
* <p>
* <hr><blockquote><pre>
* new TextArea("Hello", 5, 40);
* </pre></blockquote><hr>
* <p>
* @version 1.56, 08/19/02
* @author Sami Shaio
* @since JDK1.0
*/
public class TextArea extends TextComponent {
/**
* The number of rows in the TextArea.
* This parameter will determine the text area's height.
* Guaranteed to be non-negative.
*
* @serial
* @see getRows()
* @see setRows()
*/
int rows;
/**
* 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.
*
* @serial
* @see getColumns()
* @see setColumns()
*/
int columns;
private static final String base = "text";
private static int nameCounter = 0;
/**
* Create and display both vertical and horizontal scrollbars.
* @since JDK1.1
*/
public static final int SCROLLBARS_BOTH = 0;
/**
* Create and display vertical scrollbar only.
* @since JDK1.1
*/
public static final int SCROLLBARS_VERTICAL_ONLY = 1;
/**
* Create and display horizontal scrollbar only.
* @since JDK1.1
*/
public static final int SCROLLBARS_HORIZONTAL_ONLY = 2;
/**
* Do not create or display any scrollbars for the text area.
* @since JDK1.1
*/
public static final int SCROLLBARS_NONE = 3;
/**
* Determines which scrollbars are created for the
* text area. It can be one of four values :
* <code>SCROLLBARS_BOTH</code> = both scrollbars.<BR>
* <code>SCROLLBARS_HORIZONTAL_ONLY</code> = Horizontal bar only.<BR>
* <code>SCROLLBARS_VERTICAL_ONLY</code> = Vertical bar only.<BR>
* <code>SCROLLBARS_NONE</code> = No scrollbars.<BR>
*
* @serial
* @see getScrollbarVisibility()
*/
private int scrollbarVisibility;
/**
* Cache the Sets of forward and backward traversal keys so we need not
* look them up each time.
*/
private static Set forwardTraversalKeys, backwardTraversalKeys;
/*
* JDK 1.1 serialVersionUID
*/
private static final long serialVersionUID = 3692302836626095722L;
static {
forwardTraversalKeys = KeyboardFocusManager.initFocusTraversalKeysSet(
"TAB",
new TreeSet());
backwardTraversalKeys = KeyboardFocusManager.initFocusTraversalKeysSet(
"shift TAB",
new TreeSet());
}
/**
* Constructs a new text area.
* 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.
*/
public TextArea() {
this("", 0, 0, SCROLLBARS_BOTH);
}
/**
* 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.
*/
public TextArea(String text) {
this(text, 0, 0, SCROLLBARS_BOTH);
}
/**
* Constructs a new empty text area 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 rows the number of rows
* @param columns the number of columns
*/
public TextArea(int rows, int columns) {
this("", rows, columns, SCROLLBARS_BOTH);
}
/**
* 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.
* @param rows the number of rows.
* @param columns the number of columns.
*/
public TextArea(String text, int rows, int columns) {
this(text, rows, columns, SCROLLBARS_BOTH);
}
/**
* Constructs a new text area with the specified text,
* and with the rows, columns, and scroll bar visibility
* as specified.
* <p>
* The <code>TextArea</code> class defines several constants
* that can be supplied as values for the
* <code>scrollbars</code> argument:
* <code>SCROLLBARS_BOTH</code>,
* <code>SCROLLBARS_VERTICAL_ONLY</code>,
* <code>SCROLLBARS_HORIZONTAL_ONLY</code>,
* and <code>SCROLLBARS_NONE</code>. Any other value for the
* <code>scrollbars</code> 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
* <code>text</code> is <code>null</code>, the empty
* string <code>""</code> will be displayed.
* @param rows the number of rows. If
* <code>rows</code> is less than <code>0</code>,
* <code>rows</code> is set to <code>0</code>.
* @param columns the number of columns. If
* <code>columns</code> is less than <code>0</code>,
* <code>columns</code> is set to <code>0</code>.
* @param scrollbars a constant that determines what
* scrollbars are created to view the text area.
* @since JDK1.1
*/
public TextArea(String text, int rows, int columns, int scrollbars) {
super(text);
this.rows = (rows >= 0) ? rows : 0;
this.columns = (columns >= 0) ? columns : 0;
if (scrollbars >= SCROLLBARS_BOTH && scrollbars <= SCROLLBARS_NONE) {
scrollbarVisibility = scrollbars;
} else {
scrollbarVisibility = SCROLLBARS_BOTH;
}
setFocusTraversalKeys(KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
forwardTraversalKeys);
setFocusTraversalKeys(KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
backwardTraversalKeys);
}
/**
* Construct a name for this component. Called by getName() when the
* name is null.
*/
String constructComponentName() {
return base + nameCounter++;
}
/**
* Creates the TextArea's peer. The peer allows us to modify
* the appearance of the TextArea without changing any of its
* functionality.
*/
public void addNotify() {
synchronized (getTreeLock()) {
if (peer == null)
peer = ((PeerBasedToolkit) getToolkit()).createTextArea(this);
super.addNotify();
}
}
/**
* Inserts the specified text at the specified position
* in this text area.
* @param str the 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
*/
public void insert(String str, int pos) {
insertText(str, pos);
}
/**
* @deprecated As of JDK version 1.1,
* replaced by <code>insert(String, int)</code>.
*/
public synchronized void insertText(String str, int pos) {
TextAreaPeer peer = (TextAreaPeer) this.peer;
if (peer != null) {
peer.insert(str, pos);
} else {
text = text.substring(0, pos) + str + text.substring(pos);
}
}
/**
* Appends the given text to the text area's current text.
* @param str the text to append.
* @see java.awt.TextArea#insert
*/
public void append(String str) {
appendText(str);
}
/**
* @deprecated As of JDK version 1.1,
* replaced by <code>append(String)</code>.
*/
public synchronized void appendText(String str) {
if (peer != null) {
insertText(str, getText().length());
} else {
text = text + str;
}
}
/**
* Replaces text between the indicated start and end positions
* with the specified replacement text.
* @param str the text to use as the replacement.
* @param start the start position.
* @param end the end position.
* @see java.awt.TextArea#insert
* @since JDK1.1
*/
public void replaceRange(String str, int start, int end) {
replaceText(str, start, end);
}
/**
* @deprecated As of JDK version 1.1,
* replaced by <code>replaceRange(String, int, int)</code>.
*/
public synchronized void replaceText(String str, int start, int end) {
TextAreaPeer peer = (TextAreaPeer) this.peer;
if (peer != null) {
peer.replaceRange(str, start, end);
} else {
text = text.substring(0, start) + str + text.substring(end);
}
}
/**
* Gets the number of rows in the text area.
* @return the number of rows in the text area.
* @see java.awt.TextArea#setRows
* @see java.awt.TextArea#getColumns
* @since JDK1
*/
public int getRows() {
return rows;
}
/**
* Sets the number of rows for this text area.
* @param rows the number of rows.
* @see java.awt.TextArea#getRows
* @see java.awt.TextArea#setColumns
* @exception IllegalArgumentException if the value
* supplied for <code>rows</code>
* is less than <code>0</code>.
* @since JDK1.1
*/
public void setRows(int rows) {
int oldVal = this.rows;
if (rows < 0) {
throw new IllegalArgumentException("rows less than zero.");
}
if (rows != oldVal) {
this.rows = rows;
invalidate();
}
}
/**
* Gets the number of columns in this text area.
* @return the number of columns in the text area.
* @see java.awt.TextArea#setColumns
* @see java.awt.TextArea#getRows
*/
public int getColumns() {
return columns;
}
/**
* Sets the number of columns for this text area.
* @param columns the number of columns.
* @see java.awt.TextArea#getColumns
* @see java.awt.TextArea#setRows
* @exception IllegalArgumentException if the value
* supplied for <code>columns</code>
* is less than <code>0</code>.
* @since JDK1.1
*/
public void setColumns(int columns) {
int oldVal = this.columns;
if (columns < 0) {
throw new IllegalArgumentException("columns less than zero.");
}
if (columns != oldVal) {
this.columns = columns;
invalidate();
}
}
/**
* Gets an enumerated value that indicates which scroll bars
* the text area uses.
* <p>
* The <code>TextArea</code> class defines four integer constants
* that are used to specify which scroll bars are available.
* <code>TextArea</code> 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
*/
public int getScrollbarVisibility() {
return scrollbarVisibility;
}
/**
* Determines the preferred size of a text area with the specified
* number of rows and columns.
* @param rows the number of rows.
* @param cols 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
*/
public Dimension getPreferredSize(int rows, int columns) {
return preferredSize(rows, columns);
}
/**
* @deprecated As of JDK version 1.1,
* replaced by <code>getPreferredSize(int, int)</code>.
*/
public Dimension preferredSize(int rows, int columns) {
synchronized (getTreeLock()) {
TextAreaPeer peer = (TextAreaPeer) this.peer;
return (peer != null) ?
peer.getPreferredSize(rows, columns) :
super.preferredSize();
}
}
/**
* 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
*/
public Dimension getPreferredSize() {
return preferredSize();
}
/**
* @deprecated As of JDK version 1.1,
* replaced by <code>getPreferredSize()</code>.
*/
public Dimension preferredSize() {
synchronized (getTreeLock()) {
return ((rows > 0) && (columns > 0)) ?
preferredSize(rows, columns) :
super.preferredSize();
}
}
/**
* Determines the minimum size of a text area with the specified
* number of rows and columns.
* @param rows the number of rows.
* @param cols 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
*/
public Dimension getMinimumSize(int rows, int columns) {
return minimumSize(rows, columns);
}
/**
* @deprecated As of JDK version 1.1,
* replaced by <code>getMinimumSize(int, int)</code>.
*/
public Dimension minimumSize(int rows, int columns) {
synchronized (getTreeLock()) {
TextAreaPeer peer = (TextAreaPeer) this.peer;
return (peer != null) ?
peer.getMinimumSize(rows, columns) :
super.minimumSize();
}
}
/**
* 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
*/
public Dimension getMinimumSize() {
return minimumSize();
}
/**
* @deprecated As of JDK version 1.1,
* replaced by <code>getMinimumSize()</code>.
*/
public Dimension minimumSize() {
synchronized (getTreeLock()) {
return ((rows > 0) && (columns > 0)) ?
minimumSize(rows, columns) :
super.minimumSize();
}
}
/**
* Returns the parameter string representing the state of
* this text area. This string is useful for debugging.
* @return the parameter string of this text area.
*/
protected String paramString() {
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;
}
/*
* Serialization support.
*/
/**
* The textArea Serialized Data Version.
*
* @serial
*/
private int textAreaSerializedDataVersion = 2;
/**
* Read the ObjectInputStream.
* @exception HeadlessException if
* <code>GraphicsEnvironment.isHeadless()</code> returns
* <code>true</code>
* @see java.awt.GraphicsEnvironment#isHeadless
*/
private void readObject(ObjectInputStream s)
throws ClassNotFoundException, IOException, HeadlessException
{
// 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);
}
}
}