Класс JTextArea

public class JTextArea
extends JTextComponent

Область JTextArea — это многострочная область, отображающая обычный текст. Она предназначена для использования в качестве лёгкого компонента, обеспечивающего совместимость с классом java.awt.TextArea, где это возможно. Вы найдёте информацию и примеры использования всех текстовых компонентов в Использование текстовых компонентов, разделе учебника The Java Tutorial.

Этот компонент обладает возможностями, отсутствующими в классе java.awt.TextArea. Дополнительные возможности можно найти в суперклассе. Альтернативные многострочные текстовые классы с более широкими возможностями — JTextPane и JEditorPane.

Компонент java.awt.TextArea внутренне обрабатывает прокрутку. JTextArea отличается тем, что не управляет прокруткой, но реализует интерфейс swing Scrollable. Это позволяет поместить его внутрь JScrollPane, если нужно поведение прокрутки, и использовать напрямую, если прокрутка не требуется.

java.awt.TextArea имеет возможность переносить текст на новые строки. Это контролировалось политикой горизонтальной прокрутки. Поскольку прокрутка не выполняется напрямую JTextArea, обратная совместимость должна быть обеспечена другим способом. JTextArea имеет связанное свойство для переноса текста на новые строки, которое управляет тем, будет ли происходить перенос. По умолчанию свойство переноса строк выключено (не переносится).

java.awt.TextArea имеет два свойства rows и columns, которые используются для определения предпочтительного размера. JTextArea использует эти свойства для указания предпочтительного размера области просмотра при размещении внутри JScrollPane, чтобы соответствовать функциональности, предоставленной java.awt.TextArea. JTextArea имеет предпочтительный размер, необходимый для отображения всего текста, чтобы он правильно функционировал внутри JScrollPane. Если значение для rows или columns равно нулю, предпочтительный размер по данной оси используется для предпочтительного размера области просмотра по той же оси.

За изменениями в java.awt.TextArea можно следить, добавив TextListener для TextEvent. В компонентах, основанных на JTextComponent, изменения транслируются от модели через DocumentEvent к DocumentListeners. DocumentEvent указывает местоположение изменения и тип изменения, если это необходимо. Фрагмент кода может выглядеть примерно так:

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

Новые строки

Подробное описание обработки новых строк можно найти в DefaultEditorKit.

Предупреждение: Swing не потокобезопасен. Дополнительную информацию см. в Политике потоков Swing.

Предупреждение: Сериализованные объекты этого класса не будут совместимы с будущими версиями Swing. Текущая поддержка сериализации подходит для краткосрочного хранения или RMI между приложениями, использующими одну и ту же версию Swing. Начиная с версии 1.4, поддержка долгосрочного хранения всех JavaBeans™ была добавлена в пакет java.beans. Пожалуйста, ознакомьтесь с XMLEncoder.

Конструкторы

JTextArea

public JTextArea()

Создаёт новый Текстовый_Область. Устанавливает модель по умолчанию, начальная строка равна null, а строки/столбцы установлены в 0.

JTextArea

public JTextArea(String text)

Создаёт новый Текстовый_Область с указанным отображаемым текстом. Создаётся модель по умолчанию, и строки/столбцы установлены в 0.

Параметры:

text - отображаемый текст, или null

JTextArea

public JTextArea(int rows,
                 int columns)

Создаёт новый пустой Текстовый_Область с указанным количеством строк и столбцов. Создаётся модель по умолчанию, и начальная строка равна null.

Параметры:

rows - количество строк >= 0

columns - количество столбцов >= 0

Исключения:

IllegalArgumentException - если аргументы строк или столбцов отрицательные.

JTextArea

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

Создаёт новый Текстовый_Область с указанным текстом и количеством строк и столбцов. Создаётся модель по умолчанию.

Параметры:

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.

Переопределяет:

getUIClassID в классе JComponent

Возвращает:

идентификатор ("TextAreaUI")

См. также:

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

createDefaultModel

protected Document createDefaultModel()

Создаёт реализацию модели по умолчанию, используемую при создании, если явно не задана. Возвращает новый экземпляр PlainDocument.

Возвращает:

модель документа по умолчанию

setTabSize

public void setTabSize(int size)

Устанавливает количество символов для расширения табуляции. Это будет умножено на максимальный сдвиг для шрифтов с переменной шириной. При изменении размера табуляции генерируется событие 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 - выбрасывается, если смещение меньше нуля или больше длины документа.

getLineCount

public int getLineCount()

Определяет количество строк в области.

Возвращает:

количество строк > 0

getLineStartOffset

public int getLineStartOffset(int line)
                       throws BadLocationException

Определяет смещение начала заданной строки.

Параметры:

line - номер строки для преобразования >= 0

Возвращает:

смещение >= 0

Исключения:

BadLocationException - выбрасывается, если строка меньше нуля или больше или равна количеству строк в документе (как указано в getLineCount).

getLineEndOffset

public int getLineEndOffset(int line)
                     throws BadLocationException

Определяет смещение конца заданной строки.

Параметры:

line - номер строки >= 0

Возвращает:

смещение >= 0

Исключения:

BadLocationException - выбрасывается, если строка меньше нуля или больше или равна количеству строк в документе (как указано в getLineCount).

insert

public void insert(String str,
                   int pos)

Вставляет указанный текст в указанную позицию. Не делает ничего, если модель равна null, или если текст равен null или пустой.

Параметры:

str - вставляемый текст

pos - позиция вставки >= 0

Исключения:

IllegalArgumentException - если pos - недопустимая позиция в модели

См. также:

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

append

public void append(String str)

Добавляет заданный текст в конец документа. Не делает ничего, если модель равна null, или если строка равна null или пустая.

Параметры:

str - вставляемый текст

См. также:

insert(java.lang.String, int)

replaceRange

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

Заменяет текст от указанной начальной до конечной позиции новым указанным текстом. Не делает ничего, если модель равна null. Просто удаляет, если новая строка равна null или пустая.

Параметры:

str - текст для замены

start - начальная позиция >= 0

end - конечная позиция >= начало

Исключения:

IllegalArgumentException - если часть диапазона - недопустимая позиция в модели

См. также:

insert(java.lang.String, 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 - если columns меньше 0

См. также:

getColumns()

getColumnWidth

protected int getColumnWidth()

Получает ширину столбца. Значение того, что такое столбец, может быть довольно слабым понятием для некоторых шрифтов. Этот метод используется для определения ширины столбца. По умолчанию он определяется как ширина символа m для используемого шрифта. Этот метод может быть переопределён для использования альтернативного значения.

Возвращает:

ширина столбца >= 1

getPreferredSize

public Dimension getPreferredSize()

Возвращает предпочтительный размер TextArea. Это максимум из размера, необходимого для отображения текста, и запрошенного размера для области просмотра.

Переопределяет:

getPreferredSize в классе JComponent

Возвращает:

размер

См. также:

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

setFont

public void setFont(Font f)

Устанавливает текущий шрифт. Это удаляет кэшированные высоту строки и ширину столбца, чтобы новый шрифт отразился, и вызывает revalidate().

Переопределяет:

setFont в классе JComponent

Параметры:

f - шрифт, который нужно использовать в качестве текущего

См. также:

Component.getFont()

paramString

protected String paramString()

Возвращает строковое представление этого JTextArea. Этот метод предназначен только для отладки, и содержимое и формат возвращаемой строки могут отличаться между реализациями. Возвращаемая строка может быть пустой, но не может быть null.

Переопределяет:

paramString в классе JTextComponent

Возвращает:

строковое представление этого JTextArea.

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()

Возвращает true, если область просмотра должна всегда принудительно устанавливать ширину этого Scrollable, чтобы она соответствовала ширине области просмотра. Это реализовано так, чтобы возвращать true, если политика перевода строк включена, и false, если строки не переносятся.

Определено в:

getScrollableTracksViewportWidth в интерфейсе Scrollable

Переопределяет:

getScrollableTracksViewportWidth в классе JTextComponent

Возвращает:

true, если область просмотра должна принудительно установить ширину Scrollable, чтобы она соответствовала ее собственной ширине.

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()

Возвращает предпочтительный размер области просмотра, если этот компонент вложен в JScrollPane. Используются желаемые настройки строк и столбцов, если они заданы, в противном случае используется поведение суперкласса.

Определено в:

getPreferredScrollableViewportSize в интерфейсе Scrollable

Переопределяет:

getPreferredScrollableViewportSize в классе JTextComponent

Возвращает:

Предпочтительный размер JViewport, в котором представлен этот Scrollable.

См. также:

JComponent.getPreferredSize()

getScrollableUnitIncrement

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

Определено в:

getScrollableUnitIncrement в интерфейсе Scrollable

Переопределяет:

getScrollableUnitIncrement в классе JTextComponent

Параметры:

visibleRect - область просмотра, видимая в области просмотра

orientation - Либо SwingConstants.VERTICAL, либо SwingConstants.HORIZONTAL.

direction - Меньше нуля для прокрутки вверх/влево, больше нуля для прокрутки вниз/вправо.

Возвращает:

Увеличение "единицы" для прокрутки в указанном направлении

Исключения:

IllegalArgumentException - для неверного направления

См. также:

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

getAccessibleContext

public AccessibleContext getAccessibleContext()

Получает AccessibleContext, связанный с этим JTextArea. Для JTextArea AccessibleContext принимает форму AccessibleJTextArea. Новый экземпляр AccessibleJTextArea создается при необходимости.

Определено в:

getAccessibleContext в интерфейсе Accessible

Переопределяет:

getAccessibleContext в классе JTextComponent

Возвращает:

AccessibleJTextArea, который служит AccessibleContext для этого JTextArea