спецификации, руководства, описания, API

Отформатированные Текстовые поля

Этот документ обрисовывает в общих чертах реализацию Swing отформатированных текстовых полей. Отформатированные текстовые поля обеспечивают способ для разработчиков определить юридический набор символов, которые могут быть введены в текстовый компонент. Этот документ располагается в следующих разделах:

Используя JFormattedTextField
Как JFormattedTextField Работает
Фильтрация Ввода
Фильтрация Навигации
JFormattedTextField. AbstractFormatter
JFormattedTextField.AbstractFormatterFactory
DefaultFormatter
Реализации AbstractFormatter
java.text. Изменения формата
JavaDoc

Используя JFormattedTextField

JFormattedTextField позволит форматировать дат, чисел, Строк и произвольных Объектов. JFormattedTextField положится java.text.Format классы, чтобы обработать форматирование дат и чисел. Создать a JFormattedTextField вводить даты в текущем специфичном для локали формате:

    new JFormattedTextField(new Date());

Если Вы должны вывести на экран даты в определенном формате, можно использовать один из SimpleDateFormat конструкторы:

    new JFormattedTextField(new SimpleDateFormat("MM/dd/yy"));

Числа будут обработаны экземпляром java.text.NumberFormat. Следующие шоу несколько способов создать a JFormattedTextField отредактировать числа.

   new JFormattedTextField(new Number(1000));
   new JFormattedTextField(new DecimalFormat("#,###"));
   new JFormattedTextField(new DecimalFormat("0.###E0"));

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

   new JFormattedTextField(new MaskFormatter("(###) ###-####"));

Как JFormattedTextField Работает

JFormattedTextField непосредственно представляет минимальное количество API в дополнение к тому из его class высшего качества, JTextField. В его самых простых сроках, JFormattedTextField может считаться a JTextField с дополнительным свойством значения (Объекта типа) и объекта обработать форматирование (экземпляр AbstractFormatter).

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

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

Типичный сеанс для того, чтобы отредактировать числа похож:

  JFormattedTextField ftf = new JFormattedTextField();
  ftf.setValue(new Integer(1000));
  ...
  int intValue = ((Number)ftf.getValue()).intValue();

Фильтрация Ввода

Ограничение ввода в текстовый компонент ранее потребовало создания подкласса Document. Это - довольно тяжелая работа для такого простого, и общего, использования. Чтобы сделать эту задачу легче, мы создали class, DocumentFilter, это может быть включено в a Document (Document интерфейс, который не изменился, вместо этого AbstractDocument теперь имеет метод set/метода get для a DocumentFilter, и свойство устанавливается для Documents, которые не убывают от AbstractDocument так, чтобы другие могли поддерживать DocumentFilter если они хотят к). Когда a Document с a DocumentFilter передается, чтобы удалить или вставить контент, Document вызывает соответствующий метод на DocumentFilter. Это DocumentFilter's обязанность выпустить обратный вызов, если работа должна продолжиться. Этим способом DocumentFilter имеет полный контроль по как Document может быть видоизменен. DocumentFilter определяется:

  public void remove(FilterBypass fb, int offset, int length) throws BadLocationException;
  public void insertString(FilterBypass fb, int offset, String string, AttributeSet attr) throws BadLocationException;
  public void replace(FilterBypass fb, int offset, int length, String string, AttributeSet attr) throws BadLocationException;

Если DocumentFilter хочет видоизмениться Document изнутри remove или insertString методы, это должно или вызвать super's реализация, или вызывают метод на FilterBypass. Вызов метода на super или FilterBypass обеспечивает способ обойти фильтр так, чтобы вызывающая сторона не застряла в рекурсии стека. DocumentFilter не ограничивается только вызовом одного метода назад на FilterBypass. Это может вызвать любой из методов, представленных FilterBypass, и может вызвать их так много раз, как это желает (в рамках одного из DocumentFilter's методы). FilterBypass определяется:

  public abstract Document getDocument();
  public abstract void remove(int offset, int length) throws BadLocationException;
  public abstract void insertString(int offset, String string, AttributeSet attr) throws BadLocationException;
  public abstract void replace(int offset, int length, String string, AttributeSet attr) throws BadLocationException;

Следующий пример иллюстрирует создание a DocumentFilter это отображает нижний регистр на прописные буквы:

   DocumentFilter upperDF = new DocumentFilter() {
      public void insertString(FilterBypass fb, int offset, String string, AttributeSet attr) throws BadLocationException {
          super.insertString(fb, offset, string.toUpperCase(), attr);
      }

      public void replace(FilterBypass fb, int offset, int length, String string, AttributeSet attr) throws BadLocationException {
          if (string != null) {
              string = text.toUpperCase();
          }
          super.replace(fb, offset, length, string, attr);
      }
   };

Фильтрация Навигации

Подобный DocumentFilter, новый class, NavigationFilter, учитывает фильтрацию, куда выбор может быть помещен. NavigationFilter вызывается действиями навигации (такой как оставлено, право, центр), чтобы определить следующую позицию, чтобы поместить выбор от данной позиции. NavigationFilter свойство на JTextComponent, и определяется:

    public void setDot(FilterBypass fb, int dot, Position.Bias bias);
    public void moveDot(FilterBypass fb, int dot, Position.Bias bias);
    public int getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) throws BadLocationException;

Отметьте это getNextVisualPositionFrom определяется в View; для непротиворечивости, метода в NavigationFilter называется тем же самым.

Подобный DocumentFilter, NavigationFilter передается a FilterBypass это должно быть вызвано, чтобы обработать фактическую мутацию. NavigationFilter.FilterBypass определяется:

    public abstract Caret getCaret();
    public abstract void setDot(int dot, Position.Bias bias);
    public abstract void moveDot(int dot, Position.Bias bias);

JFormattedTextField. AbstractFormatter

Как ранее упомянуто, экземпляр AbstractFormatter используется, чтобы отформатировать определенное Объектное значение. AbstractFormatter может также наложить политику редактирования, определяя a DocumentFilter; это может также наложить политику навигации, определяя a NavigationFilter. AbstractFormatter определяется:

    public void install(JFormattedTextField ftf);
    public void uninstall();
    public abstract Object stringToValue(String text) throws ParseException;
    public abstract String valueToString(Object value) throws ParseException;
    protected JFormattedTextField getFormattedTextField();
    protected void setEditValid(boolean valid);
    protected void invalidEdit();
    protected Action[] getActions();
    protected DocumentFilter getDocumentFilter();
    protected NavigationFilter getNavigationFilter();

Однажды JFormattedTextField готово использовать AbstractFormatter это вызывает install. AbstractFormatter.install выполняет следующее:

Устанавливает текст JFormattedTextField к возвращаемому значению valueToString (если a ParseException бросается, пустая Строка используется и setEditValid(false) вызывается).
Установки DocumentFilter возвращенный из getDocumentFilter на JFormattedTextField's Document.
Установки NavigationFilter возвращенный из getNavigationFilter на JFormattedTextField.
Установки Actions возвратился из getActions на JFormattedTextField's ActionMap.

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

Некоторые AbstractFormatters позволяют JFormattedTextField содержать недопустимое значение, редактируя. Позволить JFormattedTextField обеспечить индикацию относительно этого, AbstractFormatter должен вызвать setEditValid(false) когда пользователь вводит недопустимое значение, и затем вызовите setEditValid(true) когда значение допустимо снова.

Когда JFormattedTextField делается с AbstractFormatter, это вызывает uninstall. uninstall удаляет ранее установленный Listeners.

JFormattedTextField.AbstractFormatterFactory

JFormattedTextField делегирует создание AbstractFormatters к экземпляру AbstractFormatterFactory (общедоступный статический внутренний class JFormattedTextField). Это облегчает для разработчиков обеспечивать различные средства форматирования для различных состояний JFormattedTextField. Например, Вы могли обеспечить специальное предложение AbstractFormatter если текущая стоимость null, или одно средство форматирования, редактируя и другой, выводя на экран. AbstractFormatterFactory определяется:

    public abstract AbstractFormatter getFormatter(JFormattedTextField ftf);

Если разработчик не предоставил AbstractFormatterFactory, каждый будет создаваться основанный на Class из значения.

DefaultFormatter

DefaultFormatter расширяется JFormattedTextField.AbstractFormatter и суперкласс для всех реализаций средства форматирования, которые мы обеспечиваем. DefaultFormatter использование Объектов форматов toString и создает Объект, используя конструктора, который берет Строку. DefaultFormatter позволяет много параметров конфигурации:

Опция	Описание
CommitsOnValidEdit	Определяет, когда редактирования публикуются назад к `JFormattedTextField`. Если `true`, `commitEdit` вызывается на `JFormattedTextField` после каждого успешного редактирования, иначе `commitEdit` вызывается только, когда возврат нажимается.
OverwriteMode	Конфигурирует поведение, вставляя символы. Если `overwriteMode` `true` (значение по умолчанию), новые символы перезаписывают существующие символы в модели, поскольку они вставляются.
AllowsInvalid	Определяет, позволяют ли отредактированному значению быть недопустимым. Часто удобно позволить пользователю вводить недопустимые значения, пока фиксация не предпринимается.

Реализации AbstractFormatter

Следующая таблица приводит AbstractFormatter реализации, которые мы обеспечиваем, так же как предназначенное использование:

AbstractFormatter	Объектный Тип	Примечания
DefaultFormatter	Объект	`valueToString` использование `Object.toString()`, и `stringToValue` использует единственного конструктора параметра, который берет Строку.
MaskFormatter	Строки	Поведение диктуют на символьную маску, которая определяет юридические значения (например, "###-####").
InternationalFormatter	Объекты	Использует экземпляр `java.text.Format` обработать `valueToString` и `stringToValue`.
NumberFormatter	Числа	Использует экземпляр `NumberFormat` чтобы обработать форматирование, убывает от `InternationalFormatter`.
DateFormatter	Дата	Использует экземпляр `DateFormat` чтобы обработать форматирование, убывает от `InternationalFormatter`.

java.text. Изменения формата

Поддержка Swing отформатированных дат и чисел, сделанных широким применением Format классы в java.text пакет. Со следующими проблемами встретились, используя предыдущий API:

Вы могли только получить пределы одного поля за один раз. Если бы Вы хотели больше, то необходимо вызвать format неоднократно.
Предыдущие полевые константы не были достаточны, чтобы описать весь текст отформатированных строк. Один бликующий пропуск был экспоненциальной частью отформатированных чисел.
Используя целочисленные ID для ряда констант, которые симулировали быть расширяемыми, не было очень изящно. Когда новые константы были добавлены, мог потенциально быть конфликт с любым Format подклассы там, что мы не знали о. Отметьте что константы DateFormat и NumberFormat уже перекрытие, таким образом, a NumberFormat счастливо интерпретировал бы YEAR_FIELD как FRACTION_FIELD. Проблема была усилена существованием полиморфного Format.format(Object, StringBuffer, FieldPosition) метод.
Спецификация не определяла поведение, если поле не существовало в отформатированной строке, и фактических результатах, различных между различными выпусками.
Спецификация не определяла поведение, если поле не было распознано средством форматирования; например, если я спросил a NumberFormat для MONTH_FIELD (фактическая реализация этого случая, возвращенного 0 и для, начинается, индексируют и конец, индексируют).
Из-за этого вызывающая сторона не могла узнать который поля a Format разделите на подклассы фактически поддерживаемый, если это не знало определенный подкласс. Это, наряду с фактом, что не все символы в отформатированной строке являются частью полей, делает реализацию универсального метода, который возвращает все невозможные поля.

Эти проблемы были в значительной степени решены, добавляя следующий метод к java.text.Format:

    public AttributedCharacterIterator formatToCharacterIterator(Object obj);

Каждый Format class использует безопасное с точки зрения типов перечисление для констант, которые он поддерживает.

JavaDoc

Новые Классы

Следующие классы в новинку для этих 1.4 выпусков:

Константы переименовываются, чтобы соответствовать соглашениям о присвоении имен Java

Отчет bugtraq, который соответствует этому изменению: 4468474.

Следующие константы были заменены, чтобы приспособить Java соглашениям о присвоении имен:

CommitValueOnFocusLost был заменен COMMIT.
CommitOrRevertValueOnFocusLost был заменен COMMIT_OR_REVERT.
RevertValueOnFocusLost был заменен REVERT.
PersistValueOnFocusLost был заменен PERSIST.

Свяжитесь с Нами