libjava/java/awt/TextArea.java

   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., 59 Temple Place, Suite 330, Boston, MA
  19    02111-1307 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 package java.awt;
  39
  40 import java.awt.peer.ComponentPeer;
  41 import java.awt.peer.TextAreaPeer;
  42
  43
  44 /**
  45  * A TextArea is a text component capable of displaying multiple lines
  46  * of user-editable text.  A TextArea handles its own scrolling and
  47  * can display vertical and horizontal scrollbars as navigation aids.
  48  *
  49  * @author Aaron M. Renn (arenn@urbanophile.com)
  50  */
  51 public class TextArea extends TextComponent implements java.io.Serializable
  52 {
  53   /**
  54    * Display both horiztonal and vertical scroll bars.
  55    */
  56   public static final int SCROLLBARS_BOTH = 0;
  57
  58   /**
  59    * Display vertical scroll bar only.
  60    */
  61   public static final int SCROLLBARS_VERTICAL_ONLY = 1;
  62
  63   /**
  64    * Display horizatonal scroll bar only.
  65    */
  66   public static final int SCROLLBARS_HORIZONTAL_ONLY = 2;
  67
  68   /**
  69    * Do not display scrollbars.
  70    */
  71   public static final int SCROLLBARS_NONE = 3;
  72
  73   /**
  74    * Serialization constant.
  75    */
  76   private static final long serialVersionUID = 3692302836626095722L;
  77
  78   /**
  79    * @serial The number of columns used in this text area's preferred
  80    * and minimum size calculations.
  81    */
  82   private int columns;
  83
  84   /**
  85    * @serial The number of rows used in this text area's preferred and
  86    * minimum size calculations.
  87    */
  88   private int rows;
  89
  90   /**
  91    * @serial The scrollbar display policy.  One of SCROLLBARS_BOTH,
  92    * SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY,
  93    * SCROLLBARS_NONE.
  94    */
  95   private int scrollbarVisibility;
  96
  97   /*
  98    * The number used to generate the name returned by getName.
  99    */
 100   private static transient long next_text_number = 0;
 101
 102   /**
 103    * Initialize a new instance of <code>TextArea</code> that is empty
 104    * and is one row by one column.  Both horizontal and vertical
 105    * scrollbars will be displayed.
 106    *
 107    * @exception HeadlessException If GraphicsEnvironment.isHeadless () is true,
 108    */
 109   public TextArea ()
 110   {
 111     this ("", 1, 1, SCROLLBARS_BOTH);
 112   }
 113
 114   /**
 115    * Initialize a new instance of <code>TextArea</code> that initially
 116    * contains the specified text.  Both horizontal and veritcal
 117    * scrollbars will be displayed.
 118    *
 119    * @param text The text to display in this text area.
 120    *
 121    * @exception HeadlessException If GraphicsEnvironment.isHeadless () is true,
 122    */
 123   public TextArea (String text)
 124   {
 125     this (text, 1, text.length (), SCROLLBARS_BOTH);
 126   }
 127
 128   /**
 129    * Initialize a new instance of <code>TextArea</code> that is empty
 130    * and can display the specified number of rows and columns of text,
 131    * without the need to scroll.  Both horizontal and vertical
 132    * scrollbars will be displayed.
 133    *
 134    * @param rows The number of rows in this text area.
 135    * @param columns The number of columns in this text area.
 136    *
 137    * @exception HeadlessException If GraphicsEnvironment.isHeadless () is true,
 138    */
 139   public TextArea (int rows, int columns)
 140   {
 141     this ("", rows, columns, SCROLLBARS_BOTH);
 142   }
 143
 144   /**
 145    * Initialize a new instance of <code>TextArea</code> that can
 146    * display the specified number of rows and columns of text, without
 147    * the need to scroll.  The TextArea initially contains the
 148    * specified text.
 149    *
 150    * @param text The text to display in this text area.
 151    * @param rows The number of rows in this text area.
 152    * @param columns The number of columns in this text area.
 153    *
 154    * @exception HeadlessException If GraphicsEnvironment.isHeadless () is true,
 155    */
 156   public TextArea (String text, int rows, int columns)
 157   {
 158     this (text, rows, columns, SCROLLBARS_BOTH);
 159   }
 160
 161   /**
 162    * Initialize a new instance of <code>TextArea</code> that initially
 163    * contains the specified text.  The TextArea can display the
 164    * specified number of rows and columns of text, without the need to
 165    * scroll.  This constructor allows specification of the scroll bar
 166    * display policy.
 167    *
 168    * @param text The text to display in this text area.
 169    * @param rows The number of rows in this text area.
 170    * @param columns The number of columns in this text area.
 171    * @param scrollbarVisibility The scroll bar display policy. One of
 172    * SCROLLBARS_BOTH, SCROLLBARS_VERTICAL_ONLY,
 173    * SCROLLBARS_HORIZONTAL_ONLY, SCROLLBARS_NONE.
 174    *
 175    * @exception HeadlessException If GraphicsEnvironment.isHeadless () is true,
 176    */
 177   public TextArea (String text, int rows, int columns, int scrollbarVisibility)
 178   {
 179     super (text);
 180
 181     if (GraphicsEnvironment.isHeadless ())
 182       throw new HeadlessException ();
 183
 184     if (rows < 1 || columns < 0)
 185       throw new IllegalArgumentException ("Bad row or column value");
 186
 187     if (scrollbarVisibility != SCROLLBARS_BOTH
 188         && scrollbarVisibility != SCROLLBARS_VERTICAL_ONLY
 189         && scrollbarVisibility != SCROLLBARS_HORIZONTAL_ONLY
 190         && scrollbarVisibility != SCROLLBARS_NONE)
 191       throw new IllegalArgumentException ("Bad scrollbar visibility value");
 192
 193     this.rows = rows;
 194     this.columns = columns;
 195     this.scrollbarVisibility = scrollbarVisibility;
 196   }
 197
 198   /*
 199    * Instance Variables
 200    */
 201
 202   /**
 203    * Retrieve the number of columns that this text area would prefer
 204    * to display.  This value may or may not correspond to the number
 205    * of columns that are actually displayed.
 206    *
 207    * @return The preferred number of columns.
 208    */
 209   public int getColumns ()
 210   {
 211     return columns;
 212   }
 213
 214   /**
 215    * Set the preferred number of columns for this text area.  This
 216    * method does not cause the number of columns displayed by the text
 217    * area to be updated, if the text area is currently visible.
 218    *
 219    * @param columns The preferred number of columns.
 220    *
 221    * @exception IllegalArgumentException If columns is less than zero.
 222    */
 223   public synchronized void setColumns (int columns)
 224   {
 225     if (columns < 0)
 226       throw new IllegalArgumentException ("Value is less than zero: "
 227                                           + columns);
 228
 229     this.columns = columns;
 230   }
 231
 232   /**
 233    * Retrieve the number of rows that this text area would prefer to
 234    * display.  This value may or may not correspond to the number of
 235    * rows that are actually displayed.
 236    *
 237    * @return The preferred number of rows.
 238    */
 239   public int getRows ()
 240   {
 241     return rows;
 242   }
 243
 244   /**
 245    * Set the preferred number of rows for this text area.  This method
 246    * does not cause the number of columns displayed by the text area
 247    * to be updated, if the text area is currently visible.
 248    *
 249    * @param rows The preferred number of rows.
 250    *
 251    * @exception IllegalArgumentException If rows is less than zero.
 252    */
 253   public synchronized void setRows (int rows)
 254   {
 255     if (rows < 1)
 256       throw new IllegalArgumentException ("Value is less than one: " + rows);
 257
 258     this.rows = rows;
 259   }
 260
 261   /**
 262    * Retrieve the minimum size for this text area, considering the
 263    * text area's current row and column values.  A text area's minimum
 264    * size depends on the number of rows and columns of text it would
 265    * prefer to display, and on the size of the font in which the text
 266    * would be displayed.
 267    *
 268    * @return The minimum size for this text field.
 269    */
 270   public Dimension getMinimumSize ()
 271   {
 272     return getMinimumSize (getRows (), getColumns ());
 273   }
 274
 275   /**
 276    * Retrieve the minimum size that this text area would have if its
 277    * row and column values were equal to those specified.  A text
 278    * area's minimum size depends on the number of rows and columns of
 279    * text it would prefer to display, and on the size of the font in
 280    * which the text would be displayed.
 281    *
 282    * @param rows The number of rows to use in the minimum size
 283    * calculation.
 284    * @param columns The number of columns to use in the minimum size
 285    * calculation.
 286    *
 287    * @return The minimum size for this text area.
 288    */
 289   public Dimension getMinimumSize (int rows, int columns)
 290   {
 291     return minimumSize (rows, columns);
 292   }
 293
 294   /**
 295    * Retrieve the minimum size for this text area, considering the
 296    * text area's current row and column values.  A text area's minimum
 297    * size depends on the number of rows and columns of text it would
 298    * prefer to display, and on the size of the font in which the text
 299    * would be displayed.
 300    *
 301    * @return The minimum size for this text area.
 302    *
 303    * @deprecated This method is deprecated in favor of
 304    * <code>getMinimumSize ()</code>.
 305    */
 306   public Dimension minimumSize ()
 307   {
 308     return minimumSize (getRows (), getColumns ());
 309   }
 310
 311   /**
 312    * Retrieve the minimum size that this text area would have if its
 313    * row and column values were equal to those specified.  A text
 314    * area's minimum size depends on the number of rows and columns of
 315    * text it would prefer to display, and on the size of the font in
 316    * which the text would be displayed.
 317    *
 318    * @param rows The number of rows to use in the minimum size
 319    * calculation.
 320    * @param columns The number of columns to use in the minimum size
 321    * calculation.
 322    *
 323    * @return The minimum size for this text area.
 324    *
 325    * @deprecated This method is deprecated in favor of
 326    * <code>getMinimumSize (int, int)</code>.
 327    */
 328   public Dimension minimumSize (int rows, int columns)
 329   {
 330     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 331
 332     // Sun returns Dimension (0,0) in this case.
 333     if (peer == null)
 334       return new Dimension (0, 0);
 335
 336     return peer.getMinimumSize (rows, columns);
 337   }
 338
 339   /**
 340    * Retrieve the preferred size for this text area, considering the
 341    * text area's current row and column values.  A text area's preferred
 342    * size depends on the number of rows and columns of text it would
 343    * prefer to display, and on the size of the font in which the text
 344    * would be displayed.
 345    *
 346    * @return The preferred size for this text field.
 347    */
 348   public Dimension getPreferredSize ()
 349   {
 350     return getPreferredSize (getRows (), getColumns ());
 351   }
 352
 353   /**
 354    * Retrieve the preferred size that this text area would have if its
 355    * row and column values were equal to those specified.  A text
 356    * area's preferred size depends on the number of rows and columns
 357    * of text it would prefer to display, and on the size of the font
 358    * in which the text would be displayed.
 359    *
 360    * @param rows The number of rows to use in the preferred size
 361    * calculation.
 362    * @param columns The number of columns to use in the preferred size
 363    * calculation.
 364    *
 365    * @return The preferred size for this text area.
 366    */
 367   public Dimension getPreferredSize (int rows, int columns)
 368   {
 369     return preferredSize (rows, columns);
 370   }
 371
 372   /**
 373    * Retrieve the preferred size for this text area, considering the
 374    * text area's current row and column values.  A text area's preferred
 375    * size depends on the number of rows and columns of text it would
 376    * prefer to display, and on the size of the font in which the text
 377    * would be displayed.
 378    *
 379    * @return The preferred size for this text field.
 380    *
 381    * @deprecated This method is deprecated in favor of
 382    * <code>getPreferredSize ()</code>.
 383    */
 384   public Dimension preferredSize ()
 385   {
 386     return preferredSize (getRows (), getColumns ());
 387   }
 388
 389   /**
 390    * Retrieve the preferred size that this text area would have if its
 391    * row and column values were equal to those specified.  A text
 392    * area's preferred size depends on the number of rows and columns
 393    * of text it would prefer to display, and on the size of the font
 394    * in which the text would be displayed.
 395    *
 396    * @param rows The number of rows to use in the preferred size
 397    * calculation.
 398    * @param columns The number of columns to use in the preferred size
 399    * calculation.
 400    *
 401    * @return The preferred size for this text area.
 402    *
 403    * @deprecated This method is deprecated in favor of
 404    * <code>getPreferredSize (int, int)</code>.
 405    */
 406   public Dimension preferredSize (int rows, int columns)
 407   {
 408     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 409
 410     // Sun returns Dimension (0,0) in this case.
 411     if (peer == null)
 412       return new Dimension (0, 0);
 413
 414     return peer.getPreferredSize (rows, columns);
 415   }
 416
 417   /**
 418    * Retrieve the scroll bar display policy -- one of SCROLLBARS_BOTH,
 419    * SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY,
 420    * SCROLLBARS_NONE.
 421    *
 422    * @return The current scroll bar display policy.
 423    */
 424   public int getScrollbarVisibility ()
 425   {
 426     return scrollbarVisibility;
 427   }
 428
 429   /**
 430    * Notify this object that it should create its native peer.
 431    */
 432   public void addNotify ()
 433   {
 434     if (getPeer () != null)
 435       return;
 436
 437     setPeer ((ComponentPeer) getToolkit().createTextArea (this));
 438   }
 439
 440   /**
 441    * Append the specified text to the end of the current text.
 442    *
 443    * @param str The text to append.
 444    */
 445   public void append (String str)
 446   {
 447     appendText (str);
 448   }
 449
 450   /**
 451    * Append the specified text to the end of the current text.
 452    *
 453    * @param str The text to append.
 454    *
 455    * @deprecated This method is deprecated in favor of
 456    * <code>append ()</code>.
 457    */
 458   public void appendText (String str)
 459   {
 460     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 461     if (peer == null)
 462       return;
 463
 464     peer.insert (str, peer.getText().length ());
 465   }
 466
 467   /**
 468    * Insert the specified text at the specified position.  The first
 469    * character in the text area is at position zero.
 470    *
 471    * @param str The text to insert.
 472    * @param pos The position at which to insert text.
 473    */
 474   public void insert (String str, int pos)
 475   {
 476     insertText (str, pos);
 477   }
 478
 479   /**
 480    * Insert the specified text at the specified position.  The first
 481    * character in the text area is at position zero.
 482    *
 483    * @param str The text to insert.
 484    * @param pos The position at which to insert text.
 485    *
 486    * @deprecated This method is deprecated in favor of
 487    * <code>insert ()</code>.
 488    */
 489   public void insertText (String str, int pos)
 490   {
 491     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 492     if (peer == null)
 493       return;
 494
 495     peer.insert (str, pos);
 496   }
 497
 498   /**
 499    * Replace a range of characters with the specified text.  The
 500    * character at the start position will be replaced, unless start ==
 501    * end.  The character at the end posistion will not be replaced.
 502    * The first character in the text area is at position zero.  The
 503    * length of the replacement text may differ from the length of the
 504    * text that is replaced.
 505    *
 506    * @param str The new text for the range.
 507    * @param start The start position of the replacement range.
 508    * @param end The end position of the replacement range.
 509    */
 510   public void replaceRange (String str, int start, int end)
 511   {
 512     replaceText (str, start, end);
 513   }
 514
 515   /**
 516    * Replace a range of characters with the specified text.  The
 517    * character at the start position will be replaced, unless start ==
 518    * end.  The character at the end posistion will not be replaced.
 519    * The first character in the text area is at position zero.  The
 520    * length of the replacement text may differ from the length of the
 521    * text that is replaced.
 522    *
 523    * @param str The new text for the range.
 524    * @param start The start position of the replacement range.
 525    * @param end The end position of the replacement range.
 526    *
 527    * @deprecated This method is deprecated in favor of
 528    * <code>replaceRange ()</code>.
 529    */
 530   public void replaceText (String str, int start, int end)
 531   {
 532     TextAreaPeer peer = (TextAreaPeer) getPeer ();
 533     if (peer == null)
 534       return;
 535
 536     peer.replaceRange (str, start, end);
 537   }
 538
 539   /**
 540    * Retrieve a debugging string for this text area.
 541    *
 542    * @return A debugging string for this text area.
 543    */
 544   protected String paramString ()
 545   {
 546     String sbVisibility = "";
 547
 548     switch (scrollbarVisibility)
 549       {
 550       case SCROLLBARS_BOTH:
 551         sbVisibility = "both";
 552         break;
 553       case SCROLLBARS_VERTICAL_ONLY:
 554         sbVisibility = "vertical-only";
 555         break;
 556       case SCROLLBARS_HORIZONTAL_ONLY:
 557         sbVisibility = "horizontal-only";
 558         break;
 559       case SCROLLBARS_NONE:
 560         sbVisibility = "none";
 561         break;
 562       }
 563
 564     String editable = "";
 565     if (isEditable ())
 566       editable = "editable,";
 567
 568     return getName () + "," + getX () + "," + getY () + "," + getWidth ()
 569            + "x" + getHeight () + "," + "text=" + getText () + "," + editable
 570            + "selection=" + getSelectionStart () + "-" + getSelectionEnd ()
 571            + ",rows=" + rows + ",columns=" + columns + ",scrollbarVisibility="
 572            + sbVisibility;
 573   }
 574
 575   /**
 576    * Generate a unique name for this text area.
 577    *
 578    * @return A unique name for this text area.
 579    */
 580   String generateName ()
 581   {
 582     return "text" + getUniqueLong ();
 583   }
 584
 585   private static synchronized long getUniqueLong ()
 586   {
 587     return next_text_number++;
 588   }
 589 }