< prev index next >

src/java.desktop/share/classes/javax/swing/JTextArea.java

Print this page




  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing;
  26 
  27 import java.awt.*;
  28 import java.awt.event.*;
  29 import javax.swing.text.*;
  30 import javax.swing.plaf.*;
  31 import javax.accessibility.*;
  32 
  33 import java.util.Collections;
  34 import java.util.Set;
  35 import java.util.StringTokenizer;
  36 
  37 import java.io.ObjectOutputStream;
  38 import java.io.ObjectInputStream;
  39 import java.io.IOException;
  40 
  41 /**
  42  * A <code>JTextArea</code> is a multi-line area that displays plain text.
  43  * It is intended to be a lightweight component that provides source
  44  * compatibility with the <code>java.awt.TextArea</code> class where it can
  45  * reasonably do so.
  46  * You can find information and examples of using all the text components in
  47  * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/text.html">Using Text Components</a>,
  48  * a section in <em>The Java Tutorial.</em>
  49  *
  50  * <p>
  51  * This component has capabilities not found in the
  52  * <code>java.awt.TextArea</code> class.  The superclass should be
  53  * consulted for additional capabilities.
  54  * Alternative multi-line text classes with
  55  * more capabilities are <code>JTextPane</code> and <code>JEditorPane</code>.
  56  * <p>
  57  * The <code>java.awt.TextArea</code> internally handles scrolling.
  58  * <code>JTextArea</code> is different in that it doesn't manage scrolling,
  59  * but implements the swing <code>Scrollable</code> interface.  This allows it
  60  * to be placed inside a <code>JScrollPane</code> if scrolling
  61  * behavior is desired, and used directly if scrolling is not desired.
  62  * <p>
  63  * The <code>java.awt.TextArea</code> has the ability to do line wrapping.
  64  * This was controlled by the horizontal scrolling policy.  Since
  65  * scrolling is not done by <code>JTextArea</code> directly, backward
  66  * compatibility must be provided another way.  <code>JTextArea</code> has
  67  * a bound property for line wrapping that controls whether or
  68  * not it will wrap lines.  By default, the line wrapping property
  69  * is set to false (not wrapped).
  70  * <p>
  71  * <code>java.awt.TextArea</code> has two properties <code>rows</code>
  72  * and <code>columns</code> that are used to determine the preferred size.
  73  * <code>JTextArea</code> uses these properties to indicate the
  74  * preferred size of the viewport when placed inside a <code>JScrollPane</code>
  75  * to match the functionality provided by <code>java.awt.TextArea</code>.
  76  * <code>JTextArea</code> has a preferred size of what is needed to
  77  * display all of the text, so that it functions properly inside of
  78  * a <code>JScrollPane</code>.  If the value for <code>rows</code>
  79  * or <code>columns</code> is equal to zero,
  80  * the preferred size along that axis is used for
  81  * the viewport preferred size along the same axis.
  82  * <p>
  83  * The <code>java.awt.TextArea</code> could be monitored for changes by adding
  84  * a <code>TextListener</code> for <code>TextEvent</code>s.
  85  * In the <code>JTextComponent</code> based
  86  * components, changes are broadcasted from the model via a
  87  * <code>DocumentEvent</code> to <code>DocumentListeners</code>.
  88  * The <code>DocumentEvent</code> gives
  89  * the location of the change and the kind of change if desired.
  90  * The code fragment might look something like:
  91  * <pre>
  92  *    DocumentListener myListener = ??;
  93  *    JTextArea myArea = ??;
  94  *    myArea.getDocument().addDocumentListener(myListener);
  95  * </pre>
  96  *
  97  * <dl>
  98  * <dt><b>Newlines</b>
  99  * <dd>
 100  * For a discussion on how newlines are handled, see
 101  * <a href="text/DefaultEditorKit.html">DefaultEditorKit</a>.
 102  * </dl>
 103  *
 104  * <p>
 105  * <strong>Warning:</strong> Swing is not thread safe. For more
 106  * information see <a
 107  * href="package-summary.html#threading">Swing's Threading
 108  * Policy</a>.
 109  * <p>
 110  * <strong>Warning:</strong>
 111  * Serialized objects of this class will not be compatible with
 112  * future Swing releases. The current serialization support is
 113  * appropriate for short term storage or RMI between applications running
 114  * the same version of Swing.  As of 1.4, support for long term storage
 115  * of all JavaBeans&trade;
 116  * has been added to the <code>java.beans</code> package.
 117  * Please see {@link java.beans.XMLEncoder}.
 118  *
 119  * @beaninfo
 120  *   attribute: isContainer false
 121  * description: A multi-line area that displays plain text.
 122  *
 123  * @author  Timothy Prinzing
 124  * @see JTextPane
 125  * @see JEditorPane
 126  * @since 1.2
 127  */
 128 @SuppressWarnings("serial") // Same-version serialization only
 129 public class JTextArea extends JTextComponent {
 130 
 131     /**
 132      * @see #getUIClassID
 133      * @see #readObject
 134      */
 135     private static final String uiClassID = "TextAreaUI";
 136 


 279      * null or doesn't have a tab setting, return a default of 8.
 280      *
 281      * @return the number of characters
 282      */
 283     public int getTabSize() {
 284         int size = 8;
 285         Document doc = getDocument();
 286         if (doc != null) {
 287             Integer i = (Integer) doc.getProperty(PlainDocument.tabSizeAttribute);
 288             if (i != null) {
 289                 size = i.intValue();
 290             }
 291         }
 292         return size;
 293     }
 294 
 295     /**
 296      * Sets the line-wrapping policy of the text area.  If set
 297      * to true the lines will be wrapped if they are too long
 298      * to fit within the allocated width.  If set to false,
 299      * the lines will always be unwrapped.  A <code>PropertyChange</code>
 300      * event ("lineWrap") is fired when the policy is changed.
 301      * By default this property is false.
 302      *
 303      * @param wrap indicates if lines should be wrapped
 304      * @see #getLineWrap
 305      * @beaninfo
 306      *   preferred: true
 307      *       bound: true
 308      * description: should lines be wrapped
 309      */
 310     public void setLineWrap(boolean wrap) {
 311         boolean old = this.wrap;
 312         this.wrap = wrap;
 313         firePropertyChange("lineWrap", old, wrap);
 314     }
 315 
 316     /**
 317      * Gets the line-wrapping policy of the text area.  If set
 318      * to true the lines will be wrapped if they are too long
 319      * to fit within the allocated width.  If set to false,


 633     }
 634 
 635     /**
 636      * Sets the current font.  This removes cached row height and column
 637      * width so the new font will be reflected, and calls revalidate().
 638      *
 639      * @param f the font to use as the current font
 640      */
 641     public void setFont(Font f) {
 642         super.setFont(f);
 643         rowHeight = 0;
 644         columnWidth = 0;
 645     }
 646 
 647 
 648     /**
 649      * Returns a string representation of this JTextArea. This method
 650      * is intended to be used only for debugging purposes, and the
 651      * content and format of the returned string may vary between
 652      * implementations. The returned string may be empty but may not
 653      * be <code>null</code>.
 654      *
 655      * @return  a string representation of this JTextArea.
 656      */
 657     protected String paramString() {
 658         String wrapString = (wrap ?
 659                              "true" : "false");
 660         String wordString = (word ?
 661                              "true" : "false");
 662 
 663         return super.paramString() +
 664         ",colums=" + columns +
 665         ",columWidth=" + columnWidth +
 666         ",rows=" + rows +
 667         ",rowHeight=" + rowHeight +
 668         ",word=" + wordString +
 669         ",wrap=" + wrapString;
 670     }
 671 
 672     // --- Scrollable methods ----------------------------------------
 673 


 692      *
 693      * @return The preferredSize of a JViewport whose view is this Scrollable.
 694      * @see JViewport#getPreferredSize
 695      */
 696     public Dimension getPreferredScrollableViewportSize() {
 697         Dimension size = super.getPreferredScrollableViewportSize();
 698         size = (size == null) ? new Dimension(400,400) : size;
 699         Insets insets = getInsets();
 700 
 701         size.width = (columns == 0) ? size.width :
 702                 columns * getColumnWidth() + insets.left + insets.right;
 703         size.height = (rows == 0) ? size.height :
 704                 rows * getRowHeight() + insets.top + insets.bottom;
 705         return size;
 706     }
 707 
 708     /**
 709      * Components that display logical rows or columns should compute
 710      * the scroll increment that will completely expose one new row
 711      * or column, depending on the value of orientation.  This is implemented
 712      * to use the values returned by the <code>getRowHeight</code> and
 713      * <code>getColumnWidth</code> methods.
 714      * <p>
 715      * Scrolling containers, like JScrollPane, will use this method
 716      * each time the user requests a unit scroll.
 717      *
 718      * @param visibleRect the view area visible within the viewport
 719      * @param orientation Either SwingConstants.VERTICAL or
 720      *   SwingConstants.HORIZONTAL.
 721      * @param direction Less than zero to scroll up/left,
 722      *   greater than zero for down/right.
 723      * @return The "unit" increment for scrolling in the specified direction
 724      * @exception IllegalArgumentException for an invalid orientation
 725      * @see JScrollBar#setUnitIncrement
 726      * @see #getRowHeight
 727      * @see #getColumnWidth
 728      */
 729     public int getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction) {
 730         switch (orientation) {
 731         case SwingConstants.VERTICAL:
 732             return getRowHeight();
 733         case SwingConstants.HORIZONTAL:


 758 
 759 
 760     /**
 761      * Gets the AccessibleContext associated with this JTextArea.
 762      * For JTextAreas, the AccessibleContext takes the form of an
 763      * AccessibleJTextArea.
 764      * A new AccessibleJTextArea instance is created if necessary.
 765      *
 766      * @return an AccessibleJTextArea that serves as the
 767      *         AccessibleContext of this JTextArea
 768      */
 769     public AccessibleContext getAccessibleContext() {
 770         if (accessibleContext == null) {
 771             accessibleContext = new AccessibleJTextArea();
 772         }
 773         return accessibleContext;
 774     }
 775 
 776     /**
 777      * This class implements accessibility support for the
 778      * <code>JTextArea</code> class.  It provides an implementation of the
 779      * Java Accessibility API appropriate to text area user-interface
 780      * elements.
 781      * <p>
 782      * <strong>Warning:</strong>
 783      * Serialized objects of this class will not be compatible with
 784      * future Swing releases. The current serialization support is
 785      * appropriate for short term storage or RMI between applications running
 786      * the same version of Swing.  As of 1.4, support for long term storage
 787      * of all JavaBeans&trade;
 788      * has been added to the <code>java.beans</code> package.
 789      * Please see {@link java.beans.XMLEncoder}.
 790      */
 791     @SuppressWarnings("serial") // Same-version serialization only
 792     protected class AccessibleJTextArea extends AccessibleJTextComponent {
 793 
 794         /**
 795          * Gets the state set of this object.
 796          *
 797          * @return an instance of AccessibleStateSet describing the states
 798          * of the object
 799          * @see AccessibleStateSet
 800          */
 801         public AccessibleStateSet getAccessibleStateSet() {
 802             AccessibleStateSet states = super.getAccessibleStateSet();
 803             states.add(AccessibleState.MULTI_LINE);
 804             return states;
 805         }
 806     }
 807 
 808     // --- variables -------------------------------------------------


  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing;
  26 
  27 import java.awt.*;
  28 import java.awt.event.*;
  29 import javax.swing.text.*;
  30 import javax.swing.plaf.*;
  31 import javax.accessibility.*;
  32 
  33 import java.util.Collections;
  34 import java.util.Set;
  35 import java.util.StringTokenizer;
  36 
  37 import java.io.ObjectOutputStream;
  38 import java.io.ObjectInputStream;
  39 import java.io.IOException;
  40 
  41 /**
  42  * A {@code JTextArea} is a multi-line area that displays plain text.
  43  * It is intended to be a lightweight component that provides source
  44  * compatibility with the {@code java.awt.TextArea} class where it can
  45  * reasonably do so.
  46  * You can find information and examples of using all the text components in
  47  * <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/text.html">Using Text Components</a>,
  48  * a section in <em>The Java Tutorial.</em>
  49  *
  50  * <p>
  51  * This component has capabilities not found in the
  52  * {@code java.awt.TextArea} class.  The superclass should be
  53  * consulted for additional capabilities.
  54  * Alternative multi-line text classes with
  55  * more capabilities are {@code JTextPane} and {@code JEditorPane}.
  56  * <p>
  57  * The {@code java.awt.TextArea} internally handles scrolling.
  58  * {@code JTextArea} is different in that it doesn't manage scrolling,
  59  * but implements the swing {@code Scrollable} interface.  This allows it
  60  * to be placed inside a {@code JScrollPane} if scrolling
  61  * behavior is desired, and used directly if scrolling is not desired.
  62  * <p>
  63  * The {@code java.awt.TextArea} has the ability to do line wrapping.
  64  * This was controlled by the horizontal scrolling policy.  Since
  65  * scrolling is not done by {@code JTextArea} directly, backward
  66  * compatibility must be provided another way.  {@code JTextArea} has
  67  * a bound property for line wrapping that controls whether or
  68  * not it will wrap lines.  By default, the line wrapping property
  69  * is set to false (not wrapped).
  70  * <p>
  71  * {@code java.awt.TextArea} has two properties {@code rows}
  72  * and {@code columns} that are used to determine the preferred size.
  73  * {@code JTextArea} uses these properties to indicate the
  74  * preferred size of the viewport when placed inside a {@code JScrollPane}
  75  * to match the functionality provided by {@code java.awt.TextArea}.
  76  * {@code JTextArea} has a preferred size of what is needed to
  77  * display all of the text, so that it functions properly inside of
  78  * a {@code JScrollPane}.  If the value for {@code rows}
  79  * or {@code columns} is equal to zero,
  80  * the preferred size along that axis is used for
  81  * the viewport preferred size along the same axis.
  82  * <p>
  83  * The {@code java.awt.TextArea} could be monitored for changes by adding
  84  * a {@code TextListener} for {@code TextEvent}s.
  85  * In the {@code JTextComponent} based
  86  * components, changes are broadcasted from the model via a
  87  * {@code DocumentEvent} to {@code DocumentListeners}.
  88  * The {@code DocumentEvent} gives
  89  * the location of the change and the kind of change if desired.
  90  * The code fragment might look something like:
  91  * <pre>
  92  *    DocumentListener myListener = ??;
  93  *    JTextArea myArea = ??;
  94  *    myArea.getDocument().addDocumentListener(myListener);
  95  * </pre>
  96  *
  97  * <dl>
  98  * <dt><b>Newlines</b>
  99  * <dd>
 100  * For a discussion on how newlines are handled, see
 101  * <a href="text/DefaultEditorKit.html">DefaultEditorKit</a>.
 102  * </dl>
 103  *
 104  * <p>
 105  * <strong>Warning:</strong> Swing is not thread safe. For more
 106  * information see <a
 107  * href="package-summary.html#threading">Swing's Threading
 108  * Policy</a>.
 109  * <p>
 110  * <strong>Warning:</strong>
 111  * Serialized objects of this class will not be compatible with
 112  * future Swing releases. The current serialization support is
 113  * appropriate for short term storage or RMI between applications running
 114  * the same version of Swing.  As of 1.4, support for long term storage
 115  * of all JavaBeans&trade;
 116  * has been added to the {@code java.beans} package.
 117  * Please see {@link java.beans.XMLEncoder}.
 118  *
 119  * @beaninfo
 120  *   attribute: isContainer false
 121  * description: A multi-line area that displays plain text.
 122  *
 123  * @author  Timothy Prinzing
 124  * @see JTextPane
 125  * @see JEditorPane
 126  * @since 1.2
 127  */
 128 @SuppressWarnings("serial") // Same-version serialization only
 129 public class JTextArea extends JTextComponent {
 130 
 131     /**
 132      * @see #getUIClassID
 133      * @see #readObject
 134      */
 135     private static final String uiClassID = "TextAreaUI";
 136 


 279      * null or doesn't have a tab setting, return a default of 8.
 280      *
 281      * @return the number of characters
 282      */
 283     public int getTabSize() {
 284         int size = 8;
 285         Document doc = getDocument();
 286         if (doc != null) {
 287             Integer i = (Integer) doc.getProperty(PlainDocument.tabSizeAttribute);
 288             if (i != null) {
 289                 size = i.intValue();
 290             }
 291         }
 292         return size;
 293     }
 294 
 295     /**
 296      * Sets the line-wrapping policy of the text area.  If set
 297      * to true the lines will be wrapped if they are too long
 298      * to fit within the allocated width.  If set to false,
 299      * the lines will always be unwrapped.  A {@code PropertyChange}
 300      * event ("lineWrap") is fired when the policy is changed.
 301      * By default this property is false.
 302      *
 303      * @param wrap indicates if lines should be wrapped
 304      * @see #getLineWrap
 305      * @beaninfo
 306      *   preferred: true
 307      *       bound: true
 308      * description: should lines be wrapped
 309      */
 310     public void setLineWrap(boolean wrap) {
 311         boolean old = this.wrap;
 312         this.wrap = wrap;
 313         firePropertyChange("lineWrap", old, wrap);
 314     }
 315 
 316     /**
 317      * Gets the line-wrapping policy of the text area.  If set
 318      * to true the lines will be wrapped if they are too long
 319      * to fit within the allocated width.  If set to false,


 633     }
 634 
 635     /**
 636      * Sets the current font.  This removes cached row height and column
 637      * width so the new font will be reflected, and calls revalidate().
 638      *
 639      * @param f the font to use as the current font
 640      */
 641     public void setFont(Font f) {
 642         super.setFont(f);
 643         rowHeight = 0;
 644         columnWidth = 0;
 645     }
 646 
 647 
 648     /**
 649      * Returns a string representation of this JTextArea. This method
 650      * is intended to be used only for debugging purposes, and the
 651      * content and format of the returned string may vary between
 652      * implementations. The returned string may be empty but may not
 653      * be {@code null}.
 654      *
 655      * @return  a string representation of this JTextArea.
 656      */
 657     protected String paramString() {
 658         String wrapString = (wrap ?
 659                              "true" : "false");
 660         String wordString = (word ?
 661                              "true" : "false");
 662 
 663         return super.paramString() +
 664         ",colums=" + columns +
 665         ",columWidth=" + columnWidth +
 666         ",rows=" + rows +
 667         ",rowHeight=" + rowHeight +
 668         ",word=" + wordString +
 669         ",wrap=" + wrapString;
 670     }
 671 
 672     // --- Scrollable methods ----------------------------------------
 673 


 692      *
 693      * @return The preferredSize of a JViewport whose view is this Scrollable.
 694      * @see JViewport#getPreferredSize
 695      */
 696     public Dimension getPreferredScrollableViewportSize() {
 697         Dimension size = super.getPreferredScrollableViewportSize();
 698         size = (size == null) ? new Dimension(400,400) : size;
 699         Insets insets = getInsets();
 700 
 701         size.width = (columns == 0) ? size.width :
 702                 columns * getColumnWidth() + insets.left + insets.right;
 703         size.height = (rows == 0) ? size.height :
 704                 rows * getRowHeight() + insets.top + insets.bottom;
 705         return size;
 706     }
 707 
 708     /**
 709      * Components that display logical rows or columns should compute
 710      * the scroll increment that will completely expose one new row
 711      * or column, depending on the value of orientation.  This is implemented
 712      * to use the values returned by the {@code getRowHeight} and
 713      * {@code getColumnWidth} methods.
 714      * <p>
 715      * Scrolling containers, like JScrollPane, will use this method
 716      * each time the user requests a unit scroll.
 717      *
 718      * @param visibleRect the view area visible within the viewport
 719      * @param orientation Either SwingConstants.VERTICAL or
 720      *   SwingConstants.HORIZONTAL.
 721      * @param direction Less than zero to scroll up/left,
 722      *   greater than zero for down/right.
 723      * @return The "unit" increment for scrolling in the specified direction
 724      * @exception IllegalArgumentException for an invalid orientation
 725      * @see JScrollBar#setUnitIncrement
 726      * @see #getRowHeight
 727      * @see #getColumnWidth
 728      */
 729     public int getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction) {
 730         switch (orientation) {
 731         case SwingConstants.VERTICAL:
 732             return getRowHeight();
 733         case SwingConstants.HORIZONTAL:


 758 
 759 
 760     /**
 761      * Gets the AccessibleContext associated with this JTextArea.
 762      * For JTextAreas, the AccessibleContext takes the form of an
 763      * AccessibleJTextArea.
 764      * A new AccessibleJTextArea instance is created if necessary.
 765      *
 766      * @return an AccessibleJTextArea that serves as the
 767      *         AccessibleContext of this JTextArea
 768      */
 769     public AccessibleContext getAccessibleContext() {
 770         if (accessibleContext == null) {
 771             accessibleContext = new AccessibleJTextArea();
 772         }
 773         return accessibleContext;
 774     }
 775 
 776     /**
 777      * This class implements accessibility support for the
 778      * {@code JTextArea} class.  It provides an implementation of the
 779      * Java Accessibility API appropriate to text area user-interface
 780      * elements.
 781      * <p>
 782      * <strong>Warning:</strong>
 783      * Serialized objects of this class will not be compatible with
 784      * future Swing releases. The current serialization support is
 785      * appropriate for short term storage or RMI between applications running
 786      * the same version of Swing.  As of 1.4, support for long term storage
 787      * of all JavaBeans&trade;
 788      * has been added to the {@code java.beans} package.
 789      * Please see {@link java.beans.XMLEncoder}.
 790      */
 791     @SuppressWarnings("serial") // Same-version serialization only
 792     protected class AccessibleJTextArea extends AccessibleJTextComponent {
 793 
 794         /**
 795          * Gets the state set of this object.
 796          *
 797          * @return an instance of AccessibleStateSet describing the states
 798          * of the object
 799          * @see AccessibleStateSet
 800          */
 801         public AccessibleStateSet getAccessibleStateSet() {
 802             AccessibleStateSet states = super.getAccessibleStateSet();
 803             states.add(AccessibleState.MULTI_LINE);
 804             return states;
 805         }
 806     }
 807 
 808     // --- variables -------------------------------------------------
< prev index next >