-
Notifications
You must be signed in to change notification settings - Fork 119
0. Mask
Mask
is the central class responsible for formatting the input, producing the output, and extracting the valuable characters.
class Mask(format: String, private val customNotations: List<Notation>) {
data class Result(
val formattedText: CaretString,
val extractedValue: String,
val affinity: Int,
val complete: Boolean
)
constructor(format: String): this(format, emptyList())
companion object Factory {
fun getOrCreate(format: String, customNotations: List<Notation>): Mask
fun isValid(format: String, customNotations: List<Notation>): Boolean
}
fun apply(text: CaretString): Result
fun placeholder(): String
fun acceptableTextLength(): Int
fun totalTextLength(): Int
fun acceptableValueLength(): Int
fun totalValueLength(): Int
}
Mask
object is a state machine with its own internal graph of states to move through. The graph is compiled from the format
during the initialisation. If the format
is invalid, compiler throws an exception.
Mask(format: String, private val customNotations: List<Notation>)
— constructor passes the list of custom notations and the format
to the internal compiler.
fun Factory::getOrCreate(format: String, customNotations: List<Notation>): Mask
— in order to avoid graph re-compilation overhead each time you make a Mask
object, use the getOrCreate()
class method — it has its own cache from where previously created Mask
objects with similar graphs are fetched instead of being created.
fun Factory::isValid(format: String, customNotations: List<Notation>): Boolean
— is a convenience method to check whether or not this particular format
will cause a compilation exception given the list of custom notations.
fun apply(text: CaretString): Result
— use this method to format text without involving a View
.
CaretString
is a structure representing a string and a caret (cursor) position inside of it.
data class CaretString(val string: String, val caretPosition: Int, val caretGravity: CaretGravity)
The caretGravity
property is a flag containing the direction, towards which the cursor gravitates during the formatting.
Adding and removing characters leads to the cursor movements. For instance, if the input string contains unwanted symbols, they are removed, and the cursor moves left:
Mask: [000]
Input: 1a2
^
Output: 12
^
Autocompletion allows predictive insertion of constant characters (see constant blocks and separators).
For instance, having a MM/YY
date field, /
symbol would require a full keyboard, but you can actually get away with a numeric one:
[00]{/}[00]
Key pressed Output
1 1
2 12/
3 12/3
4 12/34
Without the autocompletion, the picture is a bit different:
Key pressed Output
1 1
2 12
3 12/3
4 12/34
Enabled autocompletion essentially helps user to understand that he doesn't need to type the dividing /
by his hand, which makes data input more clear.
The autocomplete
flag is attached to the CaretGravity.FORWARD
sealed class variant: autocompletion cannot coexist with the .BACKWARD
gravity.
Automatic character skipping works as an "anti-autocompletion", erasing the constant characters (see constant blocks and separators) at the end of the line when hitting backspace.
This feature also allows the cursor to jump over those blocks of symbols in the middle of the text as if they were a single char.
The autoskip
flag is attached to the CaretGravity.BACKWARD
sealed class variant: automatic character skipping cannot coexist with the .FORWARD
gravity.
The resulting cursor position along with the output (formatted text), value completeness and calculated affinity are returned as a Mask.Result
object:
data class Result(
val formattedText: CaretString,
val extractedValue: String,
val affinity: Int,
val complete: Boolean
)
affinity
is an integer value representing the similarity between the input and the mask pattern. This value is necessary to determine the most suitable mask.
complete
flag shows if the extracted value contains all the mandatory characters.
Each mask has its metrics.
-
acceptableTextLength
is the minimum length the output has to be in order to be acceptable (complete == true
); -
totalTextLength
is the maximum output length, with all optional characters included; -
acceptableValueLength
is the minimum acceptable extracted value length; -
totalValueLength
is the maximum extracted value length.
placeholder
produces a simple placeholder text that can serve as a text field hint (including optional symbols; a
for arbitrary letters, 0
for arbitrary digits, -
for arbitrary alphanumerics):
([009])[Aa] ~> (000)aa