1 /* TextArea.java -- A multi-line text entry component
2 Copyright (C) 1999, 2004 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
41 import java
.awt
.event
.KeyEvent
;
42 import java
.awt
.peer
.ComponentPeer
;
43 import java
.awt
.peer
.TextAreaPeer
;
44 import java
.util
.HashSet
;
47 import javax
.accessibility
.AccessibleContext
;
48 import javax
.accessibility
.AccessibleStateSet
;
52 * A TextArea is a text component capable of displaying multiple lines
53 * of user-editable text. A TextArea handles its own scrolling and
54 * can display vertical and horizontal scrollbars as navigation aids.
56 * @author Aaron M. Renn (arenn@urbanophile.com)
58 public class TextArea
extends TextComponent
implements java
.io
.Serializable
61 * Display both horiztonal and vertical scroll bars.
63 public static final int SCROLLBARS_BOTH
= 0;
66 * Display vertical scroll bar only.
68 public static final int SCROLLBARS_VERTICAL_ONLY
= 1;
71 * Display horizatonal scroll bar only.
73 public static final int SCROLLBARS_HORIZONTAL_ONLY
= 2;
76 * Do not display scrollbars.
78 public static final int SCROLLBARS_NONE
= 3;
81 * Serialization constant.
83 private static final long serialVersionUID
= 3692302836626095722L;
86 * @serial The number of columns used in this text area's preferred
87 * and minimum size calculations.
92 * @serial The number of rows used in this text area's preferred and
93 * minimum size calculations.
98 * @serial The scrollbar display policy. One of SCROLLBARS_BOTH,
99 * SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY,
102 private int scrollbarVisibility
;
105 * The number used to generate the name returned by getName.
107 private static transient long next_text_number
;
110 * Initialize a new instance of <code>TextArea</code> that is empty.
111 * Conceptually the <code>TextArea</code> has 0 rows and 0 columns
112 * but its initial bounds are defined by its peer or by the
113 * container in which it is packed. Both horizontal and vertical
114 * scrollbars will be displayed.
116 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
120 this ("", 0, 0, SCROLLBARS_BOTH
);
124 * Initialize a new instance of <code>TextArea</code> that contains
125 * the specified text. Conceptually the <code>TextArea</code> has 0
126 * rows and 0 columns but its initial bounds are defined by its peer
127 * or by the container in which it is packed. Both horizontal and
128 * veritcal scrollbars will be displayed.
130 * @param text The text to display in this text area.
132 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
134 public TextArea (String text
)
136 this (text
, 0, 0, SCROLLBARS_BOTH
);
140 * Initialize a new instance of <code>TextArea</code> that is empty
141 * and can display the specified number of rows and columns of text,
142 * without the need to scroll. Both horizontal and vertical
143 * scrollbars will be displayed.
145 * @param rows The number of rows in this text area.
146 * @param columns The number of columns in this text area.
148 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
150 public TextArea (int rows
, int columns
)
152 this ("", rows
, columns
, SCROLLBARS_BOTH
);
156 * Initialize a new instance of <code>TextArea</code> that can
157 * display the specified number of rows and columns of text, without
158 * the need to scroll. The TextArea initially contains the
161 * @param text The text to display in this text area.
162 * @param rows The number of rows in this text area.
163 * @param columns The number of columns in this text area.
165 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
167 public TextArea (String text
, int rows
, int columns
)
169 this (text
, rows
, columns
, SCROLLBARS_BOTH
);
173 * Initialize a new instance of <code>TextArea</code> that initially
174 * contains the specified text. The TextArea can display the
175 * specified number of rows and columns of text, without the need to
176 * scroll. This constructor allows specification of the scroll bar
179 * @param text The text to display in this text area.
180 * @param rows The number of rows in this text area.
181 * @param columns The number of columns in this text area.
182 * @param scrollbarVisibility The scroll bar display policy. One of
183 * SCROLLBARS_BOTH, SCROLLBARS_VERTICAL_ONLY,
184 * SCROLLBARS_HORIZONTAL_ONLY, SCROLLBARS_NONE.
186 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
188 public TextArea (String text
, int rows
, int columns
, int scrollbarVisibility
)
192 if (GraphicsEnvironment
.isHeadless ())
193 throw new HeadlessException ();
195 if (rows
< 0 || columns
< 0)
196 throw new IllegalArgumentException ("Bad row or column value");
198 if (scrollbarVisibility
!= SCROLLBARS_BOTH
199 && scrollbarVisibility
!= SCROLLBARS_VERTICAL_ONLY
200 && scrollbarVisibility
!= SCROLLBARS_HORIZONTAL_ONLY
201 && scrollbarVisibility
!= SCROLLBARS_NONE
)
202 throw new IllegalArgumentException ("Bad scrollbar visibility value");
205 this.columns
= columns
;
206 this.scrollbarVisibility
= scrollbarVisibility
;
208 // TextAreas need to receive tab key events so we override the
209 // default forward and backward traversal key sets.
210 Set s
= new HashSet ();
211 s
.add (AWTKeyStroke
.getAWTKeyStroke (KeyEvent
.VK_TAB
,
212 KeyEvent
.CTRL_DOWN_MASK
));
213 setFocusTraversalKeys (KeyboardFocusManager
.FORWARD_TRAVERSAL_KEYS
, s
);
215 s
.add (AWTKeyStroke
.getAWTKeyStroke (KeyEvent
.VK_TAB
,
216 KeyEvent
.SHIFT_DOWN_MASK
217 | KeyEvent
.CTRL_DOWN_MASK
));
218 setFocusTraversalKeys (KeyboardFocusManager
.BACKWARD_TRAVERSAL_KEYS
, s
);
222 * Retrieve the number of columns that this text area would prefer
223 * to display. This value may or may not correspond to the number
224 * of columns that are actually displayed.
226 * @return The preferred number of columns.
228 public int getColumns ()
234 * Set the preferred number of columns for this text area. This
235 * method does not cause the number of columns displayed by the text
236 * area to be updated, if the text area is currently visible.
238 * @param columns The preferred number of columns.
240 * @exception IllegalArgumentException If columns is less than zero.
242 public synchronized void setColumns (int columns
)
245 throw new IllegalArgumentException ("Value is less than zero: "
248 this.columns
= columns
;
252 * Retrieve the number of rows that this text area would prefer to
253 * display. This value may or may not correspond to the number of
254 * rows that are actually displayed.
256 * @return The preferred number of rows.
258 public int getRows ()
264 * Set the preferred number of rows for this text area. This method
265 * does not cause the number of columns displayed by the text area
266 * to be updated, if the text area is currently visible.
268 * @param rows The preferred number of rows.
270 * @exception IllegalArgumentException If rows is less than zero.
272 public synchronized void setRows (int rows
)
275 throw new IllegalArgumentException ("Value is less than one: " + rows
);
281 * Retrieve the minimum size for this text area, considering the
282 * text area's current row and column values. A text area's minimum
283 * size depends on the number of rows and columns of text it would
284 * prefer to display, and on the size of the font in which the text
285 * would be displayed.
287 * @return The minimum size for this text field.
289 public Dimension
getMinimumSize ()
291 return getMinimumSize (getRows (), getColumns ());
295 * Retrieve the minimum size that this text area would have if its
296 * row and column values were equal to those specified. A text
297 * area's minimum size depends on the number of rows and columns of
298 * text it would prefer to display, and on the size of the font in
299 * which the text would be displayed.
301 * @param rows The number of rows to use in the minimum size
303 * @param columns The number of columns to use in the minimum size
306 * @return The minimum size for this text area.
308 public Dimension
getMinimumSize (int rows
, int columns
)
310 return minimumSize (rows
, columns
);
314 * Retrieve the minimum size for this text area, considering the
315 * text area's current row and column values. A text area's minimum
316 * size depends on the number of rows and columns of text it would
317 * prefer to display, and on the size of the font in which the text
318 * would be displayed.
320 * @return The minimum size for this text area.
322 * @deprecated This method is deprecated in favor of
323 * <code>getMinimumSize ()</code>.
325 public Dimension
minimumSize ()
327 return minimumSize (getRows (), getColumns ());
331 * Retrieve the minimum size that this text area would have if its
332 * row and column values were equal to those specified. A text
333 * area's minimum size depends on the number of rows and columns of
334 * text it would prefer to display, and on the size of the font in
335 * which the text would be displayed.
337 * @param rows The number of rows to use in the minimum size
339 * @param columns The number of columns to use in the minimum size
342 * @return The minimum size for this text area.
344 * @deprecated This method is deprecated in favor of
345 * <code>getMinimumSize (int, int)</code>.
347 public Dimension
minimumSize (int rows
, int columns
)
349 TextAreaPeer peer
= (TextAreaPeer
) getPeer ();
351 // Sun returns Dimension (0,0) in this case.
353 return new Dimension (0, 0);
355 return peer
.getMinimumSize (rows
, columns
);
359 * Retrieve the preferred size for this text area, considering the
360 * text area's current row and column values. A text area's preferred
361 * size depends on the number of rows and columns of text it would
362 * prefer to display, and on the size of the font in which the text
363 * would be displayed.
365 * @return The preferred size for this text field.
367 public Dimension
getPreferredSize ()
369 return getPreferredSize (getRows (), getColumns ());
373 * Retrieve the preferred size that this text area would have if its
374 * row and column values were equal to those specified. A text
375 * area's preferred size depends on the number of rows and columns
376 * of text it would prefer to display, and on the size of the font
377 * in which the text would be displayed.
379 * @param rows The number of rows to use in the preferred size
381 * @param columns The number of columns to use in the preferred size
384 * @return The preferred size for this text area.
386 public Dimension
getPreferredSize (int rows
, int columns
)
388 return preferredSize (rows
, columns
);
392 * Retrieve the preferred size for this text area, considering the
393 * text area's current row and column values. A text area's preferred
394 * size depends on the number of rows and columns of text it would
395 * prefer to display, and on the size of the font in which the text
396 * would be displayed.
398 * @return The preferred size for this text field.
400 * @deprecated This method is deprecated in favor of
401 * <code>getPreferredSize ()</code>.
403 public Dimension
preferredSize ()
405 return preferredSize (getRows (), getColumns ());
409 * Retrieve the preferred size that this text area would have if its
410 * row and column values were equal to those specified. A text
411 * area's preferred size depends on the number of rows and columns
412 * of text it would prefer to display, and on the size of the font
413 * in which the text would be displayed.
415 * @param rows The number of rows to use in the preferred size
417 * @param columns The number of columns to use in the preferred size
420 * @return The preferred size for this text area.
422 * @deprecated This method is deprecated in favor of
423 * <code>getPreferredSize (int, int)</code>.
425 public Dimension
preferredSize (int rows
, int columns
)
427 TextAreaPeer peer
= (TextAreaPeer
) getPeer ();
429 // Sun returns Dimension (0,0) in this case.
431 return new Dimension (0, 0);
433 return peer
.getPreferredSize (rows
, columns
);
437 * Retrieve the scroll bar display policy -- one of SCROLLBARS_BOTH,
438 * SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY,
441 * @return The current scroll bar display policy.
443 public int getScrollbarVisibility ()
445 return scrollbarVisibility
;
449 * Notify this object that it should create its native peer.
451 public void addNotify ()
453 if (getPeer () == null)
454 setPeer ((ComponentPeer
) getToolkit().createTextArea (this));
458 * Append the specified text to the end of the current text.
460 * @param str The text to append.
462 public void append (String str
)
468 * Append the specified text to the end of the current text.
470 * @param str The text to append.
472 * @deprecated This method is deprecated in favor of
473 * <code>append ()</code>.
475 public void appendText (String str
)
477 TextAreaPeer peer
= (TextAreaPeer
) getPeer ();
480 peer
.insert (str
, peer
.getText().length ());
484 * Insert the specified text at the specified position. The first
485 * character in the text area is at position zero.
487 * @param str The text to insert.
488 * @param pos The position at which to insert text.
490 public void insert (String str
, int pos
)
492 insertText (str
, pos
);
496 * Insert the specified text at the specified position. The first
497 * character in the text area is at position zero.
499 * @param str The text to insert.
500 * @param pos The position at which to insert text.
502 * @deprecated This method is deprecated in favor of
503 * <code>insert ()</code>.
505 public void insertText (String str
, int pos
)
507 TextAreaPeer peer
= (TextAreaPeer
) getPeer ();
510 peer
.insert (str
, pos
);
514 * Replace a range of characters with the specified text. The
515 * character at the start position will be replaced, unless start ==
516 * end. The character at the end posistion will not be replaced.
517 * The first character in the text area is at position zero. The
518 * length of the replacement text may differ from the length of the
519 * text that is replaced.
521 * @param str The new text for the range.
522 * @param start The start position of the replacement range.
523 * @param end The end position of the replacement range.
525 public void replaceRange (String str
, int start
, int end
)
527 replaceText (str
, start
, end
);
531 * Replace a range of characters with the specified text. The
532 * character at the start position will be replaced, unless start ==
533 * end. The character at the end posistion will not be replaced.
534 * The first character in the text area is at position zero. The
535 * length of the replacement text may differ from the length of the
536 * text that is replaced.
538 * @param str The new text for the range.
539 * @param start The start position of the replacement range.
540 * @param end The end position of the replacement range.
542 * @deprecated This method is deprecated in favor of
543 * <code>replaceRange ()</code>.
545 public void replaceText (String str
, int start
, int end
)
547 TextAreaPeer peer
= (TextAreaPeer
) getPeer ();
550 peer
.replaceRange (str
, start
, end
);
554 * Retrieve a debugging string for this text area.
556 * @return A debugging string for this text area.
558 protected String
paramString ()
560 String sbVisibility
= "";
562 switch (scrollbarVisibility
)
564 case SCROLLBARS_BOTH
:
565 sbVisibility
= "both";
567 case SCROLLBARS_VERTICAL_ONLY
:
568 sbVisibility
= "vertical-only";
570 case SCROLLBARS_HORIZONTAL_ONLY
:
571 sbVisibility
= "horizontal-only";
573 case SCROLLBARS_NONE
:
574 sbVisibility
= "none";
578 String editable
= "";
580 editable
= "editable,";
582 return getName () + "," + getX () + "," + getY () + "," + getWidth ()
583 + "x" + getHeight () + "," + "text=" + getText () + "," + editable
584 + "selection=" + getSelectionStart () + "-" + getSelectionEnd ()
585 + ",rows=" + rows
+ ",columns=" + columns
+ ",scrollbarVisibility="
590 * Generate a unique name for this text area.
592 * @return A unique name for this text area.
594 String
generateName ()
596 return "text" + getUniqueLong ();
599 private static synchronized long getUniqueLong ()
601 return next_text_number
++;
604 protected class AccessibleAWTTextArea
extends AccessibleAWTTextComponent
606 protected AccessibleAWTTextArea()
610 public AccessibleStateSet
getAccessibleStateSet()
612 return super.getAccessibleStateSet();
617 * Gets the AccessibleContext associated with this <code>TextArea</code>.
618 * The context is created, if necessary.
620 * @return the associated context
622 public AccessibleContext
getAccessibleContext()
624 /* Create the context if this is the first request */
625 if (accessibleContext
== null)
626 accessibleContext
= new AccessibleAWTTextArea();
627 return accessibleContext
;