Jetpack Compose: VisualTransformation Made Simpler | by Carter Hudson | Mar, 2023 | Energy Tech

For those who do not care how the sausage is made, skip to the top for the implementation.

Jetpack Compose has launched the VisualTransformationAPI for formatting and remodeling TextField enter. I just lately had a must format a cellphone quantity because it was written, so I looked for an idiomatic resolution.

Not desirous to reinvent the wheel, I went searching for an answer. Certainly somebody had already fastened this, proper? Effectively, not a lot, it appears.

Each proposed implementation I might discover appeared overly designed or utterly guide in its calculations. My mind simply nops. Strive it your self, give it a search.

Taking the time to know it, not to mention keep it up sooner or later, looks as if an even bigger time funding than I am keen to make. There must be a greater manner, proper?

Let’s attempt to implement ours.

This class needs you to implement the filter perform, which is to format the incoming uncooked string to the illustration for show. I want that they had referred to as this perform one thing else, like formatHowever it’s what it’s.

The return worth of this perform needs an occasion of TransformedText. Let’s have a look at what it is all about

Right here we have now two parameters to the constructor: AnnotatedStringand one thing referred to as OffsetMapping. He AnnotatedString it is fairly widespread, so I will not go into an excessive amount of element right here. It will simply maintain your string formatted usually, so you will find yourself with one thing like AnnotatedString(textual content = SomeFormatter.format(textual content), ...). Fairly easy. Now, what in regards to the second parameter of TransformedText? one thing referred to as OffsetMapping.

Oh boy let me let you know in regards to the vampire of time that’s OffsetMapping. This factor is the true meat and potatoes of transformation. That is the place the magic occurs.

Okay, a minor rant right here – skip a couple of paragraphs in the event you do not thoughts.

To start with, the parameter title actually bothers me: offset. It appears innocuous sufficient at first look, however what precisely are we compensating for? Let’s have a look at the paperwork:

Convert the unique textual content offset to the remodeled textual content offset.
This perform have to be a monotonically non-decreasing perform. In different phrases, if a cursor advances within the unique textual content, the cursor within the remodeled textual content should advance or keep there.

Monotonically nondecreasing. Understood. I am glad they simplified it for me within the subsequent sentence.

Okay, if we use some context clues right here, we will assume that it is in regards to the cursor offset for the TextField. It is smart, proper? For those who begin including symbols and so forth to a cellphone quantity, the cursor place for the unique textual content won’t be the identical place within the remodeled textual content.

From what I can inform, the bidirectionality of the factor helps when the consumer highlights segments of textual content for copy/paste. Both manner, he needs each, so we’ll give him each.

Finish of the diatribe.

For those who search on-line, you will see folks recommending a extra guide process for offering compensation allowances. When implementing originalToTransformedit will think about the present cursor offset within the unique string and take into consideration the place that might be within the remodeled string.

A zero offset is to the left of the place the primary character would seem: the remaining place of a void TextField.

An offset with the worth 1 can be to the correct of the primary character, and so forth.

That is fairly simple for one thing like a zipper code or bank card. Let us take a look at a really fast instance. Be happy to skip this if you have already got the thought.

I observed that there appear to be two approaches to formatting these strings: what I name “anxious” and “lazy”, for lack of higher phrases. I simply made this up. For instance, let’s check out a zipper code.

Fundamental ZIP codes are 5 digits, however typically the types provide the possibility, and even require, a ZIP+4 format. ZIP+4 has 5 digits, a hyphen, after which 4 digits: xxxxx-xxxx.

Anxious towards Lazy refers to when the spacers are inserted.

Observe: | refers back to the cursor

Anxious

What I name “keen” right here, within the case of a zipper code, signifies that the hyphen would seem when the fifth digit is entered: 1234| -> 12345-|

Lazy

In contrast, what I name “lazy” refers to inserting the hyphen when the sixth character is entered: 12345| -> 12345-6|

Which one ought to I take advantage of?

Actually, it relies upon, and it varies. If in case you have a formatter that you don’t have any management over, like Google’s cellphone quantity formatter, you owe it to them. If in case you have management over the formatter, you may dictate which technique to make use of. For our zip instance, if ZIP+4 is required, perhaps it’s going to eagerly show the script. If it is non-compulsory, perhaps solely present it if the consumer begins typing it.

For those who combine methods between formatters and offset mappings, you may get misplaced cursors or, in some circumstances, crash altogether.

Now that that is out of the best way, let’s think about one thing extra sophisticated than a zipper code.

Bank card: lazy formatter, lazy offsets

Let’s have a look at how we will visually remodel a bank card quantity because it’s entered. We might be utilizing a lazy formatter and lazy offsets for this instance. In contrast to the zip instance, we have now a couple of separator that we should respect. First, our easy formatter:

object LazyCreditCardFormatter : Formatter 
override enjoyable format(enter: CharSequence): CharSequence =
enter
.chunked(4)
.joinToString(" ")

Fairly easy and lazy. Now we have now to consider our OffsetMapping

Unique to Remodeled

They offer us the unique cursor offset, and we’re pressured to compute what the offset can be for the remodeled string. You may discover that I’ve used concrete ranges right here fairly than attempting to assemble them abstractly by making larger than/lower than statements.

override enjoyable originalToTransformed(offset: Int): Int =
when (offset) 
in (1..4) -> offset
in (5..8) -> offset + 1
in (9..12) -> offset + 2
in (13..16) -> offset + 3
else -> offset

If we’re within the first vary, no separators have been inserted into the remodeled string, so nothing modifications with our offsets.

If we’re within the second vary, meaning a fifth character has been entered. The string has been formatted to have an area between characters 4 and 5. That is the purpose at which the formatter and offset allocation ought to observe the identical keen or lazy technique. If the cursor have been within the unique string, it will be after the fifth character. Since an additional area has been inserted, we have to transfer it after the sixth character, so offset + 1and so forth for every rank dice.

Remodeled to Unique

This one breaks my mind typically, for no matter cause. On this instance, we go in the wrong way for the offset transformations. Our vary cubes are barely completely different, relying on how we wish the cursor location to behave when a consumer highlights textual content. You’ll have to mess around with this a bit for every particular case.

override enjoyable transformedToOriginal(offset: Int): Int =
when (offset) 
in (1..4) -> offset
in (5..9) -> offset - 1
in (11..14) -> offset - 2
in (15..19) -> offset - 3
else -> offset

that doesn’t appear additionally unhealthy. Our when assertion has grown a bit, however that is to be anticipated with extra separators within the combine, proper? At worst, you will most likely spend an hour or two soaking in it, attempting to get it to behave correctly. You might must tweak and tweak it a bit for every completely different use case.

However what if you must do one thing that has a extra dynamic format, like a cellphone quantity?

Certainly not do I need to discover out all of the doable compensation assignments for cellphone numbers. The format can change drastically as you kind, to not point out the varied codecs for worldwide calls. That looks as if a nightmare. Let’s search for a extra dynamic resolution.

originaltransformed

In originalToTransformed, we have been making some additions relying on which vary group the unique offset was in. Some concepts come to thoughts, however they shortly show naive below check.

Can we rely what number of separators are within the formatted string after which add it to our unique offset? That finally ends up breaking the cursor path by way of your complete string. If in case you have 3 separators, you may solely return to the third offset.

What about one thing like this?

override enjoyable originalToTransformed(offset: Int): Int 
if (offset == 0) 
return 0
return formatted
.substring(0, offset)
.rely  isSeparator(it)  + offset

That will not work both. The cursor location is delayed after the primary separator is inserted. If we substrict to offsetwe fall behind after the primary separator and have bizarre cursor placement each time.

I can’t insist on the purpose. I simply know that I attempted lots of issues. Really feel a little bit unhealthy for me, okay? I am working with a tiny mind, right here.

after which clicked

What we actually need to know is the place to place the cursor within the remodeled string, when given a place within the unique string, proper?

Take into account the uncooked string 5551234and the formatted string 555–1234.

We all know that every index within the string is one lower than the correct shift of that character. If we have a look at the formatted string, we all know all of the indices of all of the characters. If we all know that, we will derive every offset for every character, proper? It is only a matter of filtering out the indices we’re fascinated about and changing the indices into offsets.

if we circled 555–1234 in an inventory of indices for all non-separator characters, we’d find yourself with [0,1,2,4,5,6,7]. Discover that the script index is lacking.

If we add one to every of these indices, we would find yourself with offsets: [1,2,3,5,6,7,8]. Nevertheless, if we run this, we’ll by no means be capable of transfer the cursor to the left of the primary character, every shift might be offset by one, and we’ll most likely crash with empty strings. That is straightforward sufficient to repair: simply prepend a 0 in the beginning and we’ll clear up all these issues: [0,1,2,3,5,6,7,8].

Now we all the time know every remodeled offset. Since we filter out all separators, we will entry utilizing the unique offset with out going out of bounds.

Let’s attempt. If we’re given an unique offset of 4, we all know we’d place the cursor right here: 555-1|234 within the remodeled string. If we entry our record of offsets remodeled at index 4, we get 5. The fifth offset within the remodeled string might be to the correct of the 1simply as we wish.

Right here is the related implementation:

override enjoyable originalToTransformed(offset: Int): Int 
val transformedOffsets = formatted
.mapIndexedNotNull  index, c ->
index
.takeIf  PhoneNumberUtils.isNonSeparator(c) 
// convert index to an offset
?.plus(1)

// We need to help an offset of 0 and shift the whole lot to the correct,
// so we prepend that index by default
.let  offsetList ->
listOf(0) + offsetList
return transformedOffsets[offset]

remodeled to unique

Let’s have a look at one other instance:

(555) 123-4567

If we’re given a remodeled offset of 11, which is to the correct of 4, we will have a look at our unique string and see that it will correspond to an offset of seven. The important thing right here is to note the sample. The distinction between the values ​​of the 2 offsets is the same as the variety of separators previous the remodeled offset.

As soon as we discover that, issues turn out to be fairly easy:

override enjoyable transformedToOriginal(offset: Int): Int =
formatted
// This creates an inventory of all separator offsets
.mapIndexedNotNull  index, c ->
index.takeIf  !PhoneNumberUtils.isNonSeparator(c) 

// We need to rely what number of separators precede the remodeled offset
.rely  separatorIndex ->
separatorIndex < offset

// We discover the unique offset by subtracting the variety of separators
.let  separatorCount ->
offset - separatorCount

There we go, that is so a lot better than having to put in writing an excellent tedious when assertion. However taking a look at this, would not this resolution appear fairly generic already?

The one factor right here that refers to cellphone numbers is PhoneNumberUtils.isNonSeparator(c). With that in thoughts, we might most likely make a generic implementation fairly simply:

summary class GenericSeparatorVisualTransformation : VisualTransformation {
summary enjoyable remodel(enter: CharSequence): CharSequence
summary enjoyable isSeparator(char: Char): Boolean
override enjoyable filter(textual content: AnnotatedString): TransformedText {
val formatted = remodel(textual content)
return TransformedText(
textual content = AnnotatedString(textual content = formatted.toString()),
object : OffsetMapping 
override enjoyable originalToTransformed(offset: Int): Int 
val transformedOffsets = formatted
.mapIndexedNotNull  index, c ->
index
.takeIf  !isSeparator(c) 
// convert index to an offset
?.plus(1)

// We need to help an offset of 0 and shift the whole lot to the correct,
// so we prepend that index by default
.let  offsetList ->
listOf(0) + offsetList
return transformedOffsets[offset]
override enjoyable transformedToOriginal(offset: Int): Int =
formatted
// This creates an inventory of all separator offsets
.mapIndexedNotNull  index, c ->
index.takeIf  isSeparator(c) 

// We need to rely what number of separators precede the remodeled offset
.rely  separatorIndex ->
separatorIndex < offset

// We discover the unique offset by subtracting the variety of separators
.let  separatorCount ->
offset - separatorCount


)
}
}

I ended up utilizing this to format cellphone numbers. As a bonus, right here is a straightforward cellphone quantity formatter I ready that helps worldwide format. Press 0 as the primary entry to prepend a +which prompts the worldwide format.

class SimplePhoneNumberFormatter(defaultCountry: String = Locale.getDefault().nation) 
non-public val formatter = PhoneNumberUtil.getInstance().getAsYouTypeFormatter(defaultCountry)
non-public enjoyable String.replaceIndexIf(
index: Int,
worth: Char,
predicate: (Char) -> Boolean
): String =
if (predicate(get(index))) 
toCharArray()
.apply  set(index, worth) 
.let(::String)
 else this
enjoyable format(quantity: String): String =
quantity
.takeIf  it.isNotBlank() 
?.replaceIndexIf(0, '+')  c ->
c == '0'

?.filter  it == '+' 
?.let  sanitized ->
formatter.clear()
var formatted = ""
sanitized.forEach 
formatted = formatter.inputDigit(it)

formatted
 ?: quantity

Use these two courses collectively like this:

class PhoneNumberVisualTransformation(
defaultLocale: Locale = Locale.getDefault(),
) : GenericSeparatorVisualTransformation() 
non-public val phoneNumberFormatter = SimplePhoneNumberFormatter(defaultLocale.nation)
override enjoyable remodel(enter: CharSequence): CharSequence =
phoneNumberFormatter.format(enter.toString())
override enjoyable isSeparator(char: Char): Boolean = !PhoneNumberUtils.isNonSeparator(char)

And bear in mind to restrict the entries in your textual content area, otherwise you’ll have a tough time:

TextField(
worth = cellphone,
onValueChange =  worth -> cellphone = worth.takeWhile  it.isDigit()  ,
visualTransformation = bear in mind  PhoneNumberVisualTransformation() 
)

I hope you may have realized one thing. I do know I did. And I do not need to should be taught it ever once more, so I wrote this text as a dev journal. Phew.

P.S.

For those who actually like all of the keen formatting and want this method to help enthusiastic offsets, you may do one thing like:

non-public enjoyable getOffsetFactor(enter: CharSequence, index: Int): Int 
if (!useEagerOffsets) 
return 1

val nextIndex = index + 1
val hasNext = nextIndex <= enter.lastIndex
val nextIsSeparator = hasNext && isSeparator(enter[nextIndex])
return if (nextIsSeparator) 2 else 1

move a flag within the generic displacement mapping:

summary class GenericSeparatorVisualTransformation(non-public val useEagerOffsets: Boolean = false) :
VisualTransformation

and do one thing like:

index
.takeIf  !isSeparator(c) 
// convert index to an offset
?.plus(getOffsetFactor(formatted, index))

However I kinda hate it, and I did not check it a lot, so your mileage might fluctuate.