Класс MaskFormatter

public class MaskFormatter
extends DefaultFormatter

MaskFormatter используется для форматирования и редактирования строк. Поведение MaskFormatter контролируется с помощью строковой маски, которая определяет допустимые символы, которые могут быть содержаться в определенной позиции в модели Document. Ниже приведены поддерживаемые символы:

Символ	Описание
#	Любая допустимая цифра, использует Character.isDigit.
'	Символ экранирования, используется для экранирования специальных символов форматирования.
U	Любой символ (Character.isLetter). Все строчные буквы преобразуются в заглавные.
L	Любой символ (Character.isLetter). Все заглавные буквы преобразуются в строчные.
A	Любой символ или цифра (Character.isLetter или Character.isDigit)
?	Любой символ (Character.isLetter).
*	Любой символ.
H	Любой шестнадцатеричный символ (0-9, a-f или A-F).

Обычно символы соответствуют одному символу, но в некоторых языках это не так. Маска применяется к каждому символу и будет адаптироваться, чтобы уместить необходимое количество символов.

Вы можете дополнительно ограничить символы, которые могут быть введены, методами setInvalidCharacters и setValidCharacters. setInvalidCharacters позволяет указать недопустимые символы. setValidCharacters позволяет указать допустимые символы. Например, следующий фрагмент кода эквивалентен маске '0xHHH' без недопустимых/допустимых символов:

MaskFormatter formatter = new MaskFormatter("0x***");
 formatter.setValidCharacters("0123456789abcdefABCDEF");

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

MaskFormatter formatter = new MaskFormatter("###-####");
   formatter.setPlaceholderCharacter('_');
   formatter.getDisplayValue(tf, "123");

В результате получится строка '123-____'. Если setPlaceholder("555-1212") вызывается, то результатом будет '123-1212'. Строка-заполнитель используется только при начальном форматировании, при последующих форматированиях используется только символ-заполнитель.

Если MaskFormatter настроено на разрешение только допустимых символов (setAllowsInvalid(false)), то при редактировании будут пропущены буквальные символы. Рассмотрим MaskFormatter с маской "###-####" и текущим значением "555-1212". При использовании клавиши со стрелкой вправо для навигации по полю результат будет следующим (| указывает позицию курсора):

|555-1212
   5|55-1212
   55|5-1212
   555-|1212
   555-1|212

Символ '-' является буквальным (нередактируемым) и пропускается.

Аналогичное поведение будет наблюдаться при редактировании. Предположим, в MaskFormatter в предыдущем примере вставляются строки '123-45' и '12345'. Обе вставки приведут к одной и той же строке '123-45__'. При обработке MaskFormatter вставки в позиции 3 (символ '-'), могут произойти следующие события:

1. Если вставленный символ '-' , он принимается.
2. Если вставленный символ соответствует маске для следующего нелитерального символа, он принимается в новом месте.
3. В противном случае изменение считается недопустимым.

По умолчанию MaskFormatter не допускает недопустимых изменений, это можно изменить с помощью метода setAllowsInvalid, и изменения будут применяться при валидных изменениях (используйте метод setCommitsOnValidEdit для изменения этого).

По умолчанию MaskFormatter находится в режиме перезаписи. То есть, когда набираются символы, новый символ не вставляется, а символ в текущей позиции заменяется на набранный символ. Это поведение можно изменить с помощью метода setOverwriteMode.

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

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

MaskFormatter

public MaskFormatter()

Создаёт MaskFormatter без маски.

MaskFormatter

public MaskFormatter(String mask)
              throws ParseException

Создаёт MaskFormatter с указанной маской. Будет выброшено исключение ParseException, если mask является недопустимой маской.

Исключения:

ParseException - если маска не содержит допустимых символов маски

Методы

setMask

public void setMask(String mask)
             throws ParseException

Устанавливает маску, определяющую допустимые символы. Будет выброшено исключение ParseException, если mask не является допустимой.

Исключения:

ParseException - если маска не содержит допустимых символов маски

getMask

public String getMask()

Возвращает маску форматирования.

Возвращает:

Маска, определяющая допустимые символы.

setValidCharacters

public void setValidCharacters(String validCharacters)

Позволяет дополнительно ограничить символы, которые можно ввести. Допустимы только символы, указанные в маске, не в invalidCharacters, и в validCharacters. Передача null (по умолчанию) подразумевает, что допустимые символы ограничены только маской и недопустимыми символами.

Параметры:

validCharacters - Если не null, задаёт допустимые символы.

getValidCharacters

public String getValidCharacters()

Возвращает допустимые символы, которые можно ввести.

Возвращает:

Допустимые символы

setInvalidCharacters

public void setInvalidCharacters(String invalidCharacters)

Позволяет дополнительно ограничить символы, которые можно ввести. Допустимы только символы, указанные в маске, не в invalidCharacters, и в validCharacters. Передача null (по умолчанию) подразумевает, что допустимые символы ограничены только маской и допустимыми символами.

Параметры:

invalidCharacters - Если не null, задаёт недопустимые символы.

getInvalidCharacters

public String getInvalidCharacters()

Возвращает символы, которые недопустимы для ввода.

Возвращает:

Недопустимые символы.

setPlaceholder

public void setPlaceholder(String placeholder)

Устанавливает строку для использования, если значение не полностью заполняет маску. Значение null подразумевает, что должен использоваться символ-заполнитель.

Параметры:

placeholder - Строка, используемая при форматировании, если значение не полностью заполняет маску

getPlaceholder

public String getPlaceholder()

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

Возвращает:

Строка, используемая при форматировании, если значение не полностью заполняет маску

setPlaceholderCharacter

public void setPlaceholderCharacter(char placeholder)

Параметры:

placeholder - Символ, используемый при форматировании, если значение не полностью заполняет маску

getPlaceholderCharacter

public char getPlaceholderCharacter()

Возвращает символ для использования вместо символов, отсутствующих в значении, т.е. пользователь должен их заполнить.

Возвращает:

Символ, используемый при форматировании, если значение не полностью заполняет маску

setValueContainsLiteralCharacters

public void setValueContainsLiteralCharacters(boolean containsLiteralChars)

Параметры:

containsLiteralChars - Используется для указания, должны ли возвращаться символы-литералы в маске в строке stringToValue

getValueContainsLiteralCharacters

public boolean getValueContainsLiteralCharacters()

Возвращает true, если stringToValue должен возвращать символы-литералы в маске.

Возвращает:

True, если символы-литералы в маске должны возвращаться в stringToValue

stringToValue

public Object stringToValue(String value)
                     throws ParseException

Парсит текст, возвращая соответствующее представление объекта строки value. Это удаляет символы-литералы по мере необходимости и вызывает родительский метод stringToValue, так что если вы указали класс значения (setValueClass), будет создан экземпляр этого класса. Это вызовет исключение ParseException, если значение не соответствует текущей маске. Обратитесь к setValueContainsLiteralCharacters(boolean) для получения подробной информации о том, как обрабатываются литералы.

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

stringToValue в классе DefaultFormatter

Параметры:

value - Строка для преобразования

Возвращает:

Объектное представление текста

Исключения:

ParseException - если при преобразовании произошла ошибка

См. также:

setValueContainsLiteralCharacters(boolean)

valueToString

public String valueToString(Object value)
                     throws ParseException

Возвращает строковое представление объекта value на основе маски. Обратитесь к setValueContainsLiteralCharacters(boolean) для получения подробной информации о том, как обрабатываются литералы.

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

valueToString в классе DefaultFormatter

Параметры:

value - Значение для преобразования

Возвращает:

Строковое представление значения

Исключения:

ParseException - если при преобразовании произошла ошибка

См. также:

setValueContainsLiteralCharacters(boolean)

install

public void install(JFormattedTextField ftf)

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

install в классе DefaultFormatter

Параметры:

ftf - JFormattedTextField для форматирования, может быть null, что указывает на отключение от текущего JFormattedTextField.