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.
 288:    *
 289:    * @return The minimum size for this text field.
 290:    */
 291:   public Dimension getMinimumSize ()
 292:   {
 293:     return getMinimumSize (getRows (), getColumns ());
 294:   }
 295: 
 296:   /**
 297:    * Retrieve the minimum size for this text area.  If the minimum
 298:    * size has been set, then rows and columns are used in the calculation.
 299:    *
 300:    * @param rows The number of rows to use in the minimum size
 301:    * calculation.
 302:    * @param columns The number of columns to use in the minimum size
 303:    * calculation.
 304:    *
 305:    * @return The minimum size for this text area.
 306:    */
 307:   public Dimension getMinimumSize (int rows, int columns)
 308:   {
 309:     return minimumSize (rows, columns);
 310:   }
 311: 
 312:   /**
 313:    * Retrieve the minimum size for this text area.
 314:    * 
 315:    * @return The minimum size for this text area.
 316:    *
 317:    * @deprecated This method is deprecated in favor of
 318:    * <code>getMinimumSize ()</code>.
 319:    */
 320:   public Dimension minimumSize ()
 321:   {
 322:     return minimumSize (getRows (), getColumns ());
 323:   }
 324: 
 325:   /**
 326:    * Retrieve the minimum size for this text area.  If the minimum
 327:    * size has been set, then rows and columns are used in the calculation.
 328:    *
 329:    * @param rows The number of rows to use in the minimum size
 330:    * calculation.
 331:    * @param columns The number of columns to use in the minimum size
 332:    * calculation.
 333:    *
 334:    * @return The minimum size for this text area.
 335:    *
 336:    * @deprecated This method is deprecated in favor of
 337:    * <code>getMinimumSize (int, int)</code>.
 338:    */
 339:   public Dimension minimumSize (int rows, int columns)
 340:   {
 341:     if (isMinimumSizeSet())
 342:       return new Dimension(minSize);
 343:     
 344:     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 345:     if (peer == null)
 346:       return new Dimension (getWidth(), getHeight());
 347: 
 348:     return peer.getMinimumSize (rows, columns);
 349:   }
 350: 
 351:   /**
 352:    * Retrieve the preferred size for this text area.
 353:    *
 354:    * @return The preferred size for this text field.
 355:    */
 356:   public Dimension getPreferredSize ()
 357:   {
 358:     return getPreferredSize (getRows (), getColumns ());
 359:   }
 360: 
 361:   /**
 362:    * Retrieve the preferred size for this text area.  If the preferred
 363:    * size has been set, then rows and columns are used in the calculation.
 364:    *
 365:    * @param rows The number of rows to use in the preferred size
 366:    * calculation.
 367:    * @param columns The number of columns to use in the preferred size
 368:    * calculation.
 369:    *
 370:    * @return The preferred size for this text area.
 371:    */
 372:   public Dimension getPreferredSize (int rows, int columns)
 373:   {
 374:     return preferredSize (rows, columns);
 375:   }
 376: 
 377:   /**
 378:    * Retrieve the preferred size for this text area.
 379:    *
 380:    * @return The preferred size for this text field.
 381:    *
 382:    * @deprecated This method is deprecated in favor of
 383:    * <code>getPreferredSize ()</code>.
 384:    */
 385:   public Dimension preferredSize ()
 386:   {
 387:     return preferredSize (getRows (), getColumns ());
 388:   }
 389: 
 390:   /**
 391:    * Retrieve the preferred size for this text area.  If the preferred
 392:    * size has been set, then rows and columns are used in the calculation.
 393:    *
 394:    * @param rows The number of rows to use in the preferred size
 395:    * calculation.
 396:    * @param columns The number of columns to use in the preferred size
 397:    * calculation.
 398:    *
 399:    * @return The preferred size for this text area.
 400:    *
 401:    * @deprecated This method is deprecated in favor of
 402:    * <code>getPreferredSize (int, int)</code>.
 403:    */
 404:   public Dimension preferredSize (int rows, int columns)
 405:   {
 406:     if (isPreferredSizeSet())
 407:       return new Dimension(prefSize);
 408:     
 409:     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 410:     if (peer == null)
 411:       return new Dimension (getWidth(), getHeight());
 412: 
 413:     return peer.getPreferredSize (rows, columns);
 414:   }
 415: 
 416:   /**
 417:    * Retrieve the scroll bar display policy -- one of SCROLLBARS_BOTH,
 418:    * SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY,
 419:    * SCROLLBARS_NONE.
 420:    *
 421:    * @return The current scroll bar display policy.
 422:    */
 423:   public int getScrollbarVisibility ()
 424:   {
 425:     return scrollbarVisibility;
 426:   }
 427: 
 428:   /**
 429:    * Notify this object that it should create its native peer.
 430:    */
 431:   public void addNotify ()
 432:   {
 433:     if (getPeer () == null)
 434:       setPeer ((ComponentPeer) getToolkit().createTextArea (this));
 435:   }
 436: 
 437:   /**
 438:    * Append the specified text to the end of the current text.
 439:    *
 440:    * @param str The text to append.
 441:    */
 442:   public void append (String str)
 443:   {
 444:     appendText (str);
 445:   }
 446: 
 447:   /**
 448:    * Append the specified text to the end of the current text.
 449:    *
 450:    * @param str The text to append.
 451:    *
 452:    * @deprecated This method is deprecated in favor of
 453:    * <code>append ()</code>.
 454:    */
 455:   public void appendText (String str)
 456:   {
 457:     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 458: 
 459:     if (peer != null)
 460:       peer.insert (str, peer.getText().length ());
 461:     else
 462:       setText(getText() + str);   
 463:   }
 464: 
 465:   /**
 466:    * Insert the specified text at the specified position.  The first
 467:    * character in the text area is at position zero.
 468:    *
 469:    * @param str The text to insert.
 470:    * @param pos The position at which to insert text.
 471:    */
 472:   public void insert (String str, int pos)
 473:   {
 474:     insertText (str, pos);
 475:   }
 476: 
 477:   /**
 478:    * Insert the specified text at the specified position.  The first
 479:    * character in the text area is at position zero.
 480:    *
 481:    * @param str The text to insert.
 482:    * @param pos The position at which to insert text.
 483:    *
 484:    * @deprecated This method is deprecated in favor of
 485:    * <code>insert ()</code>.
 486:    */
 487:   public void insertText (String str, int pos)
 488:   {
 489:     String tmp1 = null;
 490:     String tmp2 = null;
 491:     
 492:     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 493: 
 494:     if (peer != null)
 495:       peer.insert (str, pos);
 496:     else
 497:       {
 498:         tmp1 = getText().substring(0, pos);
 499:         tmp2 = getText().substring(pos, getText().length());
 500:         setText(tmp1 + str + tmp2);
 501:       }
 502:   }
 503: 
 504:   /**
 505:    * Replace a range of characters with the specified text.  The
 506:    * character at the start position will be replaced, unless start ==
 507:    * end.  The character at the end posistion will not be replaced.
 508:    * The first character in the text area is at position zero.  The
 509:    * length of the replacement text may differ from the length of the
 510:    * text that is replaced.
 511:    *
 512:    * @param str The new text for the range.
 513:    * @param start The start position of the replacement range.
 514:    * @param end The end position of the replacement range.
 515:    */
 516:   public void replaceRange (String str, int start, int end)
 517:   {
 518:     replaceText (str, start, end);
 519:   }
 520: 
 521:   /**
 522:    * Replace a range of characters with the specified text.  The
 523:    * character at the start position will be replaced, unless start ==
 524:    * end.  The character at the end posistion will not be replaced.
 525:    * The first character in the text area is at position zero.  The
 526:    * length of the replacement text may differ from the length of the
 527:    * text that is replaced.
 528:    *
 529:    * @param str The new text for the range.
 530:    * @param start The start position of the replacement range.
 531:    * @param end The end position of the replacement range.
 532:    *
 533:    * @deprecated This method is deprecated in favor of
 534:    * <code>replaceRange ()</code>.
 535:    */
 536:   public void replaceText (String str, int start, int end)
 537:   {
 538:     String tmp1 = null;
 539:     String tmp2 = null;
 540: 
 541:     TextAreaPeer peer = (TextAreaPeer) getPeer();
 542: 
 543:     if (peer != null)
 544:       peer.replaceRange(str, start, end);
 545:     else
 546:       {
 547:         tmp1 = getText().substring(0, start);
 548:         tmp2 = getText().substring(end, getText().length());
 549:         setText(tmp1 + str + tmp2);
 550:       }
 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: }