libjava/javax/swing/JTextArea.java

   1 /* JTextArea.java --
   2    Copyright (C) 2004, 2005  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
  39 package javax.swing;
  40
  41 import java.awt.FontMetrics;
  42
  43 import javax.swing.text.BadLocationException;
  44 import javax.swing.text.Document;
  45 import javax.swing.text.Element;
  46 import javax.swing.text.JTextComponent;
  47 import javax.swing.text.PlainDocument;
  48
  49 /**
  50  * The <code>JTextArea</code> component provides a multi-line area for displaying
  51  * and editing plain text.  The component is designed to act as a lightweight
  52  * replacement for the heavyweight <code>java.awt.TextArea</code> component,
  53  * which provides similar functionality using native widgets.
  54  * <p>
  55  *
  56  * This component has additional functionality to the AWT class.  It follows
  57  * the same design pattern as seen in other text components, such as
  58  * <code>JTextField</code>, <code>JTextPane</code> and <code>JEditorPane</code>,
  59  * and embodied in <code>JTextComponent</code>.  These classes separate the text
  60  * (the model) from its appearance within the onscreen component (the view).  The
  61  * text is held within a <code>javax.swing.text.Document</code> object, which can
  62  * also maintain relevant style information where necessary.  As a result, it is the
  63  * document that should be monitored for textual changes, via
  64  * <code>DocumentEvent</code>s delivered to registered
  65  * <code>DocumentListener</code>s, rather than this component.
  66  * <p>
  67  *
  68  * Unlike <code>java.awt.TextArea</code>, <code>JTextArea</code> does not
  69  * handle scrolling.  Instead, this functionality is delegated to a
  70  * <code>JScrollPane</code>, which can contain the text area and handle
  71  * scrolling when required.  Likewise, the word wrapping functionality
  72  * of the AWT component is converted to a property of this component
  73  * and the <code>rows</code> and <code>columns</code> properties
  74  * are used in calculating the preferred size of the scroll pane's
  75  * view port.
  76  *
  77  * @author Michael Koch  (konqueror@gmx.de)
  78  * @author Andrew John Hughes  (gnu_andrew@member.fsf.org)
  79  * @see java.awt.TextArea
  80  * @see javax.swing.JTextComponent
  81  * @see javax.swing.JTextField
  82  * @see javax.swing.JTextPane
  83  * @see javax.swing.JEditorPane
  84  * @see javax.swing.text.Document
  85  * @see javax.swing.text.DocumentEvent
  86  * @see javax.swing.text.DocumentListener
  87  */
  88
  89 public class JTextArea extends JTextComponent
  90 {
  91   /**
  92    * Compatible with Sun's JDK
  93    */
  94   private static final long serialVersionUID = -6141680179310439825L;
  95
  96   /**
  97    * The number of rows used by the component.
  98    */
  99   private int rows;
 100
 101   /**
 102    * The number of columns used by the component.
 103    */
 104   private int columns;
 105
 106   /**
 107    * Whether line wrapping is enabled or not.
 108    */
 109   private boolean lineWrap;
 110
 111   /**
 112    * The number of characters equal to a tab within the text.
 113    */
 114   private int tabSize = 8;
 115
 116   private boolean wrapStyleWord;
 117
 118   /**
 119    * Creates a new <code>JTextArea</code> object.
 120    */
 121   public JTextArea()
 122   {
 123     this(null, null, 0, 0);
 124   }
 125
 126   /**
 127    * Creates a new <code>JTextArea</code> object.
 128    *
 129    * @param text the initial text
 130    */
 131   public JTextArea(String text)
 132   {
 133     this(null, text, 0, 0);
 134   }
 135
 136   /**
 137    * Creates a new <code>JTextArea</code> object.
 138    *
 139    * @param rows the number of rows
 140    * @param columns the number of cols
 141    *
 142    * @exception IllegalArgumentException if rows or columns are negative
 143    */
 144   public JTextArea(int rows, int columns)
 145   {
 146     this(null, null, rows, columns);
 147   }
 148
 149   /**
 150    * Creates a new <code>JTextArea</code> object.
 151    *
 152    * @param text the initial text
 153    * @param rows the number of rows
 154    * @param columns the number of cols
 155    *
 156    * @exception IllegalArgumentException if rows or columns are negative
 157    */
 158   public JTextArea(String text, int rows, int columns)
 159   {
 160     this(null, text, rows, columns);
 161   }
 162
 163   /**
 164    * Creates a new <code>JTextArea</code> object.
 165    *
 166    * @param the document model to use
 167    */
 168   public JTextArea(Document doc)
 169   {
 170     this(doc, null, 0, 0);
 171   }
 172
 173   /**
 174    * Creates a new <code>JTextArea</code> object.
 175    *
 176    * @param the document model to use
 177    * @param text the initial text
 178    * @param rows the number of rows
 179    * @param columns the number of cols
 180    *
 181    * @exception IllegalArgumentException if rows or columns are negative
 182    */
 183   public JTextArea(Document doc, String text, int rows, int columns)
 184   {
 185     setDocument(doc == null ? createDefaultModel() : doc);
 186     setText(text);
 187     setRows(rows);
 188     setColumns(columns);
 189   }
 190
 191   /**
 192    * Appends the supplied text to the current contents
 193    * of the document model.
 194    *
 195    * @param toAppend the text to append
 196    */
 197   public void append(String toAppend)
 198   {
 199       try
 200           {
 201               getDocument().insertString(getText().length(), toAppend, null);
 202           }
 203       catch (BadLocationException exception)
 204           {
 205               /* This shouldn't happen in theory -- but, if it does...  */
 206               throw new RuntimeException("Unexpected exception occurred.", exception);
 207           }
 208   }
 209
 210   /**
 211    * Creates the default document model.
 212    *
 213    * @return a new default model
 214    */
 215   protected Document createDefaultModel()
 216   {
 217     return new PlainDocument();
 218   }
 219
 220   /**
 221    * Returns true if the width of this component should be forced
 222    * to match the width of a surrounding view port.  When line wrapping
 223    * is turned on, this method returns true.
 224    *
 225    * @return true if lines are wrapped.
 226    */
 227   public boolean getScrollableTracksViewportWidth()
 228   {
 229     return lineWrap ? true : super.getScrollableTracksViewportWidth();
 230   }
 231
 232   /**
 233    * Returns the UI class ID string.
 234    *
 235    * @return the string "TextAreaUI"
 236    */
 237   public String getUIClassID()
 238   {
 239     return "TextAreaUI";
 240   }
 241
 242   /**
 243    * Returns the current number of columns.
 244    *
 245    * @return number of columns
 246    */
 247   public int getColumns()
 248   {
 249     return columns;
 250   }
 251
 252   /**
 253    * Sets the number of rows.
 254    *
 255    * @param columns number of columns
 256    *
 257    * @exception IllegalArgumentException if columns is negative
 258    */
 259   public void setColumns(int columns)
 260   {
 261     if (columns < 0)
 262       throw new IllegalArgumentException();
 263
 264     this.columns = columns;
 265   }
 266
 267   /**
 268    * Returns the current number of rows.
 269    *
 270    * @return number of rows
 271    */
 272   public int getRows()
 273   {
 274     return rows;
 275   }
 276
 277   /**
 278    * Sets the number of rows.
 279    *
 280    * @param columns number of columns
 281    *
 282    * @exception IllegalArgumentException if rows is negative
 283    */
 284   public void setRows(int rows)
 285   {
 286     if (rows < 0)
 287       throw new IllegalArgumentException();
 288
 289     this.rows = rows;
 290   }
 291
 292   /**
 293    * Checks whether line wrapping is enabled.
 294    *
 295    * @return <code>true</code> if line wrapping is enabled,
 296    * <code>false</code> otherwise
 297    */
 298   public boolean getLineWrap()
 299   {
 300     return lineWrap;
 301   }
 302
 303   /**
 304    * Enables/disables line wrapping.
 305    *
 306    * @param wrapping <code>true</code> to enable line wrapping,
 307    * <code>false</code> otherwise
 308    */
 309   public void setLineWrap(boolean flag)
 310   {
 311     if (lineWrap == flag)
 312       return;
 313
 314     boolean oldValue = lineWrap;
 315     lineWrap = flag;
 316     firePropertyChange("lineWrap", oldValue, lineWrap);
 317   }
 318
 319   /**
 320    * Checks whether word style wrapping is enabled.
 321    *
 322    * @return <code>true</code> if word style wrapping is enabled,
 323    * <code>false</code> otherwise
 324    */
 325   public boolean getWrapStyleWord()
 326   {
 327     return wrapStyleWord;
 328   }
 329
 330   /**
 331    * Enables/Disables word style wrapping.
 332    *
 333    * @param flag <code>true</code> to enable word style wrapping,
 334    * <code>false</code> otherwise
 335    */
 336   public void setWrapStyleWord(boolean flag)
 337   {
 338     if (wrapStyleWord == flag)
 339       return;
 340
 341     boolean oldValue = wrapStyleWord;
 342     wrapStyleWord = flag;
 343     firePropertyChange("wrapStyleWord", oldValue, wrapStyleWord);
 344   }
 345
 346   /**
 347    * Returns the number of characters used for a tab.
 348    * This defaults to 8.
 349    *
 350    * @return the current number of spaces used for a tab.
 351    */
 352   public int getTabSize()
 353   {
 354     return tabSize;
 355   }
 356
 357   /**
 358    * Sets the number of characters used for a tab to the
 359    * supplied value.  If a change to the tab size property
 360    * occurs (i.e. newSize != tabSize), a property change event
 361    * is fired.
 362    *
 363    * @param newSize The new number of characters to use for a tab.
 364    */
 365   public void setTabSize(int newSize)
 366   {
 367     if (tabSize == newSize)
 368       return;
 369
 370     int oldValue = tabSize;
 371     tabSize = newSize;
 372     firePropertyChange("tabSize", oldValue, tabSize);
 373   }
 374
 375   protected int getColumnWidth()
 376   {
 377     FontMetrics metrics = getToolkit().getFontMetrics(getFont());
 378     return metrics.charWidth('m');
 379   }
 380
 381   public int getLineCount()
 382   {
 383     return getDocument().getDefaultRootElement().getElementCount();
 384   }
 385
 386   public int getLineStartOffset(int line)
 387      throws BadLocationException
 388   {
 389     int lineCount = getLineCount();
 390
 391     if (line < 0 || line > lineCount)
 392       throw new BadLocationException("Non-existing line number", line);
 393
 394     Element lineElem = getDocument().getDefaultRootElement().getElement(line);
 395     return lineElem.getStartOffset();
 396   }
 397
 398   public int getLineEndOffset(int line)
 399      throws BadLocationException
 400   {
 401     int lineCount = getLineCount();
 402
 403     if (line < 0 || line > lineCount)
 404       throw new BadLocationException("Non-existing line number", line);
 405
 406     Element lineElem = getDocument().getDefaultRootElement().getElement(line);
 407     return lineElem.getEndOffset();
 408   }
 409
 410   public int getLineOfOffset(int offset)
 411     throws BadLocationException
 412   {
 413     Document doc = getDocument();
 414
 415     if (offset < doc.getStartPosition().getOffset()
 416         || offset >= doc.getEndPosition().getOffset())
 417       throw new BadLocationException("offset outside of document", offset);
 418
 419     return doc.getDefaultRootElement().getElementIndex(offset);
 420   }
 421
 422   protected int getRowHeight()
 423   {
 424     FontMetrics metrics = getToolkit().getFontMetrics(getFont());
 425     return metrics.getHeight();
 426   }
 427
 428   /**
 429    * Inserts the supplied text at the specified position.  Nothing
 430    * happens in the case that the model or the supplied string is null
 431    * or of zero length.
 432    *
 433    * @param string The string of text to insert.
 434    * @param position The position at which to insert the supplied text.
 435    * @throws IllegalArgumentException if the position is &lt; 0 or greater
 436    * than the length of the current text.
 437    */
 438   public void insert(String string, int position)
 439   {
 440     // Retrieve the document model.
 441     Document doc = getDocument();
 442
 443     // Check the model and string for validity.
 444     if (doc == null
 445         || string == null
 446         || string.length() == 0)
 447       return;
 448
 449     // Insert the text into the model.
 450     try
 451       {
 452         doc.insertString(position, string, null);
 453       }
 454     catch (BadLocationException e)
 455       {
 456         throw new IllegalArgumentException("The supplied position, "
 457                                            + position + ", was invalid.");
 458       }
 459   }
 460
 461   public void replaceRange(String text, int start, int end)
 462   {
 463     Document doc = getDocument();
 464
 465     if (start > end
 466         || start < doc.getStartPosition().getOffset()
 467         || end >= doc.getEndPosition().getOffset())
 468       throw new IllegalArgumentException();
 469
 470     try
 471       {
 472         doc.remove(start, end);
 473         doc.insertString(start, text, null);
 474       }
 475     catch (BadLocationException e)
 476       {
 477         // This cannot happen as we check offset above.
 478       }
 479   }
 480 }