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.
 129:    *
 130:    * @param text The text to display in this text area.
 131:    *
 132:    * @exception HeadlessException if GraphicsEnvironment.isHeadless () is true
 133:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 443:   public int getScrollbarVisibility ()
 444:   {
 445:     return scrollbarVisibility;
 446:   }
 447: 
 448:   /**
 449:    * Notify this object that it should create its native peer.
 450:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 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:    */
 594:   String generateName ()
 595:   {
 596:     return "text" + getUniqueLong ();
 597:   }
 598: 
 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: 
 608:     protected AccessibleAWTTextArea()
 609:     {
 610:     }
 611:     
 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:    */
 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: }