javax.swing
类 JTextArea

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.text.JTextComponent
                  javax.swing.JTextArea

所有已实现的接口：

ImageObserver, MenuContainer, Serializable, Accessible, Scrollable

public class JTextArea
extends JTextComponent

JTextArea 是一个显示纯文本的多行区域。它作为一个轻量级组件，提供与 java.awt.TextArea 类的源兼容性，理应如此。有关使用所有文本组件的信息和示例，请参阅 The Java Tutorial 中 Using Text Components 一节。

此组件具有 java.awt.TextArea 类中没有的功能。有关其他功能，请参考超类。还有 JTextPane 和 JEditorPane 也是具有更多功能的多行文本类。

java.awt.TextArea 在内部处理滚动。JTextArea 的不同之处在于，它不管理滚动，但实现了 swing Scrollable 接口。这允许把它放置在 JScrollPane 的内部（如果需要滚动行为），或者直接使用（如果不需要滚动）。

java.awt.TextArea 具有换行能力。这由水平滚动策略来控制。由于滚动不是由 JTextArea 直接完成的，因此必须通过另一种方式来提供向后兼容性。JTextArea 具有用于换行的绑定 (bound) 属性，该属性控制其是否换行。在默认情况下，换行属性设置为 false（不换行）。

java.awt.TextArea 具有两个属性 rows 和 columns，这两个属性用来确定首选大小。JTextArea 用这些属性来指示 viewport 的首选大小，此 viewport 被放置到 JScrollPane 中以匹配由 java.awt.TextArea 提供的功能。JTextArea 具有显示所有文本所需的首选大小，以便在 JScrollPane 内部正常工作。如果 rows 或 columns 的值等于 0，则沿该轴的首选大小将用于沿相同轴上 viewport 的首选大小。

可以通过添加一个 TextEvent 的 TextListener 来对 java.awt.TextArea 的更改进行监视。在基于 JTextComponent 的组件中，更改通过 DocumentEvent 从模型传播到 DocumentListeners。DocumentEvent 给出了更改的位置和更改种类（如果需要）。代码片段如下所示：

    DocumentListener myListener = ??;
    JTextArea myArea = ??;
    myArea.getDocument().addDocumentListener(myListener);
 

换行

有关如何处理换行的讨论，请参阅 DefaultEditorKit。

警告：Swing 不是线程安全的。有关更多信息，请参阅　Swing's Threading Policy。

警告：此类的已序列化对象与以后的 Swing 版本不兼容。当前序列化支持适用于短期存储，或适用于在运行相同 Swing 版本的应用程序之间进行 RMI（Remote Method Invocation，远程方法调用）。从 1.4 版本开始，已在 java.beans 包中添加了支持所有 JavaBeans^TM 长期存储的功能。请参见 XMLEncoder。

另请参见：

JTextPane, JEditorPane

JTextArea

public JTextArea()

构造新的 TextArea。设置默认的模型，初始字符串为 null，行/列设置为 0。

JTextArea

public JTextArea(String text)

构造显示指定文本的新的 TextArea。创建默认模型，行/列设置为 0。

参数：

text - 要显示的文本，或者为 null

JTextArea

public JTextArea(int rows,
                 int columns)

构造具有指定行数和列数的新的空 TextArea。创建默认模型，初始字符串为 null。

参数：

rows - 行数 >= 0

columns - 列数 >= 0

抛出：

IllegalArgumentException - 如果行或列参数为负数。

JTextArea

public JTextArea(String text,
                 int rows,
                 int columns)

构造具有指定文本、行数和列数的新的 TextArea。创建默认模型。

参数：

text - 要显示的文本，或者为 null

rows - 行数 >= 0

columns - 列数 >= 0

抛出：

IllegalArgumentException - 如果行或列参数为负数。

JTextArea

public JTextArea(Document doc)

构造新的 JTextArea，使其具有给定的文档模型，所有其他参数均默认为 (null, 0, 0)。

参数：

doc - 要使用的模型

JTextArea

public JTextArea(Document doc,
                 String text,
                 int rows,
                 int columns)

构造具有指定行数和列数以及给定模型的新的 JTextArea。所有构造方法均调用此构造方法。

参数：

doc - 要使用的模型，如果为 null，则创建一个默认的模型

text - 要显示的文本，如果没有文本，则为 null

rows - 行数 >= 0

columns - 列数 >= 0

抛出：

IllegalArgumentException - 如果行或列参数为负数。

getUIClassID

public String getUIClassID()

返回 UI 的类 ID。

覆盖：

类 JComponent 中的 getUIClassID

返回：

ID ("TextAreaUI")

另请参见：

JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

createDefaultModel

protected Document createDefaultModel()

如果没有显式给出构造时要使用的模型，则创建该模型的默认实现。返回 PlainDocument 的一个新的实例。

返回：

默认的文档模型

setTabSize

public void setTabSize(int size)

设置选项卡要扩大到的字符数。此数将与可变宽度字体的最大 advance 相乘。当选项卡大小变化时将激发 PropertyChange 事件（"tabSize"）。

参数：

size - 要扩大到的字符数

另请参见：

getTabSize()

getTabSize

public int getTabSize()

获取用于扩展选项卡的字符数。如果文档为 null 或者没有选项卡设置，则返回默认值 8。

返回：

字符数

setLineWrap

public void setLineWrap(boolean wrap)

设置文本区的换行策略。如果设置为 true，则当行的长度大于所分配的宽度时，将换行。如果设置为 false，则始终不换行。当策略更改时，将激发 PropertyChange 事件（"lineWrap"）。此属性默认为 false。

参数：

wrap - 指示是否应该换行

另请参见：

getLineWrap()

getLineWrap

public boolean getLineWrap()

获取文本区的换行策略。如果设置为 true，则当行的长度大于所分配的宽度时，将换行。如果设置为 false，则始终不换行。

返回：

是否换行

setWrapStyleWord

public void setWrapStyleWord(boolean word)

设置换行方式（如果文本区要换行）。如果设置为 true，则当行的长度大于所分配的宽度时，将在单词边界（空白）处换行。如果设置为 false，则将在字符边界处换行。此属性默认为 false。

参数：

word - 指示是否应该使用单词边界来换行

另请参见：

getWrapStyleWord()

getWrapStyleWord

public boolean getWrapStyleWord()

获取换行方式（如果文本区要换行）。如果设置为 true，则当行的长度大于所分配的宽度时，将在单词边界（即空白）处换行。如果设置为 false，则将在字符边界处换行。

返回：

换行方式是否应该为单词边界，而不是字符边界

另请参见：

setWrapStyleWord(boolean)

getLineOfOffset

public int getLineOfOffset(int offset)
                    throws BadLocationException

将组件文本中的偏移量转换为行号。

参数：

offset - 偏移量 >= 0

返回：

行号 >= 0

抛出：

BadLocationException - 如果偏移量小于 0 或大于文档长度。

getLineCount

public int getLineCount()

确定文本区中所包含的行数。

返回：

行数 > 0

getLineStartOffset

public int getLineStartOffset(int line)
                       throws BadLocationException

确定给定行起始处的偏移量。

参数：

line - 要转换的行号 >= 0

返回：

偏移量 >= 0

抛出：

BadLocationException - 如果 line 小于 0 或大于等于文档中所包含的行数（由 getLineCount 进行报告）。

getLineEndOffset

public int getLineEndOffset(int line)
                     throws BadLocationException

确定给定行结尾处的偏移量。

参数：

line - 行 >= 0

返回：

偏移量 >= 0

抛出：

BadLocationException - 如果 line 小于 0 或大于等于文档所包含的行数（由 getLineCount 报告）。

insert

public void insert(String str,
                   int pos)

将指定文本插入指定位置。如果模型为 null 或者文本为 null 或空，则不执行任何操作。

虽然大多数 Swing 方法不是线程安全的，但此方法是线程安全的。有关更多信息，请参阅 How to Use Threads。

参数：

str - 要插入的文本

pos - 插入的位置 >= 0

抛出：

IllegalArgumentException - 如果 pos 在模型中是一个无效的位置

另请参见：

replaceRange(java.lang.String, int, int)

append

public void append(String str)

将给定文本追加到文档结尾。如果模型为 null 或者字符串为 null 或空，则不执行任何操作。

虽然大多数 Swing 方法不是线程安全的，但此方法是线程安全的。有关更多信息，请参阅 How to Use Threads。

参数：

str - 要插入的文本

另请参见：

insert(java.lang.String, int)

replaceRange

public void replaceRange(String str,
                         int start,
                         int end)

用给定的新文本替换从指示的起始位置到结尾位置的文本。如果模型为 null，则不执行任何操作。如果新字符串为 null 或为空，则只执行简单的删除操作。

虽然大多数 Swing 方法不是线程安全的，但此方法是线程安全的。有关更多信息，请参阅 How to Use Threads。

参数：

str - 要用来替换的文本

start - 起始位置 >= 0

end - 结尾位置 >= start

抛出：

IllegalArgumentException - 如果模型中的部分范围是无效的位置

另请参见：

insert(java.lang.String, int), replaceRange(java.lang.String, int, int)

getRows

public int getRows()

返回 TextArea 中的行数。

返回：

行数 > 0

setRows

public void setRows(int rows)

设置此 TextArea 的行数。设置新值之后调用 invalidate()。

参数：

rows - 行数 >= 0

抛出：

IllegalArgumentException - 如果 rows 小于 0

另请参见：

getRows()

getRowHeight

protected int getRowHeight()

定义行高的意义。默认为字体的高度。

返回：

高度 >= 1

getColumns

public int getColumns()

返回 TextArea 中的列数。

返回：

列数 >= 0

setColumns

public void setColumns(int columns)

设置此 TextArea 中的列数。设置新值之后执行 invalidate()。

参数：

columns - 列数 >= 0

抛出：

IllegalArgumentException - 如果列小于 0

另请参见：

getColumns()

getColumnWidth

protected int getColumnWidth()

获取列的宽度。对某些字体而言列的概念不是很有意义。此方法用来定义列的宽度。对于所使用的字体，默认情况下这将被定义为字符 m 的宽度。此方法可以被重新定义为一些其他替代量。

返回：

列的宽度 >= 1

getPreferredSize

public Dimension getPreferredSize()

返回 TextArea 的首选大小。这是显示文本所需的大小和 viewport 所要求大小的最大值。

覆盖：

类 JComponent 中的 getPreferredSize

返回：

大小

另请参见：

JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

setFont

public void setFont(Font f)

设置当前字体。这将移除缓存的行高和列宽，以便新的字体能够反映出来，并且调用 revalidate()。

覆盖：

类 JComponent 中的 setFont

参数：

f - 要使用的当前字体

另请参见：

Component.getFont()

paramString

protected String paramString()

返回此 JTextArea 的字符串表示形式。此方法仅在进行调试的时候使用，对于各个实现，所返回字符串的内容和格式可能有所不同。返回的字符串可能为空，但不可能为 null。

覆盖：

类 JTextComponent 中的 paramString

返回：

此 JTextArea 的字符串表示形式。

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()

如果 viewport 总是强制要求此 Scrollable 的宽度与 viewport 的宽度相匹配，则返回 true。如果换行策略为 true，则此实现返回 true，如果不换行，则返回 false。

指定者：

接口 Scrollable 中的 getScrollableTracksViewportWidth

覆盖：

类 JTextComponent 中的 getScrollableTracksViewportWidth

返回：

如果 viewport 应强制要求 Scrollables 宽度与其自己的宽度相匹配，则返回 true。

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()

如果此组件被嵌入 JScrollPane 中，则返回 viewport 的首选大小。这将使用预期的列和行设置（如果已经设置），否则使用超类行为。

指定者：

接口 Scrollable 中的 getPreferredScrollableViewportSize

覆盖：

类 JTextComponent 中的 getPreferredScrollableViewportSize

返回：

JViewport 的 preferredSize，其中 JViewport 的视图为此 Scrollable。

另请参见：

JComponent.getPreferredSize()

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)

显示逻辑行或列的组件应根据方向的值计算滚动增量，此滚动增量将完全显示一个新行或新列。此实现使用 getRowHeight 和 getColumnWidth 方法返回的值。

用户每次请求一个单元滚动时，滚动容器（例如 JScrollPane）都将使用此方法。

指定者：

接口 Scrollable 中的 getScrollableUnitIncrement

覆盖：

类 JTextComponent 中的 getScrollableUnitIncrement

参数：

visibleRect - viewport 中可见的视图区域

orientation - 或者是 SwingConstants.VERTICAL 或者是 SwingConstants.HORIZONTAL.

direction - 小于 0 时为向左/上滚动，大于 0 时为向右/下滚动。

返回：

在指定方向滚动的 "单位" 增量

抛出：

IllegalArgumentException - 如果方向无效

另请参见：

JScrollBar.setUnitIncrement(int), getRowHeight(), getColumnWidth()

getAccessibleContext

public AccessibleContext getAccessibleContext()

获取与此 JTextArea 关联的 AccessibleContext。对于 JTextAreas，AccessibleContext 采取 AccessibleJTextArea 的形式。必要时创建新的 AccessibleJTextArea 实例。

指定者：

接口 Accessible 中的 getAccessibleContext

覆盖：

类 JTextComponent 中的 getAccessibleContext

返回：

一个 AccessibleJTextArea，它充当此 JTextArea 的 AccessibleContext

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。