1 /* TextArea.java -- A multi-line text entry component 2 Copyright (C) 1999, 2004 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 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) 9 any later version. 10 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. 15 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., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 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 24 combination. 25 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. */ 37 38 39 package java.awt; 40 41 import java.awt.event.KeyEvent; 42 import java.awt.peer.ComponentPeer; 43 import java.awt.peer.TextAreaPeer; 44 import java.util.HashSet; 45 import java.util.Set; 46 47 import javax.accessibility.AccessibleContext; 48 import javax.accessibility.AccessibleStateSet; 49 50 51 /** 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. 55 * 56 * @author Aaron M. Renn (arenn@urbanophile.com) 57 */ 58 public class TextArea extends TextComponent implements java.io.Serializable 59 { 60 /** 61 * Display both horiztonal and vertical scroll bars. 62 */ 63 public static final int SCROLLBARS_BOTH = 0; 64 65 /** 66 * Display vertical scroll bar only. 67 */ 68 public static final int SCROLLBARS_VERTICAL_ONLY = 1; 69 70 /** 71 * Display horizatonal scroll bar only. 72 */ 73 public static final int SCROLLBARS_HORIZONTAL_ONLY = 2; 74 75 /** 76 * Do not display scrollbars. 77 */ 78 public static final int SCROLLBARS_NONE = 3; 79 80 /** 81 * Serialization constant. 82 */ 83 private static final long serialVersionUID = 3692302836626095722L; 84 85 /** 86 * @serial The number of columns used in this text area's preferred 87 * and minimum size calculations. 88 */ 89 private int columns; 90 91 /** 92 * @serial The number of rows used in this text area's preferred and 93 * minimum size calculations. 94 */ 95 private int rows; 96 97 /** 98 * @serial The scrollbar display policy. One of SCROLLBARS_BOTH, 99 * SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY, 100 * SCROLLBARS_NONE. 101 */ 102 private int scrollbarVisibility; 103 104 /* 105 * The number used to generate the name returned by getName. 106 */ 107 private static transient long next_text_number; 108 109 /** 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. 115 * 116 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true 117 */ TextArea()118 public TextArea () 119 { 120 this ("", 0, 0, SCROLLBARS_BOTH); 121 } 122 123 /** 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. 129 * 130 * @param text The text to display in this text area. 131 * 132 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true 133 */ TextArea(String text)134 public TextArea (String text) 135 { 136 this (text, 0, 0, SCROLLBARS_BOTH); 137 } 138 139 /** 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. 144 * 145 * @param rows The number of rows in this text area. 146 * @param columns The number of columns in this text area. 147 * 148 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true 149 */ TextArea(int rows, int columns)150 public TextArea (int rows, int columns) 151 { 152 this ("", rows, columns, SCROLLBARS_BOTH); 153 } 154 155 /** 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 159 * specified text. 160 * 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. 164 * 165 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true 166 */ TextArea(String text, int rows, int columns)167 public TextArea (String text, int rows, int columns) 168 { 169 this (text, rows, columns, SCROLLBARS_BOTH); 170 } 171 172 /** 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 177 * display policy. 178 * 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. 185 * 186 * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true 187 */ TextArea(String text, int rows, int columns, int scrollbarVisibility)188 public TextArea (String text, int rows, int columns, int scrollbarVisibility) 189 { 190 super (text); 191 192 if (GraphicsEnvironment.isHeadless ()) 193 throw new HeadlessException (); 194 195 if (rows < 0 || columns < 0) 196 throw new IllegalArgumentException ("Bad row or column value"); 197 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"); 203 204 this.rows = rows; 205 this.columns = columns; 206 this.scrollbarVisibility = scrollbarVisibility; 207 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); 214 s = new HashSet (); 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); 219 } 220 221 /** 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. 225 * 226 * @return The preferred number of columns. 227 */ getColumns()228 public int getColumns () 229 { 230 return columns; 231 } 232 233 /** 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. 237 * 238 * @param columns The preferred number of columns. 239 * 240 * @exception IllegalArgumentException If columns is less than zero. 241 */ setColumns(int columns)242 public synchronized void setColumns (int columns) 243 { 244 if (columns < 0) 245 throw new IllegalArgumentException ("Value is less than zero: " 246 + columns); 247 248 this.columns = columns; 249 } 250 251 /** 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. 255 * 256 * @return The preferred number of rows. 257 */ getRows()258 public int getRows () 259 { 260 return rows; 261 } 262 263 /** 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. 267 * 268 * @param rows The preferred number of rows. 269 * 270 * @exception IllegalArgumentException If rows is less than zero. 271 */ setRows(int rows)272 public synchronized void setRows (int rows) 273 { 274 if (rows < 1) 275 throw new IllegalArgumentException ("Value is less than one: " + rows); 276 277 this.rows = rows; 278 } 279 280 /** 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. 286 * 287 * @return The minimum size for this text field. 288 */ getMinimumSize()289 public Dimension getMinimumSize () 290 { 291 return getMinimumSize (getRows (), getColumns ()); 292 } 293 294 /** 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. 300 * 301 * @param rows The number of rows to use in the minimum size 302 * calculation. 303 * @param columns The number of columns to use in the minimum size 304 * calculation. 305 * 306 * @return The minimum size for this text area. 307 */ getMinimumSize(int rows, int columns)308 public Dimension getMinimumSize (int rows, int columns) 309 { 310 return minimumSize (rows, columns); 311 } 312 313 /** 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. 319 * 320 * @return The minimum size for this text area. 321 * 322 * @deprecated This method is deprecated in favor of 323 * <code>getMinimumSize ()</code>. 324 */ minimumSize()325 public Dimension minimumSize () 326 { 327 return minimumSize (getRows (), getColumns ()); 328 } 329 330 /** 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. 336 * 337 * @param rows The number of rows to use in the minimum size 338 * calculation. 339 * @param columns The number of columns to use in the minimum size 340 * calculation. 341 * 342 * @return The minimum size for this text area. 343 * 344 * @deprecated This method is deprecated in favor of 345 * <code>getMinimumSize (int, int)</code>. 346 */ minimumSize(int rows, int columns)347 public Dimension minimumSize (int rows, int columns) 348 { 349 TextAreaPeer peer = (TextAreaPeer) getPeer (); 350 351 // Sun returns Dimension (0,0) in this case. 352 if (peer == null) 353 return new Dimension (0, 0); 354 355 return peer.getMinimumSize (rows, columns); 356 } 357 358 /** 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. 364 * 365 * @return The preferred size for this text field. 366 */ getPreferredSize()367 public Dimension getPreferredSize () 368 { 369 return getPreferredSize (getRows (), getColumns ()); 370 } 371 372 /** 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. 378 * 379 * @param rows The number of rows to use in the preferred size 380 * calculation. 381 * @param columns The number of columns to use in the preferred size 382 * calculation. 383 * 384 * @return The preferred size for this text area. 385 */ getPreferredSize(int rows, int columns)386 public Dimension getPreferredSize (int rows, int columns) 387 { 388 return preferredSize (rows, columns); 389 } 390 391 /** 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. 397 * 398 * @return The preferred size for this text field. 399 * 400 * @deprecated This method is deprecated in favor of 401 * <code>getPreferredSize ()</code>. 402 */ preferredSize()403 public Dimension preferredSize () 404 { 405 return preferredSize (getRows (), getColumns ()); 406 } 407 408 /** 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. 414 * 415 * @param rows The number of rows to use in the preferred size 416 * calculation. 417 * @param columns The number of columns to use in the preferred size 418 * calculation. 419 * 420 * @return The preferred size for this text area. 421 * 422 * @deprecated This method is deprecated in favor of 423 * <code>getPreferredSize (int, int)</code>. 424 */ preferredSize(int rows, int columns)425 public Dimension preferredSize (int rows, int columns) 426 { 427 TextAreaPeer peer = (TextAreaPeer) getPeer (); 428 429 // Sun returns Dimension (0,0) in this case. 430 if (peer == null) 431 return new Dimension (0, 0); 432 433 return peer.getPreferredSize (rows, columns); 434 } 435 436 /** 437 * Retrieve the scroll bar display policy -- one of SCROLLBARS_BOTH, 438 * SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY, 439 * SCROLLBARS_NONE. 440 * 441 * @return The current scroll bar display policy. 442 */ getScrollbarVisibility()443 public int getScrollbarVisibility () 444 { 445 return scrollbarVisibility; 446 } 447 448 /** 449 * Notify this object that it should create its native peer. 450 */ addNotify()451 public void addNotify () 452 { 453 if (getPeer () == null) 454 setPeer ((ComponentPeer) getToolkit().createTextArea (this)); 455 } 456 457 /** 458 * Append the specified text to the end of the current text. 459 * 460 * @param str The text to append. 461 */ append(String str)462 public void append (String str) 463 { 464 appendText (str); 465 } 466 467 /** 468 * Append the specified text to the end of the current text. 469 * 470 * @param str The text to append. 471 * 472 * @deprecated This method is deprecated in favor of 473 * <code>append ()</code>. 474 */ appendText(String str)475 public void appendText (String str) 476 { 477 TextAreaPeer peer = (TextAreaPeer) getPeer (); 478 479 if (peer != null) 480 peer.insert (str, peer.getText().length ()); 481 } 482 483 /** 484 * Insert the specified text at the specified position. The first 485 * character in the text area is at position zero. 486 * 487 * @param str The text to insert. 488 * @param pos The position at which to insert text. 489 */ insert(String str, int pos)490 public void insert (String str, int pos) 491 { 492 insertText (str, pos); 493 } 494 495 /** 496 * Insert the specified text at the specified position. The first 497 * character in the text area is at position zero. 498 * 499 * @param str The text to insert. 500 * @param pos The position at which to insert text. 501 * 502 * @deprecated This method is deprecated in favor of 503 * <code>insert ()</code>. 504 */ insertText(String str, int pos)505 public void insertText (String str, int pos) 506 { 507 TextAreaPeer peer = (TextAreaPeer) getPeer (); 508 509 if (peer != null) 510 peer.insert (str, pos); 511 } 512 513 /** 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. 520 * 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. 524 */ replaceRange(String str, int start, int end)525 public void replaceRange (String str, int start, int end) 526 { 527 replaceText (str, start, end); 528 } 529 530 /** 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. 537 * 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. 541 * 542 * @deprecated This method is deprecated in favor of 543 * <code>replaceRange ()</code>. 544 */ replaceText(String str, int start, int end)545 public void replaceText (String str, int start, int end) 546 { 547 TextAreaPeer peer = (TextAreaPeer) getPeer (); 548 549 if (peer != null) 550 peer.replaceRange (str, start, end); 551 } 552 553 /** 554 * Retrieve a debugging string for this text area. 555 * 556 * @return A debugging string for this text area. 557 */ paramString()558 protected String paramString () 559 { 560 String sbVisibility = ""; 561 562 switch (scrollbarVisibility) 563 { 564 case SCROLLBARS_BOTH: 565 sbVisibility = "both"; 566 break; 567 case SCROLLBARS_VERTICAL_ONLY: 568 sbVisibility = "vertical-only"; 569 break; 570 case SCROLLBARS_HORIZONTAL_ONLY: 571 sbVisibility = "horizontal-only"; 572 break; 573 case SCROLLBARS_NONE: 574 sbVisibility = "none"; 575 break; 576 } 577 578 String editable = ""; 579 if (isEditable ()) 580 editable = "editable,"; 581 582 return getName () + "," + getX () + "," + getY () + "," + getWidth () 583 + "x" + getHeight () + "," + "text=" + getText () + "," + editable 584 + "selection=" + getSelectionStart () + "-" + getSelectionEnd () 585 + ",rows=" + rows + ",columns=" + columns + ",scrollbarVisibility=" 586 + sbVisibility; 587 } 588 589 /** 590 * Generate a unique name for this text area. 591 * 592 * @return A unique name for this text area. 593 */ generateName()594 String generateName () 595 { 596 return "text" + getUniqueLong (); 597 } 598 getUniqueLong()599 private static synchronized long getUniqueLong () 600 { 601 return next_text_number++; 602 } 603 604 protected class AccessibleAWTTextArea extends AccessibleAWTTextComponent 605 { 606 private static final long serialVersionUID = 3472827823632144419L; 607 AccessibleAWTTextArea()608 protected AccessibleAWTTextArea() 609 { 610 } 611 getAccessibleStateSet()612 public AccessibleStateSet getAccessibleStateSet() 613 { 614 return super.getAccessibleStateSet(); 615 } 616 } 617 618 /** 619 * Gets the AccessibleContext associated with this <code>TextArea</code>. 620 * The context is created, if necessary. 621 * 622 * @return the associated context 623 */ getAccessibleContext()624 public AccessibleContext getAccessibleContext() 625 { 626 /* Create the context if this is the first request */ 627 if (accessibleContext == null) 628 accessibleContext = new AccessibleAWTTextArea(); 629 return accessibleContext; 630 } 631 } 632