TextArea


1   /*
2    * @(#)TextArea.java    1.78 04/05/18
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package java.awt;
8   
9   import java.awt.event.InputEvent  ;
10  import java.awt.event.KeyEvent  ;
11  import java.awt.peer.TextAreaPeer;
12  import java.io.ObjectOutputStream  ;
13  import java.io.ObjectInputStream  ;
14  import java.io.IOException  ;
15  import java.util.Set  ;
16  import java.util.TreeSet  ;
17  import javax.accessibility.*;
18  
19  /**
20   * A <code>TextArea</code> object is a multi-line region
21   * that displays text. It can be set to allow editing or
22   * to be read-only.
23   * <p>
24   * The following image shows the appearance of a text area:
25   * <p>
26   * <img SRC="doc-files/TextArea-1.gif" alt="A TextArea showing the word 'Hello!'"
27   * ALIGN=center HSPACE=10 VSPACE=7>
28   * <p>
29   * This text area could be created by the following line of code:
30   * <p>
31   * <hr><blockquote><pre>
32   * new TextArea("Hello", 5, 40);
33   * </pre></blockquote><hr>
34   * <p>
35   * @version 1.78, 05/18/04
36   * @author  Sami Shaio
37   * @since       JDK1.0
38   */
39  public class TextArea extends TextComponent   {
40  
41      /**
42       * The number of rows in the <code>TextArea</code>.
43       * This parameter will determine the text area's height.  
44       * Guaranteed to be non-negative.  
45       *
46       * @serial
47       * @see #getRows()
48       * @see #setRows(int)
49       */
50      int rows;
51  
52      /**
53       * The number of columns in the <code>TextArea</code>.
54       * A column is an approximate average character
55       * width that is platform-dependent.
56       * This parameter will determine the text area's width.  
57       * Guaranteed to be non-negative.  
58       *
59       * @serial
60       * @see  #setColumns(int)
61       * @see  #getColumns()
62       */
63      int columns;
64  
65      private static final String   base = "text";
66      private static int nameCounter = 0;
67  
68      /**
69       * Create and display both vertical and horizontal scrollbars.
70       * @since JDK1.1
71       */
72      public static final int SCROLLBARS_BOTH = 0;
73  
74      /**
75       * Create and display vertical scrollbar only.
76       * @since JDK1.1
77       */
78      public static final int SCROLLBARS_VERTICAL_ONLY = 1;
79  
80      /**
81       * Create and display horizontal scrollbar only.
82       * @since JDK1.1
83       */
84      public static final int SCROLLBARS_HORIZONTAL_ONLY = 2;
85  
86      /**
87       * Do not create or display any scrollbars for the text area.
88       * @since JDK1.1
89       */
90      public static final int SCROLLBARS_NONE = 3;
91  
92      /**
93       * Determines which scrollbars are created for the
94       * text area. It can be one of four values :
95       * <code>SCROLLBARS_BOTH</code> = both scrollbars.<BR>
96       * <code>SCROLLBARS_HORIZONTAL_ONLY</code> = Horizontal bar only.<BR>
97       * <code>SCROLLBARS_VERTICAL_ONLY</code> = Vertical bar only.<BR>
98       * <code>SCROLLBARS_NONE</code> = No scrollbars.<BR>
99       *
100      * @serial
101      * @see #getScrollbarVisibility()
102      */
103     private int scrollbarVisibility;
104 
105     /**
106      * Cache the Sets of forward and backward traversal keys so we need not
107      * look them up each time.
108      */
109     private static Set   forwardTraversalKeys, backwardTraversalKeys;
110 
111     /*
112      * JDK 1.1 serialVersionUID
113      */
114      private static final long serialVersionUID = 3692302836626095722L;
115 
116     /**
117      * Initialize JNI field and method ids
118      */
119     private static native void initIDs();
120 
121     static {
122         /* ensure that the necessary native libraries are loaded */
123     Toolkit.loadLibraries();
124         if (!GraphicsEnvironment.isHeadless()) {
125             initIDs();
126         }
127     forwardTraversalKeys = KeyboardFocusManager.initFocusTraversalKeysSet(
128         "ctrl TAB",
129         new TreeSet  ());
130     backwardTraversalKeys = KeyboardFocusManager.initFocusTraversalKeysSet(
131         "ctrl shift TAB",
132         new TreeSet  ());
133     }
134 
135     /**
136      * Constructs a new text area with the empty string as text.
137      * This text area is created with scrollbar visibility equal to 
138      * {@link #SCROLLBARS_BOTH}, so both vertical and horizontal 
139      * scrollbars will be visible for this text area.
140      * @exception HeadlessException if
141      *    <code>GraphicsEnvironment.isHeadless</code> returns true
142      * @see java.awt.GraphicsEnvironment#isHeadless()
143      */
144     public TextArea() throws HeadlessException   {
145     this("", 0, 0, SCROLLBARS_BOTH);
146     }
147 
148     /**
149      * Constructs a new text area with the specified text.
150      * This text area is created with scrollbar visibility equal to 
151      * {@link #SCROLLBARS_BOTH}, so both vertical and horizontal 
152      * scrollbars will be visible for this text area.
153      * @param      text       the text to be displayed; if
154      *             <code>text</code> is <code>null</code>, the empty
155      *             string <code>""</code> will be displayed
156      * @exception HeadlessException if
157      *        <code>GraphicsEnvironment.isHeadless</code> returns true
158      * @see java.awt.GraphicsEnvironment#isHeadless()
159      */
160     public TextArea(String   text) throws HeadlessException   {
161     this(text, 0, 0, SCROLLBARS_BOTH);
162     }
163 
164     /**
165      * Constructs a new text area with the specified number of
166      * rows and columns and the empty string as text. 
167      * A column is an approximate average character
168      * width that is platform-dependent.  The text area is created with 
169      * scrollbar visibility equal to {@link #SCROLLBARS_BOTH}, so both 
170      * vertical and horizontal scrollbars will be visible for this 
171      * text area.
172      * @param rows the number of rows
173      * @param columns the number of columns
174      * @exception HeadlessException if
175      *     <code>GraphicsEnvironment.isHeadless</code> returns true
176      * @see java.awt.GraphicsEnvironment#isHeadless()
177      */
178     public TextArea(int rows, int columns) throws HeadlessException   {
179     this("", rows, columns, SCROLLBARS_BOTH);
180     }
181 
182     /**
183      * Constructs a new text area with the specified text,
184      * and with the specified number of rows and columns.
185      * A column is an approximate average character
186      * width that is platform-dependent.  The text area is created with 
187      * scrollbar visibility equal to {@link #SCROLLBARS_BOTH}, so both 
188      * vertical and horizontal scrollbars will be visible for this 
189      * text area.
190      * @param      text       the text to be displayed; if
191      *             <code>text</code> is <code>null</code>, the empty
192      *             string <code>""</code> will be displayed
193      * @param     rows      the number of rows
194      * @param     columns   the number of columns
195      * @exception HeadlessException if
196      *   <code>GraphicsEnvironment.isHeadless</code> returns true
197      * @see java.awt.GraphicsEnvironment#isHeadless()
198      */
199     public TextArea(String   text, int rows, int columns)
200         throws HeadlessException   {
201         this(text, rows, columns, SCROLLBARS_BOTH);
202     }
203 
204     /**
205      * Constructs a new text area with the specified text,
206      * and with the rows, columns, and scroll bar visibility
207      * as specified.  All <code>TextArea</code> constructors defer to
208      * this one.
209      * <p>
210      * The <code>TextArea</code> class defines several constants
211      * that can be supplied as values for the
212      * <code>scrollbars</code> argument: 
213      * <ul>
214      * <li><code>SCROLLBARS_BOTH</code>, 
215      * <li><code>SCROLLBARS_VERTICAL_ONLY</code>, 
216      * <li><code>SCROLLBARS_HORIZONTAL_ONLY</code>, 
217      * <li><code>SCROLLBARS_NONE</code>.
218      * </ul>
219      * Any other value for the 
220      * <code>scrollbars</code> argument is invalid and will result in 
221      * this text area being created with scrollbar visibility equal to 
222      * the default value of {@link #SCROLLBARS_BOTH}.
223      * @param      text       the text to be displayed; if
224      *             <code>text</code> is <code>null</code>, the empty
225      *             string <code>""</code> will be displayed
226      * @param      rows       the number of rows; if
227      *             <code>rows</code> is less than <code>0</code>,
228      *             <code>rows</code> is set to <code>0</code>
229      * @param      columns    the number of columns; if
230      *             <code>columns</code> is less than <code>0</code>,
231      *             <code>columns</code> is set to <code>0</code>
232      * @param      scrollbars  a constant that determines what
233      *             scrollbars are created to view the text area
234      * @since      JDK1.1
235      * @exception HeadlessException if
236      *    <code>GraphicsEnvironment.isHeadless</code> returns true
237      * @see java.awt.GraphicsEnvironment#isHeadless()
238      */
239     public TextArea(String   text, int rows, int columns, int scrollbars)
240         throws HeadlessException   {
241     super(text);
242 
243         this.rows = (rows >= 0) ? rows : 0;
244         this.columns = (columns >= 0) ? columns : 0;
245 
246         if (scrollbars >= SCROLLBARS_BOTH && scrollbars <= SCROLLBARS_NONE) {
247             this.scrollbarVisibility = scrollbars;
248         } else {
249             this.scrollbarVisibility = SCROLLBARS_BOTH;
250         }
251 
252     setFocusTraversalKeys(KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
253                   forwardTraversalKeys);
254     setFocusTraversalKeys(KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
255                   backwardTraversalKeys);
256     }
257 
258     /**
259      * Construct a name for this component.  Called by <code>getName</code>
260      * when the name is <code>null</code>.
261      */
262     String   constructComponentName() {
263         synchronized (getClass()) {
264         return base + nameCounter++;
265     }
266     }
267 
268     /**
269      * Creates the <code>TextArea</code>'s peer.  The peer allows us to modify
270      * the appearance of the <code>TextArea</code> without changing any of its
271      * functionality.
272      */
273     public void addNotify() {
274         synchronized (getTreeLock()) {
275         if (peer == null)
276             peer = getToolkit().createTextArea(this);
277         super.addNotify();
278     }
279     }
280 
281     /**
282      * Inserts the specified text at the specified position
283      * in this text area.
284      * <p>Note that passing <code>null</code> or inconsistent
285      * parameters is invalid and will result in unspecified
286      * behavior.
287      *
288      * @param      str the non-<code>null</code> text to insert
289      * @param      pos the position at which to insert
290      * @see        java.awt.TextComponent#setText
291      * @see        java.awt.TextArea#replaceRange
292      * @see        java.awt.TextArea#append
293      * @since      JDK1.1
294      */
295     public void insert(String   str, int pos) {
296         insertText(str, pos);
297     }
298 
299     /**
300      * @deprecated As of JDK version 1.1,
301      * replaced by <code>insert(String, int)</code>.
302      */
303     @Deprecated  
304     public synchronized void insertText(String   str, int pos) {
305     TextAreaPeer peer = (TextAreaPeer)this.peer;
306     if (peer != null) {
307         peer.insertText(str, pos);
308     } else {
309         text = text.substring(0, pos) + str + text.substring(pos);
310     }
311     }
312 
313     /**
314      * Appends the given text to the text area's current text.
315      * <p>Note that passing <code>null</code> or inconsistent
316      * parameters is invalid and will result in unspecified
317      * behavior.
318      *
319      * @param     str the non-<code>null</code> text to append
320      * @see       java.awt.TextArea#insert
321      * @since     JDK1.1
322      */
323     public void append(String   str) {
324         appendText(str);
325     }
326 
327     /**
328      * @deprecated As of JDK version 1.1,
329      * replaced by <code>append(String)</code>.
330      */
331     @Deprecated  
332     public synchronized void appendText(String   str) {
333     if (peer != null) {
334         insertText(str, getText().length());
335     } else {
336         text = text + str;
337     }
338     }
339 
340     /**
341      * Replaces text between the indicated start and end positions
342      * with the specified replacement text.  The text at the end 
343      * position will not be replaced.  The text at the start 
344      * position will be replaced (unless the start position is the 
345      * same as the end position).  
346      * The text position is zero-based.  The inserted substring may be 
347      * of a different length than the text it replaces.
348      * <p>Note that passing <code>null</code> or inconsistent
349      * parameters is invalid and will result in unspecified
350      * behavior.
351      *
352      * @param     str      the non-<code>null</code> text to use as
353      *                     the replacement
354      * @param     start    the start position
355      * @param     end      the end position
356      * @see       java.awt.TextArea#insert
357      * @since     JDK1.1
358      */
359     public void replaceRange(String   str, int start, int end) {
360     replaceText(str, start, end);
361     }
362 
363     /**
364      * @deprecated As of JDK version 1.1,
365      * replaced by <code>replaceRange(String, int, int)</code>.
366      */
367     @Deprecated  
368     public synchronized void replaceText(String   str, int start, int end) {
369     TextAreaPeer peer = (TextAreaPeer)this.peer;
370     if (peer != null) {
371         peer.replaceText(str, start, end);
372     } else {
373         text = text.substring(0, start) + str + text.substring(end);
374     }
375     }
376 
377     /**
378      * Returns the number of rows in the text area.
379      * @return    the number of rows in the text area
380      * @see       #setRows(int)
381      * @see       #getColumns()
382      * @since     JDK1
383      */
384     public int getRows() {
385     return rows;
386     }
387 
388     /**
389      * Sets the number of rows for this text area.
390      * @param       rows   the number of rows
391      * @see         #getRows()
392      * @see         #setColumns(int)
393      * @exception   IllegalArgumentException   if the value
394      *                 supplied for <code>rows</code>
395      *                 is less than <code>0</code>
396      * @since       JDK1.1
397      */
398     public void setRows(int rows) {
399     int oldVal = this.rows;
400     if (rows < 0) {
401         throw new IllegalArgumentException  ("rows less than zero.");
402     }
403     if (rows != oldVal) {
404         this.rows = rows;
405         invalidate();
406     }
407     }
408 
409     /**
410      * Returns the number of columns in this text area.
411      * @return    the number of columns in the text area
412      * @see       #setColumns(int)
413      * @see       #getRows()
414      */
415     public int getColumns() {
416     return columns;
417     }
418 
419     /**
420      * Sets the number of columns for this text area.
421      * @param       columns   the number of columns
422      * @see         #getColumns()
423      * @see         #setRows(int)
424      * @exception   IllegalArgumentException   if the value
425      *                 supplied for <code>columns</code>
426      *                 is less than <code>0</code>
427      * @since       JDK1.1
428      */
429     public void setColumns(int columns) {
430     int oldVal = this.columns;
431     if (columns < 0) {
432         throw new IllegalArgumentException  ("columns less than zero.");
433     }
434     if (columns != oldVal) {
435         this.columns = columns;
436         invalidate();
437     }
438     }
439 
440     /**
441      * Returns an enumerated value that indicates which scroll bars
442      * the text area uses.
443      * <p>
444      * The <code>TextArea</code> class defines four integer constants
445      * that are used to specify which scroll bars are available.
446      * <code>TextArea</code> has one constructor that gives the
447      * application discretion over scroll bars.
448      *
449      * @return     an integer that indicates which scroll bars are used
450      * @see        java.awt.TextArea#SCROLLBARS_BOTH
451      * @see        java.awt.TextArea#SCROLLBARS_VERTICAL_ONLY
452      * @see        java.awt.TextArea#SCROLLBARS_HORIZONTAL_ONLY
453      * @see        java.awt.TextArea#SCROLLBARS_NONE
454      * @see        java.awt.TextArea#TextArea(java.lang.String, int, int, int)
455      * @since      JDK1.1
456      */
457     public int getScrollbarVisibility() {
458         return scrollbarVisibility;
459     }
460 
461 
462     /**
463      * Determines the preferred size of a text area with the specified
464      * number of rows and columns.
465      * @param     rows   the number of rows
466      * @param     columns   the number of columns
467      * @return    the preferred dimensions required to display
468      *                       the text area with the specified
469      *                       number of rows and columns
470      * @see       java.awt.Component#getPreferredSize
471      * @since     JDK1.1
472      */
473     public Dimension   getPreferredSize(int rows, int columns) {
474         return preferredSize(rows, columns);
475     }
476 
477     /**
478      * @deprecated As of JDK version 1.1,
479      * replaced by <code>getPreferredSize(int, int)</code>.
480      */
481     @Deprecated  
482     public Dimension   preferredSize(int rows, int columns) {
483         synchronized (getTreeLock()) {
484         TextAreaPeer peer = (TextAreaPeer)this.peer;
485         return (peer != null) ? 
486                peer.preferredSize(rows, columns) :
487                super.preferredSize();
488         }
489     }
490 
491     /**
492      * Determines the preferred size of this text area.
493      * @return    the preferred dimensions needed for this text area
494      * @see       java.awt.Component#getPreferredSize
495      * @since     JDK1.1
496      */
497     public Dimension   getPreferredSize() {
498     return preferredSize();
499     }
500 
501     /**
502      * @deprecated As of JDK version 1.1,
503      * replaced by <code>getPreferredSize()</code>.
504      */
505     @Deprecated  
506     public Dimension   preferredSize() {
507         synchronized (getTreeLock()) {
508         return ((rows > 0) && (columns > 0)) ? 
509             preferredSize(rows, columns) :
510             super.preferredSize();
511         }
512     }
513 
514     /**
515      * Determines the minimum size of a text area with the specified
516      * number of rows and columns.
517      * @param     rows   the number of rows
518      * @param     columns   the number of columns
519      * @return    the minimum dimensions required to display
520      *                       the text area with the specified
521      *                       number of rows and columns
522      * @see       java.awt.Component#getMinimumSize
523      * @since     JDK1.1
524      */
525     public Dimension   getMinimumSize(int rows, int columns) {
526         return minimumSize(rows, columns);
527     }
528 
529     /**
530      * @deprecated As of JDK version 1.1,
531      * replaced by <code>getMinimumSize(int, int)</code>.
532      */
533     @Deprecated  
534     public Dimension   minimumSize(int rows, int columns) {
535         synchronized (getTreeLock()) {
536         TextAreaPeer peer = (TextAreaPeer)this.peer;
537         return (peer != null) ? 
538                peer.minimumSize(rows, columns) :
539                super.minimumSize();
540         }
541     }
542 
543     /**
544      * Determines the minimum size of this text area.
545      * @return    the preferred dimensions needed for this text area
546      * @see       java.awt.Component#getPreferredSize
547      * @since     JDK1.1
548      */
549     public Dimension   getMinimumSize() {
550     return minimumSize();
551     }
552 
553     /**
554      * @deprecated As of JDK version 1.1,
555      * replaced by <code>getMinimumSize()</code>.
556      */
557     @Deprecated  
558     public Dimension   minimumSize() {
559         synchronized (getTreeLock()) {
560         return ((rows > 0) && (columns > 0)) ? 
561             minimumSize(rows, columns) :
562             super.minimumSize();
563         }
564     }
565 
566     /**
567      * Returns a string representing the state of this <code>TextArea</code>.
568      * This method is intended to be used only for debugging purposes, and the 
569      * content and format of the returned string may vary between 
570      * implementations. The returned string may be empty but may not be 
571      * <code>null</code>.
572      *
573      * @return      the parameter string of this text area
574      */
575     protected String   paramString() {
576     String   sbVisStr;
577     switch (scrollbarVisibility) {
578         case SCROLLBARS_BOTH:
579         sbVisStr = "both";
580         break;
581         case SCROLLBARS_VERTICAL_ONLY:
582         sbVisStr = "vertical-only";
583         break;
584         case SCROLLBARS_HORIZONTAL_ONLY:
585         sbVisStr = "horizontal-only";
586         break;
587         case SCROLLBARS_NONE:
588         sbVisStr = "none";
589         break;
590         default:
591         sbVisStr = "invalid display policy";
592     }
593 
594     return super.paramString() + ",rows=" + rows +
595         ",columns=" + columns +
596       ",scrollbarVisibility=" + sbVisStr;
597     }
598 
599 
600     /*
601      * Serialization support.
602      */
603     /**
604      * The textArea Serialized Data Version.
605      *
606      * @serial
607      */
608     private int textAreaSerializedDataVersion = 2;
609 
610     /**
611      * Read the ObjectInputStream.  
612      * @exception HeadlessException if
613      * <code>GraphicsEnvironment.isHeadless()</code> returns
614      * <code>true</code>
615      * @see java.awt.GraphicsEnvironment#isHeadless
616      */
617     private void readObject(ObjectInputStream   s)
618       throws ClassNotFoundException  , IOException  , HeadlessException  
619     {
620         // HeadlessException will be thrown by TextComponent's readObject
621         s.defaultReadObject();
622 
623         // Make sure the state we just read in for columns, rows, 
624         // and scrollbarVisibility has legal values
625         if (columns < 0) {
626             columns = 0;
627         }
628         if (rows < 0) {
629             rows = 0;
630         }
631 
632         if ((scrollbarVisibility < SCROLLBARS_BOTH) || 
633             (scrollbarVisibility > SCROLLBARS_NONE)) {
634             this.scrollbarVisibility = SCROLLBARS_BOTH;
635         }
636 
637     if (textAreaSerializedDataVersion < 2) {
638         setFocusTraversalKeys(KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
639                   forwardTraversalKeys);
640         setFocusTraversalKeys(KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
641                   backwardTraversalKeys);
642     }
643     }
644 
645 
646 /////////////////
647 // Accessibility support
648 ////////////////
649 
650 
651     /**
652      * Returns the <code>AccessibleContext</code> associated with
653      * this <code>TextArea</code>. For text areas, the
654      * <code>AccessibleContext</code> takes the form of an 
655      * <code>AccessibleAWTTextArea</code>. 
656      * A new <code>AccessibleAWTTextArea</code> instance is created if necessary.
657      *
658      * @return an <code>AccessibleAWTTextArea</code> that serves as the 
659      *         <code>AccessibleContext</code> of this <code>TextArea</code>
660      */
661     public AccessibleContext getAccessibleContext() {
662         if (accessibleContext == null) {
663             accessibleContext = new AccessibleAWTTextArea();
664         }
665         return accessibleContext;
666     }
667 
668     /**
669      * This class implements accessibility support for the 
670      * <code>TextArea</code> class.  It provides an implementation of the 
671      * Java Accessibility API appropriate to text area user-interface elements.
672      */
673     protected class AccessibleAWTTextArea extends AccessibleAWTTextComponent
674     {
675         /*
676          * JDK 1.3 serialVersionUID
677          */
678         private static final long serialVersionUID = 3472827823632144419L;
679 
680         /**
681          * Gets the state set of this object.
682          *
683          * @return an instance of AccessibleStateSet describing the states
684          * of the object
685          * @see AccessibleStateSet
686          */
687         public AccessibleStateSet getAccessibleStateSet() {
688             AccessibleStateSet states = super.getAccessibleStateSet();
689             states.add(AccessibleState.MULTI_LINE);
690             return states;
691         }
692     }
693 
694 
695 }
696
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags