Module java.desktop
Package javax.swing

Class JTextArea

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.text.JTextComponent
javax.swing.JTextArea
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
@JavaBean(defaultProperty="UIClassID", description="A multi-line area that displays plain text.") public class JTextArea extends JTextComponent
A JTextArea is a multi-line area that displays plain text. It is intended to be a lightweight component that provides source compatibility with the java.awt.TextArea class where it can reasonably do so. You can find information and examples of using all the text components in Using Text Components, a section in The Java Tutorial.

This component has capabilities not found in the java.awt.TextArea class. The superclass should be consulted for additional capabilities. Alternative multi-line text classes with more capabilities are JTextPane and JEditorPane.

The java.awt.TextArea internally handles scrolling. JTextArea is different in that it doesn't manage scrolling, but implements the swing Scrollable interface. This allows it to be placed inside a JScrollPane if scrolling behavior is desired, and used directly if scrolling is not desired.

The java.awt.TextArea has the ability to do line wrapping. This was controlled by the horizontal scrolling policy. Since scrolling is not done by JTextArea directly, backward compatibility must be provided another way. JTextArea has a bound property for line wrapping that controls whether or not it will wrap lines. By default, the line wrapping property is set to false (not wrapped).

java.awt.TextArea has two properties rows and columns that are used to determine the preferred size. JTextArea uses these properties to indicate the preferred size of the viewport when placed inside a JScrollPane to match the functionality provided by java.awt.TextArea. JTextArea has a preferred size of what is needed to display all of the text, so that it functions properly inside of a JScrollPane. If the value for rows or columns is equal to zero, the preferred size along that axis is used for the viewport preferred size along the same axis.

The java.awt.TextArea could be monitored for changes by adding a TextListener for TextEvents. In the JTextComponent based components, changes are broadcasted from the model via a DocumentEvent to DocumentListeners. The DocumentEvent gives the location of the change and the kind of change if desired. The code fragment might look something like: 

    DocumentListener myListener = ??;
    JTextArea myArea = ??;
    myArea.getDocument().addDocumentListener(myListener);
Newlines
For a discussion on how newlines are handled, see DefaultEditorKit.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans has been added to the java.beans package. Please see XMLEncoder.

Since:
1.2
See Also:

  • Constructor Details

    • JTextArea

      public JTextArea()
      Constructs a new TextArea. A default model is set, the initial string is null, and rows/columns are set to 0.

    • JTextArea

      public JTextArea(String text)
      Constructs a new TextArea with the specified text displayed. A default model is created and rows/columns are set to 0.
      Parameters:
      text - the text to be displayed, or null

    • JTextArea

      public JTextArea(int rows, int columns)
      Constructs a new empty TextArea with the specified number of rows and columns. A default model is created, and the initial string is null.
      Parameters:
      rows - the number of rows >= 0
      columns - the number of columns >= 0
      Throws:
      IllegalArgumentException - if the rows or columns arguments are negative.

    • JTextArea

      public JTextArea(String text, int rows, int columns)
      Constructs a new TextArea with the specified text and number of rows and columns. A default model is created.
      Parameters:
      text - the text to be displayed, or null
      rows - the number of rows >= 0
      columns - the number of columns >= 0
      Throws:
      IllegalArgumentException - if the rows or columns arguments are negative.

    • JTextArea

      public JTextArea(Document doc)
      Constructs a new JTextArea with the given document model, and defaults for all of the other arguments (null, 0, 0).
      Parameters:
      doc - the model to use

    • JTextArea

      public JTextArea(Document doc, String text, int rows, int columns)
      Constructs a new JTextArea with the specified number of rows and columns, and the given model. All of the constructors feed through this constructor.
      Parameters:
      doc - the model to use, or create a default one if null
      text - the text to be displayed, null if none
      rows - the number of rows >= 0
      columns - the number of columns >= 0
      Throws:
      IllegalArgumentException - if the rows or columns arguments are negative.

  • Method Details

    • getUIClassID

      @BeanProperty(bound=false) public String getUIClassID()
      Returns the class ID for the UI.
      Overrides:
      getUIClassID in class JComponent
      Returns:
      the string "TextAreaUI"
      See Also:

    • createDefaultModel

      protected Document createDefaultModel()
      Creates the default implementation of the model to be used at construction if one isn't explicitly given. A new instance of PlainDocument is returned.
      Returns:
      the default document model

    • setTabSize

      @BeanProperty(preferred=true, description="the number of characters to expand tabs to") public void setTabSize(int size)
      Sets the number of characters to expand tabs to. This will be multiplied by the maximum advance for variable width fonts. A PropertyChange event ("tabSize") is fired when the tab size changes.
      Parameters:
      size - number of characters to expand to
      See Also:

    • getTabSize

      public int getTabSize()
      Gets the number of characters used to expand tabs. If the document is null or doesn't have a tab setting, return a default of 8.
      Returns:
      the number of characters

    • setLineWrap

      @BeanProperty(preferred=true, description="should lines be wrapped") public void setLineWrap(boolean wrap)
      Sets the line-wrapping policy of the text area. If set to true the lines will be wrapped if they are too long to fit within the allocated width. If set to false, the lines will always be unwrapped. A PropertyChange event ("lineWrap") is fired when the policy is changed. By default this property is false.
      Parameters:
      wrap - indicates if lines should be wrapped
      See Also:

    • getLineWrap

      public boolean getLineWrap()
      Gets the line-wrapping policy of the text area. If set to true the lines will be wrapped if they are too long to fit within the allocated width. If set to false, the lines will always be unwrapped.
      Returns:
      if lines will be wrapped

    • setWrapStyleWord

      @BeanProperty(description="should wrapping occur at word boundaries") public void setWrapStyleWord(boolean word)
      Sets the style of wrapping used if the text area is wrapping lines. If set to true the lines will be wrapp