BidiFormatter

class BidiFormatter
kotlin.Any
   ↳ android.text.BidiFormatter

Utility class for formatting text for display in a potentially opposite-directionality context without garbling. The directionality of the context is set at formatter creation and the directionality of the text can be either estimated or passed in when known.

To support versions lower than android.os.Build.VERSION_CODES#JELLY_BEAN_MR2, you can use the support library's android.support.v4.text.BidiFormatter class.

These APIs provides the following functionality:

1. Bidi Wrapping When text in one language is mixed into a document in another, opposite-directionality language, e.g. when an English business name is embedded in some Hebrew text, both the inserted string and the text surrounding it may be displayed incorrectly unless the inserted string is explicitly separated from the surrounding text in a "wrapper" that:

- Declares its directionality so that the string is displayed correctly. This can be done in Unicode bidi formatting codes by #unicodeWrap and similar methods.

- Isolates the string's directionality, so it does not unduly affect the surrounding content. Currently, this can only be done using invisible Unicode characters of the same direction as the context (LRM or RLM) in addition to the directionality declaration above, thus "resetting" the directionality to that of the context. The "reset" may need to be done at both ends of the string. Without "reset" after the string, the string will "stick" to a number or logically separate opposite-direction text that happens to follow it in-line (even if separated by neutral content like spaces and punctuation). Without "reset" before the string, the same can happen there, but only with more opposite-direction text, not a number. One approach is to "reset" the direction only after each string, on the theory that if the preceding opposite- direction text is itself bidi-wrapped, the "reset" after it will prevent the sticking. (Doing the "reset" only before each string definitely does not work because we do not want to require bidi-wrapping numbers, and a bidi-wrapped opposite-direction string could be followed by a number.) Still, the safest policy is to do the "reset" on both ends of each string, since RTL message translations often contain untranslated Latin-script brand names and technical terms, and one of these can be followed by a bidi-wrapped inserted value. On the other hand, when one has such a message, it is best to do the "reset" manually in the message translation itself, since the message's opposite-direction text could be followed by an inserted number, which we would not bidi-wrap anyway. Thus, "reset" only after the string is the current default. In an alternative to "reset", recent additions to the HTML, CSS, and Unicode standards allow the isolation to be part of the directionality declaration. This form of isolation is better than "reset" because it takes less space, does not require knowing the context directionality, has a gentler effect than "reset", and protects both ends of the string. However, we do not yet allow using it because required platforms do not yet support it.

Providing these wrapping services is the basic purpose of the bidi formatter.

2. Directionality estimation How does one know whether a string about to be inserted into surrounding text has the same directionality? Well, in many cases, one knows that this must be the case when writing the code doing the insertion, e.g. when a localized message is inserted into a localized page. In such cases there is no need to involve the bidi formatter at all. In some other cases, it need not be the same as the context, but is either constant (e.g. urls are always LTR) or otherwise known. In the remaining cases, e.g. when the string is user-entered or comes from a database, the language of the string (and thus its directionality) is not known a priori, and must be estimated at run-time. The bidi formatter can do this automatically using the default first-strong estimation algorithm. It can also be configured to use a custom directionality estimation object.
Requires API level 18 (Android 4.3, Jelly Bean)

Summary

Nested classes

A class for building a BidiFormatter with non-default options.

Public methods
Boolean
isRtl(str: String!)

Estimates the directionality of a string using the default text direction heuristic.

Boolean

Operates like #isRtl(String), but takes a CharSequence instead of a string
Requires API level 26 (Android 8.0, Oreo)

Boolean


Requires API level 18 (Android 4.3, Jelly Bean)

Boolean


Requires API level 18 (Android 4.3, Jelly Bean)

String?
unicodeWrap(str: String?, heuristic: TextDirectionHeuristic!, isolate: Boolean)

Formats a string of given directionality for use in plain-text output of the context directionality, so an opposite-directionality string is neither garbled nor garbles its surroundings.

CharSequence?
unicodeWrap(str: CharSequence?, heuristic: TextDirectionHeuristic!, isolate: Boolean)

Operates like #unicodeWrap(String, TextDirectionHeuristic, boolean), but takes a CharSequence instead of a string
Requires API level 26 (Android 8.0, Oreo)

String!

Operates like #unicodeWrap(String, TextDirectionHeuristic, boolean), but assumes isolate is true.

CharSequence!

Operates like #unicodeWrap(CharSequence, TextDirectionHeuristic, boolean), but assumes isolate is true.

String!
unicodeWrap(str: String!, isolate: Boolean)

Operates like #unicodeWrap(String, TextDirectionHeuristic, boolean), but uses the formatter's default direction estimation algorithm.

CharSequence!
unicodeWrap(str: CharSequence!, isolate: Boolean)

Operates like #unicodeWrap(CharSequence, TextDirectionHeuristic, boolean), but uses the formatter's default direction estimation algorithm.

String!

Operates like #unicodeWrap(String, TextDirectionHeuristic, boolean), but uses the formatter's default direction estimation algorithm and assumes isolate is true.

CharSequence!

Operates like #unicodeWrap(CharSequence, TextDirectionHeuristic, boolean), but uses the formatter's default direction estimation algorithm and assumes isolate is true.

static BidiFormatter!

Factory for creating an instance of BidiFormatter for the default locale directionality.

static BidiFormatter!
getInstance(rtlContext: Boolean)

Factory for creating an instance of BidiFormatter given the context directionality.

static BidiFormatter!
getInstance(locale: Locale!)

Factory for creating an instance of BidiFormatter given the context locale.

Public methods

isRtl

added in API level 18
fun isRtl(str: String!): Boolean

Estimates the directionality of a string using the default text direction heuristic.
Requires API level 18 (Android 4.3, Jelly Bean)

Parameters
str String!: String whose directionality is to be estimated.
Return
Boolean: true if str's estimated overall directionality is RTL. Otherwise returns false.

isRtl

added in API level 26
fun isRtl(str: CharSequence!): Boolean

Operates like #isRtl(String), but takes a CharSequence instead of a string
Requires API level 26 (Android 8.0, Oreo)

Parameters
str CharSequence!: CharSequence whose directionality is to be estimated.
Return
Boolean: true if str's estimated overall directionality is RTL. Otherwise returns false.

isRtlContext

added in API level 18
fun isRtlContext(): Boolean


Requires API level 18 (Android 4.3, Jelly Bean)

Return
Boolean: Whether the context directionality is RTL

getStereoReset

added in API level 18
fun getStereoReset(): Boolean


Requires API level 18 (Android 4.3, Jelly Bean)

Return
Boolean: Whether directionality "reset" should also be done before a string being bidi-wrapped, not just after it.

unicodeWrap

added in API level 18
fun unicodeWrap(str: String?, heuristic: TextDirectionHeuristic!, isolate: Boolean): String?

Formats a string of given directionality for use in plain-text output of the context directionality, so an opposite-directionality string is neither garbled nor garbles its surroundings. This makes use of Unicode bidi formatting characters.

The algorithm: In case the given directionality doesn't match the context directionality, wraps the string with Unicode bidi formatting characters: RLE+str+PDF for RTL text, or LRE+str+PDF for LTR text.

If isolate, directionally isolates the string so that it does not garble its surroundings. Currently, this is done by "resetting" the directionality after the string by appending a trailing Unicode bidi mark matching the context directionality (LRM or RLM) when either the overall directionality or the exit directionality of the string is opposite to that of the context. Unless the formatter was built using Builder#stereoReset(boolean) with a false argument, also prepends a Unicode bidi mark matching the context directionality when either the overall directionality or the entry directionality of the string is opposite to that of the context. Note that as opposed to the overall directionality, the entry and exit directionalities are determined from the string itself.

Does *not* do HTML-escaping.
Requires API level 18 (Android 4.3, Jelly Bean)

Parameters
str String?: The input string. This value may be null.
heuristic String?: The algorithm to be used to estimate the string's overall direction. See TextDirectionHeuristics for pre-defined heuristics.
isolate String?: Whether to directionally isolate the string to prevent it from garbling the content around it
Return
String?: Input string after applying the above processing. null if str is null.

unicodeWrap

added in API level 26
fun unicodeWrap(str: CharSequence?, heuristic: TextDirectionHeuristic!, isolate: Boolean): CharSequence?

Operates like #unicodeWrap(String, TextDirectionHeuristic, boolean), but takes a CharSequence instead of a string
Requires API level 26 (Android 8.0, Oreo)

Parameters
str CharSequence?: The input CharSequence. This value may be null.
heuristic CharSequence?: The algorithm to be used to estimate the CharSequence's overall direction. See TextDirectionHeuristics for pre-defined heuristics.
isolate CharSequence?: Whether to directionally isolate the CharSequence to prevent it from garbling the content around it
Return
CharSequence?: Input CharSequence after applying the above processing. null if str is null.

unicodeWrap

added in API level 18
fun unicodeWrap(str: String!, heuristic: TextDirectionHeuristic!): String!

Operates like #unicodeWrap(String, TextDirectionHeuristic, boolean), but assumes isolate is true.
Requires API level 18 (Android 4.3, Jelly Bean)

Parameters
str String!: The input string.
heuristic String!: The algorithm to be used to estimate the string's overall direction. See TextDirectionHeuristics for pre-defined heuristics.
Return
String!: Input string after applying the above processing.

unicodeWrap

added in API level 26
fun unicodeWrap(str: CharSequence!, heuristic: TextDirectionHeuristic!): CharSequence!

Operates like #unicodeWrap(CharSequence, TextDirectionHeuristic, boolean), but assumes isolate is true.
Requires API level 26 (Android 8.0, Oreo)

Parameters
str CharSequence!: The input CharSequence.
heuristic CharSequence!: The algorithm to be used to estimate the CharSequence's overall direction. See TextDirectionHeuristics for pre-defined heuristics.
Return
CharSequence!: Input CharSequence after applying the above processing.

unicodeWrap

added in API level 18
fun unicodeWrap(str: String!, isolate: Boolean): String!

Operates like #unicodeWrap(String, TextDirectionHeuristic, boolean), but uses the formatter's default direction estimation algorithm.
Requires API level 18 (Android 4.3, Jelly Bean)

Parameters
str String!: The input string.
isolate String!: Whether to directionally isolate the string to prevent it from garbling the content around it
Return
String!: Input string after applying the above processing.

unicodeWrap

added in API level 26
fun unicodeWrap(str: CharSequence!, isolate: Boolean): CharSequence!

Operates like #unicodeWrap(CharSequence, TextDirectionHeuristic, boolean), but uses the formatter's default direction estimation algorithm.
Requires API level 26 (Android 8.0, Oreo)

Parameters
str CharSequence!: The input CharSequence.
isolate CharSequence!: Whether to directionally isolate the CharSequence to prevent it from garbling the content around it
Return
CharSequence!: Input CharSequence after applying the above processing.

unicodeWrap

added in API level 18
fun unicodeWrap(str: String!): String!

Operates like #unicodeWrap(String, TextDirectionHeuristic, boolean), but uses the formatter's default direction estimation algorithm and assumes isolate is true.
Requires API level 18 (Android 4.3, Jelly Bean)

Parameters
str String!: The input string.
Return
String!: Input string after applying the above processing.

unicodeWrap

added in API level 26
fun unicodeWrap(str: CharSequence!): CharSequence!

Operates like #unicodeWrap(CharSequence, TextDirectionHeuristic, boolean), but uses the formatter's default direction estimation algorithm and assumes isolate is true.
Requires API level 26 (Android 8.0, Oreo)

Parameters
str CharSequence!: The input CharSequence.
Return
CharSequence!: Input CharSequence after applying the above processing.

getInstance

added in API level 18
static fun getInstance(): BidiFormatter!

Factory for creating an instance of BidiFormatter for the default locale directionality. This does not create any new objects, and returns already existing static instances.
Requires API level 18 (Android 4.3, Jelly Bean)

getInstance

added in API level 18
static fun getInstance(rtlContext: Boolean): BidiFormatter!

Factory for creating an instance of BidiFormatter given the context directionality. This does not create any new objects, and returns already existing static instances.
Requires API level 18 (Android 4.3, Jelly Bean)

Parameters
rtlContext Boolean: Whether the context directionality is RTL.

getInstance

added in API level 18
static fun getInstance(locale: Locale!): BidiFormatter!

Factory for creating an instance of BidiFormatter given the context locale. This does not create any new objects, and returns already existing static instances.
Requires API level 18 (Android 4.3, Jelly Bean)

Parameters
locale Locale!: The context locale.