Skip to content

2. Text Field Listener

Egor Taflanidi edited this page Mar 16, 2020 · 3 revisions

While the Mask is the cornerstone class of this library, text field listeners are the objects you'll be dealing with most of the time.

These listeners encapsulate the internal logic, giving you a façade of methods, properties, and callbacks to be configured.

Text field listeners implement text field's event handling, cursor movement logic, autocompletion control and automatic mask switching. They also interface underlying mask metrics and compiler notations.

Input Mask library provides a single implementation of a text field listener.

MaskedTextChangedListener  :  TextWatcher, View.OnFocusChangeListener

Receiving events

MaskedTextChangedListener has its own ValueListener interface:

interface ValueListener {
    fun onTextChanged(maskFilled: Boolean, extractedValue: String, formattedValue: String)
}

Here:

  • formattedValue is an output;
  • extractedValue is an extracted value;
  • maskFilled flag shows if an extracted value is complete.

MaskedTextChangedListener forwards each received TextWatcher call to its internal listener.

var listener:      TextWatcher?   = null
var valueListener: ValueListener? = null

ValueListener is assigned through the valueListener property.

Initialisation

MaskedTextChangedListener has a ton of convenience constructors for java overloads of the designated constructor.

MaskedTextChangedListener(
    var primaryFormat:   String,
    var affineFormats:   List<String>   = emptyList(),
    var customNotations: List<Notation> = emptyList(),
    var affinityCalculationStrategy: AffinityCalculationStrategy = AffinityCalculationStrategy.WHOLE_STRING,
    var autocomplete:  Boolean = true,
    var autoskip:      Boolean = false,
    field:             EditText,
    var listener:      TextWatcher? = null,
    var valueListener: ValueListener? = null
)

Properties

val primaryMask: Mask

fun placeholder():           String
fun acceptableTextLength():  Int
fun totalTextLength():       Int
fun acceptableValueLength(): Int
fun totalValueLength():      Int

Here, primaryMask is the main Mask object used to format the input.
Other readonly properties represent primary mask's properties and metrics.

Methods

fun setText(text: String, autocomplete: Boolean? = null): Mask.Result?
fun setText(text: String, field: EditText, autocomplete: Boolean? = null): Mask.Result

This method is designed to programmatically insert raw text into the EditText, simultaneously applying the format.