001: /*
002: * @(#)TextArea.java 1.62 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027: package java.awt;
028:
029: import java.io.ObjectOutputStream;
030: import java.io.ObjectInputStream;
031: import java.io.IOException;
032: import java.util.Set;
033: import java.util.TreeSet;
034: import sun.awt.peer.TextAreaPeer;
035: import sun.awt.PeerBasedToolkit;
036:
037: /**
038: * A <code>TextArea</code> object is a multi-line region
039: * that displays text. It can be set to allow editing or
040: * to be read-only.
041: * <p>
042: * The following image shows the appearance of a text area:
043: * <p>
044: * <img src="doc-files/TextArea-1.gif"
045: * ALIGN=center HSPACE=10 VSPACE=7>
046: * <p>
047: * This text area could be created by the following line of code:
048: * <p>
049: * <hr><blockquote><pre>
050: * new TextArea("Hello", 5, 40);
051: * </pre></blockquote><hr>
052: * <p>
053: * @version 1.56, 08/19/02
054: * @author Sami Shaio
055: * @since JDK1.0
056: */
057: public class TextArea extends TextComponent {
058: /**
059: * The number of rows in the TextArea.
060: * This parameter will determine the text area's height.
061: * Guaranteed to be non-negative.
062: *
063: * @serial
064: * @see getRows()
065: * @see setRows()
066: */
067: int rows;
068: /**
069: * The number of columns in the TextArea.
070: * A column is an approximate average character
071: * width that is platform-dependent.
072: * This parameter will determine the text area's width.
073: * Guaranteed to be non-negative.
074: *
075: * @serial
076: * @see getColumns()
077: * @see setColumns()
078: */
079: int columns;
080: private static final String base = "text";
081: private static int nameCounter = 0;
082: /**
083: * Create and display both vertical and horizontal scrollbars.
084: * @since JDK1.1
085: */
086: public static final int SCROLLBARS_BOTH = 0;
087: /**
088: * Create and display vertical scrollbar only.
089: * @since JDK1.1
090: */
091: public static final int SCROLLBARS_VERTICAL_ONLY = 1;
092: /**
093: * Create and display horizontal scrollbar only.
094: * @since JDK1.1
095: */
096: public static final int SCROLLBARS_HORIZONTAL_ONLY = 2;
097: /**
098: * Do not create or display any scrollbars for the text area.
099: * @since JDK1.1
100: */
101: public static final int SCROLLBARS_NONE = 3;
102: /**
103: * Determines which scrollbars are created for the
104: * text area. It can be one of four values :
105: * <code>SCROLLBARS_BOTH</code> = both scrollbars.<BR>
106: * <code>SCROLLBARS_HORIZONTAL_ONLY</code> = Horizontal bar only.<BR>
107: * <code>SCROLLBARS_VERTICAL_ONLY</code> = Vertical bar only.<BR>
108: * <code>SCROLLBARS_NONE</code> = No scrollbars.<BR>
109: *
110: * @serial
111: * @see getScrollbarVisibility()
112: */
113: private int scrollbarVisibility;
114:
115: /**
116: * Cache the Sets of forward and backward traversal keys so we need not
117: * look them up each time.
118: */
119: private static Set forwardTraversalKeys, backwardTraversalKeys;
120:
121: /*
122: * JDK 1.1 serialVersionUID
123: */
124: private static final long serialVersionUID = 3692302836626095722L;
125:
126: static {
127: forwardTraversalKeys = KeyboardFocusManager
128: .initFocusTraversalKeysSet("TAB", new TreeSet());
129: backwardTraversalKeys = KeyboardFocusManager
130: .initFocusTraversalKeysSet("shift TAB", new TreeSet());
131: }
132:
133: /**
134: * Constructs a new text area.
135: * This text area is created with scrollbar visibility equal to
136: * {@link #SCROLLBARS_BOTH}, so both vertical and horizontal
137: * scrollbars will be visible for this text area.
138: */
139: public TextArea() {
140: this ("", 0, 0, SCROLLBARS_BOTH);
141: }
142:
143: /**
144: * Constructs a new text area with the specified text.
145: * This text area is created with scrollbar visibility equal to
146: * {@link #SCROLLBARS_BOTH}, so both vertical and horizontal
147: * scrollbars will be visible for this text area.
148: * @param text the text to be displayed.
149: */
150: public TextArea(String text) {
151: this (text, 0, 0, SCROLLBARS_BOTH);
152: }
153:
154: /**
155: * Constructs a new empty text area with the specified number of
156: * rows and columns. A column is an approximate average character
157: * width that is platform-dependent. The text area is created with
158: * scrollbar visibility equal to {@link #SCROLLBARS_BOTH}, so both
159: * vertical and horizontal scrollbars will be visible for this
160: * text area.
161: * @param rows the number of rows
162: * @param columns the number of columns
163: */
164: public TextArea(int rows, int columns) {
165: this ("", rows, columns, SCROLLBARS_BOTH);
166: }
167:
168: /**
169: * Constructs a new text area with the specified text,
170: * and with the specified number of rows and columns.
171: * A column is an approximate average character
172: * width that is platform-dependent. The text area is created with
173: * scrollbar visibility equal to {@link #SCROLLBARS_BOTH}, so both
174: * vertical and horizontal scrollbars will be visible for this
175: * text area.
176: * @param text the text to be displayed.
177: * @param rows the number of rows.
178: * @param columns the number of columns.
179: */
180: public TextArea(String text, int rows, int columns) {
181: this (text, rows, columns, SCROLLBARS_BOTH);
182: }
183:
184: /**
185: * Constructs a new text area with the specified text,
186: * and with the rows, columns, and scroll bar visibility
187: * as specified.
188: * <p>
189: * The <code>TextArea</code> class defines several constants
190: * that can be supplied as values for the
191: * <code>scrollbars</code> argument:
192: * <code>SCROLLBARS_BOTH</code>,
193: * <code>SCROLLBARS_VERTICAL_ONLY</code>,
194: * <code>SCROLLBARS_HORIZONTAL_ONLY</code>,
195: * and <code>SCROLLBARS_NONE</code>. Any other value for the
196: * <code>scrollbars</code> argument is invalid and will result in
197: * this text area being created with scrollbar visibility equal to
198: * the default value of {@link #SCROLLBARS_BOTH}.
199: * @param text the text to be displayed. If
200: * <code>text</code> is <code>null</code>, the empty
201: * string <code>""</code> will be displayed.
202: * @param rows the number of rows. If
203: * <code>rows</code> is less than <code>0</code>,
204: * <code>rows</code> is set to <code>0</code>.
205: * @param columns the number of columns. If
206: * <code>columns</code> is less than <code>0</code>,
207: * <code>columns</code> is set to <code>0</code>.
208: * @param scrollbars a constant that determines what
209: * scrollbars are created to view the text area.
210: * @since JDK1.1
211: */
212: public TextArea(String text, int rows, int columns, int scrollbars) {
213: super (text);
214: this .rows = (rows >= 0) ? rows : 0;
215: this .columns = (columns >= 0) ? columns : 0;
216: if (scrollbars >= SCROLLBARS_BOTH
217: && scrollbars <= SCROLLBARS_NONE) {
218: scrollbarVisibility = scrollbars;
219: } else {
220: scrollbarVisibility = SCROLLBARS_BOTH;
221: }
222:
223: setFocusTraversalKeys(
224: KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
225: forwardTraversalKeys);
226: setFocusTraversalKeys(
227: KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
228: backwardTraversalKeys);
229: }
230:
231: /**
232: * Construct a name for this component. Called by getName() when the
233: * name is null.
234: */
235: String constructComponentName() {
236: return base + nameCounter++;
237: }
238:
239: /**
240: * Creates the TextArea's peer. The peer allows us to modify
241: * the appearance of the TextArea without changing any of its
242: * functionality.
243: */
244: public void addNotify() {
245: synchronized (getTreeLock()) {
246: if (peer == null)
247: peer = ((PeerBasedToolkit) getToolkit())
248: .createTextArea(this );
249: super .addNotify();
250: }
251: }
252:
253: /**
254: * Inserts the specified text at the specified position
255: * in this text area.
256: * @param str the text to insert.
257: * @param pos the position at which to insert.
258: * @see java.awt.TextComponent#setText
259: * @see java.awt.TextArea#replaceRange
260: * @see java.awt.TextArea#append
261: * @since JDK1.1
262: */
263: public void insert(String str, int pos) {
264: insertText(str, pos);
265: }
266:
267: /**
268: * @deprecated As of JDK version 1.1,
269: * replaced by <code>insert(String, int)</code>.
270: */
271: public synchronized void insertText(String str, int pos) {
272: TextAreaPeer peer = (TextAreaPeer) this .peer;
273: if (peer != null) {
274: peer.insert(str, pos);
275: } else {
276: text = text.substring(0, pos) + str + text.substring(pos);
277: }
278: }
279:
280: /**
281: * Appends the given text to the text area's current text.
282: * @param str the text to append.
283: * @see java.awt.TextArea#insert
284: */
285: public void append(String str) {
286: appendText(str);
287: }
288:
289: /**
290: * @deprecated As of JDK version 1.1,
291: * replaced by <code>append(String)</code>.
292: */
293: public synchronized void appendText(String str) {
294: if (peer != null) {
295: insertText(str, getText().length());
296: } else {
297: text = text + str;
298: }
299: }
300:
301: /**
302: * Replaces text between the indicated start and end positions
303: * with the specified replacement text.
304: * @param str the text to use as the replacement.
305: * @param start the start position.
306: * @param end the end position.
307: * @see java.awt.TextArea#insert
308: * @since JDK1.1
309: */
310: public void replaceRange(String str, int start, int end) {
311: replaceText(str, start, end);
312: }
313:
314: /**
315: * @deprecated As of JDK version 1.1,
316: * replaced by <code>replaceRange(String, int, int)</code>.
317: */
318: public synchronized void replaceText(String str, int start, int end) {
319: TextAreaPeer peer = (TextAreaPeer) this .peer;
320: if (peer != null) {
321: peer.replaceRange(str, start, end);
322: } else {
323: text = text.substring(0, start) + str + text.substring(end);
324: }
325: }
326:
327: /**
328: * Gets the number of rows in the text area.
329: * @return the number of rows in the text area.
330: * @see java.awt.TextArea#setRows
331: * @see java.awt.TextArea#getColumns
332: * @since JDK1
333: */
334: public int getRows() {
335: return rows;
336: }
337:
338: /**
339: * Sets the number of rows for this text area.
340: * @param rows the number of rows.
341: * @see java.awt.TextArea#getRows
342: * @see java.awt.TextArea#setColumns
343: * @exception IllegalArgumentException if the value
344: * supplied for <code>rows</code>
345: * is less than <code>0</code>.
346: * @since JDK1.1
347: */
348: public void setRows(int rows) {
349: int oldVal = this .rows;
350: if (rows < 0) {
351: throw new IllegalArgumentException("rows less than zero.");
352: }
353: if (rows != oldVal) {
354: this .rows = rows;
355: invalidate();
356: }
357: }
358:
359: /**
360: * Gets the number of columns in this text area.
361: * @return the number of columns in the text area.
362: * @see java.awt.TextArea#setColumns
363: * @see java.awt.TextArea#getRows
364: */
365: public int getColumns() {
366: return columns;
367: }
368:
369: /**
370: * Sets the number of columns for this text area.
371: * @param columns the number of columns.
372: * @see java.awt.TextArea#getColumns
373: * @see java.awt.TextArea#setRows
374: * @exception IllegalArgumentException if the value
375: * supplied for <code>columns</code>
376: * is less than <code>0</code>.
377: * @since JDK1.1
378: */
379: public void setColumns(int columns) {
380: int oldVal = this .columns;
381: if (columns < 0) {
382: throw new IllegalArgumentException(
383: "columns less than zero.");
384: }
385: if (columns != oldVal) {
386: this .columns = columns;
387: invalidate();
388: }
389: }
390:
391: /**
392: * Gets an enumerated value that indicates which scroll bars
393: * the text area uses.
394: * <p>
395: * The <code>TextArea</code> class defines four integer constants
396: * that are used to specify which scroll bars are available.
397: * <code>TextArea</code> has one constructor that gives the
398: * application discretion over scroll bars.
399: * @return an integer that indicates which scroll bars are used.
400: * @see java.awt.TextArea#SCROLLBARS_BOTH
401: * @see java.awt.TextArea#SCROLLBARS_VERTICAL_ONLY
402: * @see java.awt.TextArea#SCROLLBARS_HORIZONTAL_ONLY
403: * @see java.awt.TextArea#SCROLLBARS_NONE
404: * @see java.awt.TextArea#TextArea(java.lang.String, int, int, int)
405: * @since JDK1.1
406: */
407: public int getScrollbarVisibility() {
408: return scrollbarVisibility;
409: }
410:
411: /**
412: * Determines the preferred size of a text area with the specified
413: * number of rows and columns.
414: * @param rows the number of rows.
415: * @param cols the number of columns.
416: * @return the preferred dimensions required to display
417: * the text area with the specified
418: * number of rows and columns.
419: * @see java.awt.Component#getPreferredSize
420: * @since JDK1.1
421: */
422: public Dimension getPreferredSize(int rows, int columns) {
423: return preferredSize(rows, columns);
424: }
425:
426: /**
427: * @deprecated As of JDK version 1.1,
428: * replaced by <code>getPreferredSize(int, int)</code>.
429: */
430: public Dimension preferredSize(int rows, int columns) {
431: synchronized (getTreeLock()) {
432: TextAreaPeer peer = (TextAreaPeer) this .peer;
433: return (peer != null) ? peer
434: .getPreferredSize(rows, columns) : super
435: .preferredSize();
436: }
437: }
438:
439: /**
440: * Determines the preferred size of this text area.
441: * @return the preferred dimensions needed for this text area.
442: * @see java.awt.Component#getPreferredSize
443: * @since JDK1.1
444: */
445: public Dimension getPreferredSize() {
446: return preferredSize();
447: }
448:
449: /**
450: * @deprecated As of JDK version 1.1,
451: * replaced by <code>getPreferredSize()</code>.
452: */
453: public Dimension preferredSize() {
454: synchronized (getTreeLock()) {
455: return ((rows > 0) && (columns > 0)) ? preferredSize(rows,
456: columns) : super .preferredSize();
457: }
458: }
459:
460: /**
461: * Determines the minimum size of a text area with the specified
462: * number of rows and columns.
463: * @param rows the number of rows.
464: * @param cols the number of columns.
465: * @return the minimum dimensions required to display
466: * the text area with the specified
467: * number of rows and columns.
468: * @see java.awt.Component#getMinimumSize
469: * @since JDK1.1
470: */
471: public Dimension getMinimumSize(int rows, int columns) {
472: return minimumSize(rows, columns);
473: }
474:
475: /**
476: * @deprecated As of JDK version 1.1,
477: * replaced by <code>getMinimumSize(int, int)</code>.
478: */
479: public Dimension minimumSize(int rows, int columns) {
480: synchronized (getTreeLock()) {
481: TextAreaPeer peer = (TextAreaPeer) this .peer;
482: return (peer != null) ? peer.getMinimumSize(rows, columns)
483: : super .minimumSize();
484: }
485: }
486:
487: /**
488: * Determines the minimum size of this text area.
489: * @return the preferred dimensions needed for this text area.
490: * @see java.awt.Component#getPreferredSize
491: * @since JDK1.1
492: */
493: public Dimension getMinimumSize() {
494: return minimumSize();
495: }
496:
497: /**
498: * @deprecated As of JDK version 1.1,
499: * replaced by <code>getMinimumSize()</code>.
500: */
501: public Dimension minimumSize() {
502: synchronized (getTreeLock()) {
503: return ((rows > 0) && (columns > 0)) ? minimumSize(rows,
504: columns) : super .minimumSize();
505: }
506: }
507:
508: /**
509: * Returns the parameter string representing the state of
510: * this text area. This string is useful for debugging.
511: * @return the parameter string of this text area.
512: */
513: protected String paramString() {
514: String sbVisStr;
515: switch (scrollbarVisibility) {
516: case SCROLLBARS_BOTH:
517: sbVisStr = "both";
518: break;
519:
520: case SCROLLBARS_VERTICAL_ONLY:
521: sbVisStr = "vertical-only";
522: break;
523:
524: case SCROLLBARS_HORIZONTAL_ONLY:
525: sbVisStr = "horizontal-only";
526: break;
527:
528: case SCROLLBARS_NONE:
529: sbVisStr = "none";
530: break;
531:
532: default:
533: sbVisStr = "invalid display policy";
534: }
535: return super .paramString() + ",rows=" + rows + ",columns="
536: + columns + ", scrollbarVisibility=" + sbVisStr;
537: }
538:
539: /*
540: * Serialization support.
541: */
542: /**
543: * The textArea Serialized Data Version.
544: *
545: * @serial
546: */
547: private int textAreaSerializedDataVersion = 2;
548:
549: /**
550: * Read the ObjectInputStream.
551: * @exception HeadlessException if
552: * <code>GraphicsEnvironment.isHeadless()</code> returns
553: * <code>true</code>
554: * @see java.awt.GraphicsEnvironment#isHeadless
555: */
556: private void readObject(ObjectInputStream s)
557: throws ClassNotFoundException, IOException,
558: HeadlessException {
559: // HeadlessException will be thrown by TextComponent's readObject
560: s.defaultReadObject();
561:
562: // Make sure the state we just read in for columns, rows,
563: // and scrollbarVisibility has legal values
564: if (columns < 0) {
565: columns = 0;
566: }
567: if (rows < 0) {
568: rows = 0;
569: }
570:
571: if ((scrollbarVisibility < SCROLLBARS_BOTH)
572: || (scrollbarVisibility > SCROLLBARS_NONE)) {
573: this .scrollbarVisibility = SCROLLBARS_BOTH;
574: }
575:
576: if (textAreaSerializedDataVersion < 2) {
577: setFocusTraversalKeys(
578: KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
579: forwardTraversalKeys);
580: setFocusTraversalKeys(
581: KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
582: backwardTraversalKeys);
583: }
584: }
585:
586: }
|