Класс JTextField

public class JTextField
extends JTextComponent
implements SwingConstants

JTextField — это лёгкий компонент, позволяющий редактировать строку текста. Сведения и примеры использования текстовых полей см. в Руководстве по использованию текстовых полей в Руководстве по Java.

JTextField предназначен для совместимости с java.awt.TextField, где это обоснованно. Этот компонент обладает возможностями, которых нет в классе java.awt.TextField. Для получения дополнительных возможностей следует обратиться к суперклассу.

JTextField имеет метод для задания строки, используемой в качестве команды для события действия, которое срабатывает. java.awt.TextField использовал текст поля в качестве командной строки для ActionEvent. JTextField будет использовать строку команды, установленную методом setActionCommand, если это не null, в противном случае — текст поля для совместимости с java.awt.TextField.

Методы setEchoChar и getEchoChar не предоставляются напрямую, чтобы избежать случайного раскрытия символов пароля при новой реализации внешнего вида. Для обеспечения функциональности пароля отдельный класс JPasswordField расширяет JTextField, предоставляя эту услугу с независимо настраиваемым внешним видом.

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

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

Горизонтальное выравнивание JTextField может быть установлено слева, по ширине, по центру, справа или по правому краю. Выравнивание справа/справа полезно, если требуемый размер текста поля меньше выделенного размера. Это определяется методами setHorizontalAlignment и getHorizontalAlignment. По умолчанию используется выравнивание по ширине.

То, как текстовое поле обрабатывает события VK_ENTER, зависит от наличия слушателей действий в текстовом поле. Если слушатели есть, то VK_ENTER приводит к получению слушателями события ActionEvent, и событие VK_ENTER обрабатывается. Это совместимо с тем, как текстовые поля AWT обрабатывают события VK_ENTER. Если у текстового поля нет слушателей действий, то начиная с версии 1.3 событие VK_ENTER не обрабатывается. Вместо этого обрабатываются привязки родительских компонентов, что позволяет функции кнопки по умолчанию JFC/Swing работать.

Пользовательские поля можно легко создать, расширив модель и изменив предоставленную по умолчанию модель. Например, следующий фрагмент кода создаст поле, которое будет содержать только заглавные буквы. Он будет работать даже если текст скопирован из буфера обмена или изменён программно.

 public class UpperCaseField extends JTextField {
 
     public UpperCaseField(int cols) {
         super(cols);
     }
 
     protected Document createDefaultModel() {
         return new UpperCaseDocument();
     }
 
     static class UpperCaseDocument extends PlainDocument {
 
         public void insertString(int offs, String str, AttributeSet a)
             throws BadLocationException {
 
             if (str == null) {
                 return;
             }
             char[] upper = str.toCharArray();
             for (int i = 0; i < upper.length; i++) {
                 upper[i] = Character.toUpperCase(upper[i]);
             }
             super.insertString(offs, new String(upper), a);
         }
     }
 }

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

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

Поля

notifyAction

public static final String notifyAction

Имя действия для отправки уведомления о том, что содержимое поля было принято. Обычно привязано к нажатию клавиши ВВОД.

См. также:

Значения константных полей

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

JTextField

public JTextField()

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

JTextField

public JTextField(String text)

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

Параметры:

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

JTextField

public JTextField(int columns)

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

Параметры:

columns - количество столбцов для расчёта предпочтительной ширины; если columns равно нулю, предпочтительная ширина будет определяться реализацией компонента

JTextField

public JTextField(String text,
                  int columns)

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

Параметры:

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

columns - количество столбцов для расчёта предпочтительной ширины; если columns равно нулю, предпочтительная ширина будет определяться реализацией компонента

JTextField

public JTextField(Document doc,
                  String text,
                  int columns)

Создаёт новый JTextField, который использует указанную модель хранения текста и заданное количество столбцов. Этот конструктор используется для вызова других конструкторов. Если документ null, создаётся модель по умолчанию.

Параметры:

doc - модель хранения текста; если она null, будет предоставлена модель по умолчанию с помощью вызова метода createDefaultModel

text - начальная отображаемая строка или null

columns - количество столбцов для расчёта предпочтительной ширины >= 0; если columns равно нулю, предпочтительная ширина будет определяться реализацией компонента

Исключения:

IllegalArgumentException - если columns < 0

Методы

getUIClassID

public String getUIClassID()

Получает идентификатор класса для UI.

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

getUIClassID в классе JComponent

Возвращает:

строку "TextFieldUI"

См. также:

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

setDocument

public void setDocument(Document doc)

Связывает редактор с документом. Текущий зарегистрированный фабричный метод используется для построения представления документа, которое отображается редактором после перевалидации. Событие PropertyChange ("document") распространяется на каждый слушатель.

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

setDocument в классе JTextComponent

Параметры:

doc - документ для отображения/редактирования

См. также:

JTextComponent.getDocument()

isValidateRoot

public boolean isValidateRoot()

Вызовы revalidate изнутри текстового поля будут обработаны с валидацией поля, если текстовое поле не содержится в JViewport, в этом случае возвращает false.

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

isValidateRoot в классе JComponent

Возвращает:

если родителем этого текстового поля является JViewPort, возвращает false, иначе — true

См. также:

JComponent.revalidate(), JComponent.isValidateRoot(), Container.isValidateRoot()

getHorizontalAlignment

public int getHorizontalAlignment()

Возвращает горизонтальное выравнивание текста. Допустимые значения:

• JTextField.LEFT
• JTextField.CENTER
• JTextField.RIGHT
• JTextField.LEADING
• JTextField.TRAILING

Возвращает:

горизонтальное выравнивание

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)

Устанавливает горизонтальное выравнивание текста. Допустимые значения:

• JTextField.LEFT
• JTextField.CENTER
• JTextField.RIGHT
• JTextField.LEADING
• JTextField.TRAILING

invalidate и repaint вызываются при установке выравнивания, а также генерируется событие PropertyChange ("horizontalAlignment").

Параметры:

alignment - выравнивание

Исключения:

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

createDefaultModel

protected Document createDefaultModel()

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

Возвращает:

реализацию модели по умолчанию

getColumns

public int getColumns()

Возвращает количество столбцов в этом TextField.

Возвращает:

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

setColumns

public void setColumns(int columns)

Устанавливает количество столбцов в этом TextField, а затем перевалидирует макет.

Параметры:

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

Исключения:

IllegalArgumentException - если columns меньше 0

getColumnWidth

protected int getColumnWidth()

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

Возвращает:

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

getPreferredSize

public Dimension getPreferredSize()

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

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

getPreferredSize в классе JComponent

Возвращает:

размер этого текстового поля

См. также:

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

setFont

public void setFont(Font f)

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

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

setFont в классе JComponent

Параметры:

f - новый шрифт

См. также:

Component.getFont()

addActionListener

public void addActionListener(ActionListener l)

Добавляет указанного обработчика событий действия для получения событий действия от этого текстового поля.

Параметры:

l - добавляемый обработчик событий действия

removeActionListener

public void removeActionListener(ActionListener l)

Удаляет указанного обработчика событий действия, чтобы он больше не получал события действия от этого текстового поля.

Параметры:

l - удаляемый обработчик событий действия

getActionListeners

public ActionListener[] getActionListeners()

Возвращает массив всех ActionListener добавленных в этот JTextField с помощью addActionListener().

Возвращает:

все добавленные ActionListener или пустой массив, если нет добавленных слушателей

С тех пор:

1.4

fireActionPerformed

protected void fireActionPerformed()

Уведомляет всех слушателей, которые зарегистрировали интерес к уведомлению об этом типе события. Экземпляр события создаётся лениво. Список слушателей обрабатывается в порядке от последнего к первому.

См. также:

EventListenerList

setActionCommand

public void setActionCommand(String command)

Устанавливает строку команды, используемую для событий действия.

Параметры:

command - строка команды

setAction

public void setAction(Action a)

Параметры:

a - Action для JTextField, или null

С момента:

1.3

См. также:

Action, getAction(), configurePropertiesFromAction(javax.swing.Action), createActionPropertyChangeListener(javax.swing.Action), actionPropertyChanged(javax.swing.Action, java.lang.String)

getAction

public Action getAction()

Возвращает текуще установленное Action для этого ActionEvent источника, или null, если Action не установлено.

Возвращает:

Action для этого ActionEvent источника, или null

С момента:

1.3

См. также:

Action, setAction(javax.swing.Action)

configurePropertiesFromAction

protected void configurePropertiesFromAction(Action a)

Устанавливает свойства в этом текстовом поле, чтобы соответствовать свойствам указанного Action. Дополнительные сведения о настраиваемых свойствах см. в разделе Компоненты Swing, поддерживающие Action.

Параметры:

a - Action для получения свойств, или null

С момента:

1.3

См. также:

Action, setAction(javax.swing.Action)

actionPropertyChanged

protected void actionPropertyChanged(Action action,
                                     String propertyName)

Параметры:

action - Action , связанное с этим текстовым полем

propertyName - имя изменённого свойства

С момента:

1.6

См. также:

Action, configurePropertiesFromAction(javax.swing.Action)

createActionPropertyChangeListener

protected PropertyChangeListener createActionPropertyChangeListener(Action a)

Параметры:

a - действие текстового поля

С момента:

1.3

См. также:

Action, setAction(javax.swing.Action)

getActions

public Action[] getActions()

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

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

getActions в классе JTextComponent

Возвращает:

список команд

postActionEvent

public void postActionEvent()

Обрабатывает события действий, происходящие в этом текстовом поле, рассылает их любым зарегистрированным ActionListener объектам. Обычно это вызывается контроллером, зарегистрированным с текстовым полем.

getHorizontalVisibility

public BoundedRangeModel getHorizontalVisibility()

Возвращает:

видимость

См. также:

BoundedRangeModel

getScrollOffset

public int getScrollOffset()

Получает смещение прокрутки в пикселях.

Возвращает:

смещение >= 0

setScrollOffset

public void setScrollOffset(int scrollOffset)

Устанавливает смещение прокрутки в пикселях.

Параметры:

scrollOffset - смещение >= 0

scrollRectToVisible

public void scrollRectToVisible(Rectangle r)

Прокручивает поле влево или вправо.

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

scrollRectToVisible в классе JComponent

Параметры:

r - область для прокрутки

См. также:

JViewport

paramString

protected String paramString()

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

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

paramString в классе JTextComponent

Возвращает:

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

getAccessibleContext

public AccessibleContext getAccessibleContext()

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

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

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

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

getAccessibleContext в классе JTextComponent

Возвращает:

AccessibleJTextField , который служит AccessibleContext этого JTextField