Source for java.awt.TextArea

   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:    */
 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.  The TextArea initially contains
 129:    * the specified text.  If text specified as <code>null<code>, it will
 130:    * be set to "".
 131:    *
 132:    * @param text The text to display in this text area (<code>null</code> permitted).
 133:    *
 134:    * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
 135:    */
 136:   public TextArea (String text)
 137:   {
 138:     this (text, 0, 0, SCROLLBARS_BOTH);
 139:   }
 140: 
 141:   /**
 142:    * Initialize a new instance of <code>TextArea</code> that is empty
 143:    * and can display the specified number of rows and columns of text,
 144:    * without the need to scroll.  Both horizontal and vertical
 145:    * scrollbars will be displayed.
 146:    *
 147:    * @param rows The number of rows in this text area.
 148:    * @param columns The number of columns in this text area.
 149:    *
 150:    * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
 151:    */
 152:   public TextArea (int rows, int columns)
 153:   {
 154:     this ("", rows, columns, SCROLLBARS_BOTH);
 155:   }
 156: 
 157:   /**
 158:    * Initialize a new instance of <code>TextArea</code> that can
 159:    * display the specified number of rows and columns of text, without
 160:    * the need to scroll.  The TextArea initially contains the
 161:    * specified text.  If text specified as <code>null<code>, it will
 162:    * be set to "".
 163:    *
 164:    * @param text The text to display in this text area (<code>null</code> permitted).
 165:    * @param rows The number of rows in this text area.
 166:    * @param columns The number of columns in this text area.
 167:    *
 168:    * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
 169:    */
 170:   public TextArea (String text, int rows, int columns)
 171:   {
 172:     this (text, rows, columns, SCROLLBARS_BOTH);
 173:   }
 174: 
 175:   /**
 176:    * Initialize a new instance of <code>TextArea</code> that initially
 177:    * contains the specified text.  The TextArea can display the
 178:    * specified number of rows and columns of text, without the need to
 179:    * scroll.  This constructor allows specification of the scroll bar
 180:    * display policy.  The TextArea initially contains the specified text.  
 181:    * If text specified as <code>null<code>, it will be set to "". 
 182:    *
 183:    * @param text The text to display in this text area (<code>null</code> permitted).
 184:    * @param rows The number of rows in this text area.
 185:    * @param columns The number of columns in this text area.
 186:    * @param scrollbarVisibility The scroll bar display policy. One of
 187:    * SCROLLBARS_BOTH, SCROLLBARS_VERTICAL_ONLY,
 188:    * SCROLLBARS_HORIZONTAL_ONLY, SCROLLBARS_NONE.
 189:    *
 190:    * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
 191:    */
 192:   public TextArea (String text, int rows, int columns, int scrollbarVisibility)
 193:   {
 194:     super (text);
 195: 
 196:     if (GraphicsEnvironment.isHeadless ())
 197:       throw new HeadlessException ();
 198: 
 199:     if (rows < 0)
 200:       this.rows = 0;
 201:     else
 202:       this.rows = rows;
 203:     
 204:     if (columns < 0)
 205:       this.columns = 0;
 206:     else
 207:       this.columns = columns;
 208: 
 209:     if (scrollbarVisibility < 0 || scrollbarVisibility > 4)
 210:       this.scrollbarVisibility = SCROLLBARS_BOTH;
 211:     else
 212:       this.scrollbarVisibility = scrollbarVisibility;
 213: 
 214:     // TextAreas need to receive tab key events so we override the
 215:     // default forward and backward traversal key sets.
 216:     Set s = new HashSet ();
 217:     s.add (AWTKeyStroke.getAWTKeyStroke (KeyEvent.VK_TAB,
 218:                                          KeyEvent.CTRL_DOWN_MASK));
 219:     setFocusTraversalKeys (KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, s);
 220:     s = new HashSet ();
 221:     s.add (AWTKeyStroke.getAWTKeyStroke (KeyEvent.VK_TAB,
 222:                                          KeyEvent.SHIFT_DOWN_MASK
 223:                                          | KeyEvent.CTRL_DOWN_MASK));
 224:     setFocusTraversalKeys (KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, s);
 225:   }
 226: 
 227:   /**
 228:    * Retrieve the number of columns that this text area would prefer
 229:    * to display.  This value may or may not correspond to the number
 230:    * of columns that are actually displayed.
 231:    *
 232:    * @return The preferred number of columns.
 233:    */
 234:   public int getColumns ()
 235:   {
 236:     return columns;
 237:   }
 238: 
 239:   /**
 240:    * Set the preferred number of columns for this text area.  This
 241:    * method does not cause the number of columns displayed by the text
 242:    * area to be updated, if the text area is currently visible.
 243:    *
 244:    * @param columns The preferred number of columns.
 245:    *
 246:    * @exception IllegalArgumentException If columns is less than zero.
 247:    */
 248:   public synchronized void setColumns (int columns)
 249:   {
 250:     if (columns < 0)
 251:       throw new IllegalArgumentException ("Value is less than zero: "
 252:                                           + columns);
 253: 
 254:     this.columns = columns;
 255:   }
 256: 
 257:   /**
 258:    * Retrieve the number of rows that this text area would prefer to
 259:    * display.  This value may or may not correspond to the number of
 260:    * rows that are actually displayed.
 261:    *
 262:    * @return The preferred number of rows.
 263:    */
 264:   public int getRows ()
 265:   {
 266:     return rows;
 267:   }
 268: 
 269:   /**
 270:    * Set the preferred number of rows for this text area.  This method
 271:    * does not cause the number of columns displayed by the text area
 272:    * to be updated, if the text area is currently visible.
 273:    *
 274:    * @param rows The preferred number of rows.
 275:    *
 276:    * @exception IllegalArgumentException If rows is less than zero.
 277:    */
 278:   public synchronized void setRows (int rows)
 279:   {
 280:     if (rows < 1)
 281:       throw new IllegalArgumentException ("Value is less than one: " + rows);
 282: 
 283:     this.rows = rows;
 284:   }
 285: 
 286:   /**
 287:    * Retrieve the minimum size for this text area, considering the
 288:    * text area's current row and column values.  A text area's minimum
 289:    * size depends on the number of rows and columns of text it would
 290:    * prefer to display, and on the size of the font in which the text
 291:    * would be displayed.
 292:    *
 293:    * @return The minimum size for this text field.
 294:    */
 295:   public Dimension getMinimumSize ()
 296:   {
 297:     return getMinimumSize (getRows (), getColumns ());
 298:   }
 299: 
 300:   /**
 301:    * Retrieve the minimum size that this text area would have if its
 302:    * row and column values were equal to those specified.  A text
 303:    * area's minimum size depends on the number of rows and columns of
 304:    * text it would prefer to display, and on the size of the font in
 305:    * which the text would be displayed.
 306:    *
 307:    * @param rows The number of rows to use in the minimum size
 308:    * calculation.
 309:    * @param columns The number of columns to use in the minimum size
 310:    * calculation.
 311:    *
 312:    * @return The minimum size for this text area.
 313:    */
 314:   public Dimension getMinimumSize (int rows, int columns)
 315:   {
 316:     return minimumSize (rows, columns);
 317:   }
 318: 
 319:   /**
 320:    * Retrieve the minimum size for this text area, considering the
 321:    * text area's current row and column values.  A text area's minimum
 322:    * size depends on the number of rows and columns of text it would
 323:    * prefer to display, and on the size of the font in which the text
 324:    * would be displayed.
 325:    *
 326:    * @return The minimum size for this text area.
 327:    *
 328:    * @deprecated This method is deprecated in favor of
 329:    * <code>getMinimumSize ()</code>.
 330:    */
 331:   public Dimension minimumSize ()
 332:   {
 333:     return minimumSize (getRows (), getColumns ());
 334:   }
 335: 
 336:   /**
 337:    * Retrieve the minimum size that this text area would have if its
 338:    * row and column values were equal to those specified.  A text
 339:    * area's minimum size depends on the number of rows and columns of
 340:    * text it would prefer to display, and on the size of the font in
 341:    * which the text would be displayed.
 342:    *
 343:    * @param rows The number of rows to use in the minimum size
 344:    * calculation.
 345:    * @param columns The number of columns to use in the minimum size
 346:    * calculation.
 347:    *
 348:    * @return The minimum size for this text area.
 349:    *
 350:    * @deprecated This method is deprecated in favor of
 351:    * <code>getMinimumSize (int, int)</code>.
 352:    */
 353:   public Dimension minimumSize (int rows, int columns)
 354:   {
 355:     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 356: 
 357:     // Sun returns Dimension (0,0) in this case.
 358:     if (peer == null)
 359:       return new Dimension (0, 0);
 360: 
 361:     return peer.getMinimumSize (rows, columns);
 362:   }
 363: 
 364:   /**
 365:    * Retrieve the preferred size for this text area, considering the
 366:    * text area's current row and column values.  A text area's preferred
 367:    * size depends on the number of rows and columns of text it would
 368:    * prefer to display, and on the size of the font in which the text
 369:    * would be displayed.
 370:    *
 371:    * @return The preferred size for this text field.
 372:    */
 373:   public Dimension getPreferredSize ()
 374:   {
 375:     return getPreferredSize (getRows (), getColumns ());
 376:   }
 377: 
 378:   /**
 379:    * Retrieve the preferred size that this text area would have if its
 380:    * row and column values were equal to those specified.  A text
 381:    * area's preferred size depends on the number of rows and columns
 382:    * of text it would prefer to display, and on the size of the font
 383:    * in which the text would be displayed.
 384:    *
 385:    * @param rows The number of rows to use in the preferred size
 386:    * calculation.
 387:    * @param columns The number of columns to use in the preferred size
 388:    * calculation.
 389:    *
 390:    * @return The preferred size for this text area.
 391:    */
 392:   public Dimension getPreferredSize (int rows, int columns)
 393:   {
 394:     return preferredSize (rows, columns);
 395:   }
 396: 
 397:   /**
 398:    * Retrieve the preferred size for this text area, considering the
 399:    * text area's current row and column values.  A text area's preferred
 400:    * size depends on the number of rows and columns of text it would
 401:    * prefer to display, and on the size of the font in which the text
 402:    * would be displayed.
 403:    *
 404:    * @return The preferred size for this text field.
 405:    *
 406:    * @deprecated This method is deprecated in favor of
 407:    * <code>getPreferredSize ()</code>.
 408:    */
 409:   public Dimension preferredSize ()
 410:   {
 411:     return preferredSize (getRows (), getColumns ());
 412:   }
 413: 
 414:   /**
 415:    * Retrieve the preferred size that this text area would have if its
 416:    * row and column values were equal to those specified.  A text
 417:    * area's preferred size depends on the number of rows and columns
 418:    * of text it would prefer to display, and on the size of the font
 419:    * in which the text would be displayed.
 420:    *
 421:    * @param rows The number of rows to use in the preferred size
 422:    * calculation.
 423:    * @param columns The number of columns to use in the preferred size
 424:    * calculation.
 425:    *
 426:    * @return The preferred size for this text area.
 427:    *
 428:    * @deprecated This method is deprecated in favor of
 429:    * <code>getPreferredSize (int, int)</code>.
 430:    */
 431:   public Dimension preferredSize (int rows, int columns)
 432:   {
 433:     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 434: 
 435:     // Sun returns Dimension (0,0) in this case.
 436:     if (peer == null)
 437:       return new Dimension (0, 0);
 438: 
 439:     return peer.getPreferredSize (rows, columns);
 440:   }
 441: 
 442:   /**
 443:    * Retrieve the scroll bar display policy -- one of SCROLLBARS_BOTH,
 444:    * SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY,
 445:    * SCROLLBARS_NONE.
 446:    *
 447:    * @return The current scroll bar display policy.
 448:    */
 449:   public int getScrollbarVisibility ()
 450:   {
 451:     return scrollbarVisibility;
 452:   }
 453: 
 454:   /**
 455:    * Notify this object that it should create its native peer.
 456:    */
 457:   public void addNotify ()
 458:   {
 459:     if (getPeer () == null)
 460:       setPeer ((ComponentPeer) getToolkit().createTextArea (this));
 461:   }
 462: 
 463:   /**
 464:    * Append the specified text to the end of the current text.
 465:    *
 466:    * @param str The text to append.
 467:    */
 468:   public void append (String str)
 469:   {
 470:     appendText (str);
 471:   }
 472: 
 473:   /**
 474:    * Append the specified text to the end of the current text.
 475:    *
 476:    * @param str The text to append.
 477:    *
 478:    * @deprecated This method is deprecated in favor of
 479:    * <code>append ()</code>.
 480:    */
 481:   public void appendText (String str)
 482:   {
 483:     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 484: 
 485:     if (peer != null)
 486:       peer.insert (str, peer.getText().length ());
 487:     else
 488:       setText(getText() + str);   
 489:   }
 490: 
 491:   /**
 492:    * Insert the specified text at the specified position.  The first
 493:    * character in the text area is at position zero.
 494:    *
 495:    * @param str The text to insert.
 496:    * @param pos The position at which to insert text.
 497:    */
 498:   public void insert (String str, int pos)
 499:   {
 500:     insertText (str, pos);
 501:   }
 502: 
 503:   /**
 504:    * Insert the specified text at the specified position.  The first
 505:    * character in the text area is at position zero.
 506:    *
 507:    * @param str The text to insert.
 508:    * @param pos The position at which to insert text.
 509:    *
 510:    * @deprecated This method is deprecated in favor of
 511:    * <code>insert ()</code>.
 512:    */
 513:   public void insertText (String str, int pos)
 514:   {
 515:     String tmp1 = null;
 516:     String tmp2 = null;
 517:     
 518:     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 519: 
 520:     if (peer != null)
 521:       peer.insert (str, pos);
 522:     else
 523:       {
 524:         tmp1 = getText().substring(0, pos);
 525:         tmp2 = getText().substring(pos, getText().length());
 526:         setText(tmp1 + str + tmp2);
 527:       }
 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:   public void replaceRange (String str, int start, int end)
 543:   {
 544:     replaceText (str, start, end);
 545:   }
 546: 
 547:   /**
 548:    * Replace a range of characters with the specified text.  The
 549:    * character at the start position will be replaced, unless start ==
 550:    * end.  The character at the end posistion will not be replaced.
 551:    * The first character in the text area is at position zero.  The
 552:    * length of the replacement text may differ from the length of the
 553:    * text that is replaced.
 554:    *
 555:    * @param str The new text for the range.
 556:    * @param start The start position of the replacement range.
 557:    * @param end The end position of the replacement range.
 558:    *
 559:    * @deprecated This method is deprecated in favor of
 560:    * <code>replaceRange ()</code>.
 561:    */
 562:   public void replaceText (String str, int start, int end)
 563:   {
 564:     String tmp1 = null;
 565:     String tmp2 = null;
 566: 
 567:     TextAreaPeer peer = (TextAreaPeer) getPeer();
 568: 
 569:     if (peer != null)
 570:       peer.replaceRange(str, start, end);
 571:     else
 572:       {
 573:         tmp1 = getText().substring(0, start);
 574:         tmp2 = getText().substring(end, getText().length());
 575:         setText(tmp1 + str + tmp2);
 576:       }
 577:   }
 578: 
 579:   /**
 580:    * Retrieve a debugging string for this text area.
 581:    *
 582:    * @return A debugging string for this text area.
 583:    */
 584:   protected String paramString ()
 585:   {
 586:     String sbVisibility = "";
 587: 
 588:     switch (scrollbarVisibility)
 589:       {
 590:       case SCROLLBARS_BOTH:
 591:     sbVisibility = "both";
 592:     break;
 593:       case SCROLLBARS_VERTICAL_ONLY:
 594:     sbVisibility = "vertical-only";
 595:     break;
 596:       case SCROLLBARS_HORIZONTAL_ONLY:
 597:     sbVisibility = "horizontal-only";
 598:     break;
 599:       case SCROLLBARS_NONE:
 600:     sbVisibility = "none";
 601:     break;
 602:       }
 603: 
 604:     String editable = "";
 605:     if (isEditable ())
 606:       editable = "editable,";
 607: 
 608:     return getName () + "," + getX () + "," + getY () + "," + getWidth ()
 609:            + "x" + getHeight () + "," + "text=" + getText () + "," + editable
 610:            + "selection=" + getSelectionStart () + "-" + getSelectionEnd ()
 611:            + ",rows=" + rows + ",columns=" + columns + ",scrollbarVisibility="
 612:            + sbVisibility;
 613:   }
 614: 
 615:   /**
 616:    * Generate a unique name for this text area.
 617:    *
 618:    * @return A unique name for this text area.
 619:    */
 620:   String generateName ()
 621:   {
 622:     return "text" + getUniqueLong ();
 623:   }
 624: 
 625:   private static synchronized long getUniqueLong ()
 626:   {
 627:     return next_text_number++;
 628:   }
 629:   
 630:   protected class AccessibleAWTTextArea extends AccessibleAWTTextComponent
 631:   {
 632:     private static final long serialVersionUID = 3472827823632144419L;
 633: 
 634:     protected AccessibleAWTTextArea()
 635:     {
 636:     }
 637:     
 638:     public AccessibleStateSet getAccessibleStateSet()
 639:     {
 640:       return super.getAccessibleStateSet();
 641:     }
 642:   }
 643:   
 644:   /**
 645:    * Gets the AccessibleContext associated with this <code>TextArea</code>.
 646:    * The context is created, if necessary.
 647:    *
 648:    * @return the associated context
 649:    */
 650:   public AccessibleContext getAccessibleContext()
 651:   {
 652:     /* Create the context if this is the first request */
 653:     if (accessibleContext == null)
 654:       accessibleContext = new AccessibleAWTTextArea();
 655:     return accessibleContext;
 656:   }
 657: }