Как работает маска

Маска позволяет форматировать последовательности символов с помощью связного списка слотов. Маска не занимается созданием слотов (за исключением случаев клонирования слота в нетерминированной маске, (см. ниже). Для получения форматированного текста, текст должен быть вставлен в маску с помощью методов Mask#insertAt() или Mask#insertFront(). Для получения форматированной строки необходимо вызвать метод Mask#toString().

Для создания маски необходимы два параметра:

1. Массив слотов. Маска преобразовывет слоты в двусвязый список и хранит в в нем введенный текст.
2. Флаг терминированности. Определяет, возможна ли вставка символов когда все слоты заполнены.

Флаг терминированности

Данный флаг определяет возможна ли вставка символов в маску, когда все слоты заполнены (см. приверы 1 и 2). Если маска нетерминирована, последний слот будет бесконечно копироваться, удлиняя маску. Это позволяет делать маски "бесконечной" длины. Однако символы, вставленные "сверх нормы", форматированы не будут.

Параметры маски

Кроме списка слотов и флага терминированности маска обладает некоторыми настраиваемыми параметрами:

1. forbidInputWhenFilled - если true, запрещает вставку в маску новых символов. Если false, при вставке в середину заполненной маски, новые символы будут "выталкивать" символы из конца маски. По умолчанию - false.
2. hideHardcodedHead - если true скрывает hardcoded последовательность в начале строки при отсутствии пользовательсткого ввода (см. пример ниже) при вызове toString(). По умолчанию - false.
3. showingEmptySlots - если true и в маске есть незаполненные слоты, то эти слоты будут выведены в toString(). ВАЖНО: когда данный флаг выставлен в true, флаг hideHardcodedHead игнорируется. По умолчанию - false
4. placeholder - символ, которым заменяются пустые пустые слоты при вызове toString() когда showingEmptySlots = true. По умолчанию _ (нижнее подчеркивание).

Пример использования флага Mask#hideHardcodedHead

Пример 1:

Mask mask = MaskImpl.createTerminated(PredefinedSlots.RUS_PHONE_NUMBER); // +7 (___) ___-__-__
System.out.println(mask.toString()); // +7 (

Пример 2:

Mask mask = MaskImpl.createTerminated(PredefinedSlots.RUS_PHONE_NUMBER); // +7 (___) ___-__-__
mask.setHideHardcodedHead(true);
System.out.println(mask.toString()); // nothing

В примерах выше произодится вывод пустой (без пользовательского ввода) маски для ввода номера телефона. Данная маска имеет hardcoded-последовательность в начале - "+7 (". В примере 1 будет выведена эта последовательность, т.к. hideHardcodedHead = false, в примере 2 не будет выведено ничего, т.к. hideHardcodedHead = true.

Пример использования флага Mask#showingEmptySlots и параметра Mask#placeholder

Пример 3:

Mask mask = MaskImpl.createTerminated(PredefinedSlots.RUS_PHONE_NUMBER);
mask.setShowingEmptySlots(true);
mask.setPlaceholder('*');
mask.insertFront("999");
System.out.println(mask.toString()); // +7 (999) ***-**-**

Получение неформатированного ввода

Для получения неформатированной строки используется метод Mask#getUnformattedString(boolean). Данный метод возвращает строку из значений всех слотов, за исключением декоративных (см. Что такое слот).

Пример 4: получение неформатированной строки

Mask mask = MaskImpl.createTerminated(new Slot[]{
        PredefinedSlots.digit(),                                          // слот для цифры
        PredefinedSlots.digit(),                                          // слот для цифры
        PredefinedSlots.hardcodedSlot('-').withTags(Slot.TAG_DECORATION), // декоративный hardcoded слот
        PredefinedSlots.digit(),                                          // слот для цифры
        PredefinedSlots.digit(),                                          // слот для цифры
});
mask.insertFront("1234");
System.out.println(mask.toString());                    // 12-34
System.out.println(mask.toUnformattedString());         // 1234

Пример 5: получение неформатированной строки

Mask mask = MaskImpl.createTerminated(PredefinedSlots.RUS_PHONE_NUMBER);
mask.insertFront("9995554433");
System.out.println(mask.toString());                    // +7 (999) 555-44-33
System.out.println(mask.toUnformattedString());         // +79995554433