Класс JFormattedTextField

public class JFormattedTextField
extends JTextField

JFormattedTextField расширяет JTextField, добавляя поддержку форматирования произвольных значений, а также извлечения конкретного объекта после редактирования текста пользователем. Ниже показан пример настройки JFormattedTextField для редактирования дат:

JFormattedTextField ftf = new JFormattedTextField();
   ftf.setValue(new Date());

После создания JFormattedTextField, можно прослушивать изменения в редактировании, добавив PropertyChangeListener и прослушивая события PropertyChangeEvent с именем свойства value.

JFormattedTextField позволяет настроить действия при потере фокуса. Возможные настройки:

Значение	Описание
JFormattedTextField.REVERT	Возвращает отображение к соответствию getValue, возможно с потерей текущего редактирования.
JFormattedTextField.COMMIT	Сохраняет текущее значение. Если редактируемое значение не считается допустимым значением AbstractFormatter, то есть происходит исключение ParseException, то значение не изменится, и отредактированное значение сохранится.
JFormattedTextField.COMMIT_OR_REVERT	Аналогично COMMIT, но если значение не является допустимым, ведет себя как REVERT.
JFormattedTextField.PERSIST	Не выполняет никаких действий, не получает новое AbstractFormatter и не обновляет значение.

По умолчанию JFormattedTextField.COMMIT_OR_REVERT, см. setFocusLostBehavior(int) для получения дополнительной информации.

JFormattedTextField позволяет потерять фокус, даже если текущее редактируемое значение неверно. Чтобы заблокировать фокус, пока JFormattedTextField находится в состоянии недопустимого редактирования, можно добавить InputVerifier. Следующий фрагмент кода показывает возможную реализацию такого InputVerifier:

public class FormattedTextFieldVerifier extends InputVerifier {
     public boolean verify(JComponent input) {
         if (input instanceof JFormattedTextField) {
             JFormattedTextField ftf = (JFormattedTextField)input;
             AbstractFormatter formatter = ftf.getFormatter();
             if (formatter != null) {
                 String text = ftf.getText();
                 try {
                      formatter.stringToValue(text);
                      return true;
                  } catch (ParseException pe) {
                      return false;
                  }
              }
          }
          return true;
      }
      public boolean shouldYieldFocus(JComponent input) {
          return verify(input);
      }
  }

В качестве альтернативы можно вызвать commitEdit, что также сохранит значение.

JFormattedTextField не выполняет форматирование самостоятельно, а форматирование осуществляется с помощью экземпляра JFormattedTextField.AbstractFormatter, получаемого из экземпляра JFormattedTextField.AbstractFormatterFactory. Экземпляры JFormattedTextField.AbstractFormatter уведомляются о своем активации методом install, в этот момент JFormattedTextField.AbstractFormatter может установить все необходимое, обычно DocumentFilter. Аналогично, когда JFormattedTextField больше не нуждается в AbstractFormatter, вызывается метод uninstall.

JFormattedTextField обычно запрашивает AbstractFormatterFactory для AbstractFormat при получении или потере фокуса. Хотя это может меняться в зависимости от политики потери фокуса. Если политика потери фокуса JFormattedTextField.PERSIST и JFormattedTextField был изменен, AbstractFormatterFactory не будет запрошен до тех пор, пока значение не будет сохранено. Аналогично, если политика потери фокуса JFormattedTextField.COMMIT и stringToValue выбросит исключение, AbstractFormatterFactory не будет запрошен при потере или получении фокуса.

JFormattedTextField.AbstractFormatter также отвечает за определение моментов, когда значения сохраняются в JFormattedTextField. Некоторые JFormattedTextField.AbstractFormatter будут предоставлять новые значения при каждом редактировании, а другие никогда не сохраняют значение. Текущее значение можно получить из текущего JFormattedTextField.AbstractFormatter с помощью вызова commitEdit. commitEdit будет вызываться всякий раз, когда нажимается клавиша ВВОД в JFormattedTextField.

Если AbstractFormatterFactory не задан явно, он будет установлен на основе Class типа значения после вызова setValue (при условии, что значение не равно null). Например, в приведенном ниже коде будут созданы соответствующие AbstractFormatterFactory и AbstractFormatter для обработки форматирования чисел:

JFormattedTextField tf = new JFormattedTextField();
   tf.setValue(100);

Предупреждение: Поскольку AbstractFormatter обычно устанавливает DocumentFilter на Document, а NavigationFilter на JFormattedTextField, не следует устанавливать собственный. В противном случае вы можете столкнуться с непредсказуемым поведением, так как политика редактирования AbstractFormatter не будет применена.

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

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

Поля

COMMIT

public static final int COMMIT

Константа, определяющая, что при потере фокуса должен вызываться commitEdit. Если при фиксации нового значения возникает ParseException, недопустимое значение останется.

См. также:

setFocusLostBehavior(int), Constant Field Values

COMMIT_OR_REVERT

public static final int COMMIT_OR_REVERT

Константа, определяющая, что при потере фокуса должен вызываться commitEdit. Если при фиксации нового значения возникает ParseException, значение будет отменено.

См. также:

setFocusLostBehavior(int), Constant Field Values

REVERT

public static final int REVERT

Константа, определяющая, что при потере фокуса редактируемое значение должно быть возвращено к текущему значению, установленному в JFormattedTextField.

См. также:

setFocusLostBehavior(int), Constant Field Values

PERSIST

public static final int PERSIST

Константа, определяющая, что при потере фокуса отредактированное значение должно быть сохранено.

См. также:

setFocusLostBehavior(int), Constant Field Values

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

JFormattedTextField

public JFormattedTextField()

Создает JFormattedTextField без AbstractFormatterFactory. Используйте setMask или setFormatterFactory для настройки JFormattedTextField для редактирования определенного типа значения.

JFormattedTextField

public JFormattedTextField(Object value)

Создает JFormattedTextField с указанным значением. Это создаст AbstractFormatterFactory на основе типа value.

Параметры:

value - Начальное значение для JFormattedTextField

JFormattedTextField

public JFormattedTextField(Format format)

Создает JFormattedTextField. format обернут в соответствующий AbstractFormatter, который затем обернут в AbstractFormatterFactory.

Параметры:

format - Формат, используемый для поиска AbstractFormatter

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)

Создает JFormattedTextField с указанным AbstractFormatter. AbstractFormatter помещается в AbstractFormatterFactory.

Параметры:

formatter - AbstractFormatter для форматирования.

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)

Создает JFormattedTextField с указанным AbstractFormatterFactory.

Параметры:

factory - AbstractFormatterFactory, используемый для форматирования.

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory,
                           Object currentValue)

Создает JFormattedTextField с указанным AbstractFormatterFactory и начальным значением.

Параметры:

factory - AbstractFormatterFactory, используемый для форматирования.

currentValue - Начальное значение для использования

Методы

setFocusLostBehavior

public void setFocusLostBehavior(int behavior)

Параметры:

behavior - Определяет поведение при потере фокуса

Исключения:

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

getFocusLostBehavior

public int getFocusLostBehavior()

Возвращает поведение при потере фокуса. Это будет одно из COMMIT_OR_REVERT, COMMIT, REVERT или PERSIST. Обратите внимание, что некоторые AbstractFormatter могут отправлять изменения по мере их возникновения, так что значение этого параметра не будет иметь эффекта.

Возвращает:

возвращает поведение при потере фокуса

setFormatterFactory

public void setFormatterFactory(JFormattedTextField.AbstractFormatterFactory tf)

Параметры:

tf - AbstractFormatterFactory, используемый для поиска экземпляров AbstractFormatter

getFormatterFactory

public JFormattedTextField.AbstractFormatterFactory getFormatterFactory()

Возвращает текущий AbstractFormatterFactory.

Возвращает:

AbstractFormatterFactory, используемый для определения AbstractFormatter

См. также:

setFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)

setFormatter

protected void setFormatter(JFormattedTextField.AbstractFormatter format)

Параметры:

format - AbstractFormatter для форматирования

См. также:

setFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)

getFormatter

public JFormattedTextField.AbstractFormatter getFormatter()

Возвращает AbstractFormatter, который используется для форматирования и анализа текущего значения.

Возвращает:

AbstractFormatter, используемый для форматирования

setValue

public void setValue(Object value)

Параметры:

value - Текущее значение для отображения

getValue

public Object getValue()

Возвращает последнее допустимое значение. В зависимости от политики редактирования AbstractFormatter это может не возвращать текущее значение. Текущее редактируемое значение можно получить, вызвав commitEdit с последующим вызовом getValue.

Возвращает:

Последнее допустимое значение

commitEdit

public void commitEdit()
                throws ParseException

Принудительно берет текущее значение из AbstractFormatter и устанавливает его в качестве текущего значения. Это не оказывает никакого влияния, если не установлен текущий AbstractFormatter.

Исключения:

ParseException - если AbstractFormatter не может отформатировать текущее значение

isEditValid

public boolean isEditValid()

Возвращает true, если текущее редактируемое значение допустимо. Значение этого параметра управляется текущим AbstractFormatter, поэтому для него нет открытого установщика.

Возвращает:

true, если текущее редактируемое значение допустимо.

invalidEdit

protected void invalidEdit()

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

processInputMethodEvent

protected void processInputMethodEvent(InputMethodEvent e)

Обрабатывает любые события метода ввода, такие как InputMethodEvent.INPUT_METHOD_TEXT_CHANGED или InputMethodEvent.CARET_POSITION_CHANGED.

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

processInputMethodEvent в классе JTextComponent

Параметры:

e - InputMethodEvent

См. также:

InputMethodEvent

processFocusEvent

protected void processFocusEvent(FocusEvent e)

Обрабатывает любые события фокуса, такие как FocusEvent.FOCUS_GAINED или FocusEvent.FOCUS_LOST.

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

processFocusEvent в классе Component

Параметры:

e - FocusEvent

См. также:

FocusEvent

getActions

public Action[] getActions()

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

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

getActions в классе JTextField

Возвращает:

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

getUIClassID

public String getUIClassID()

Получает идентификатор класса для пользовательского интерфейса.

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

getUIClassID в классе JTextField

Возвращает:

строку "FormattedTextFieldUI"

См. также:

JComponent.getUIClassID()

setDocument

public void setDocument(Document doc)

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

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

setDocument в классе JTextField

Параметры:

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

См. также:

JTextComponent.getDocument()