dojox/string/BidiEngine (version 1.10)

Summary

This class provides a bidi transformation engine, i.e. functions for reordering and shaping bidi text.

Bidi stands for support for languages with a bidirectional script.

Usually Unicode Bidi Algorithm used by OS platform (and web browsers) is capable of properly transforming Bidi text and as a result it is adequately displayed on the screen. However, in some situations, Unicode Bidi Algorithm is not invoked or is not properly applied. This may occur in situation in which software responsible for rendering the text is not leveraging Unicode Bidi Algorithm implemented by OS (e.g. dojox.GFX renderers).

Bidi engine provided in this class implements Unicode Bidi Algorithm as specified at http://www.unicode.org/reports/tr9/.

For more information on basic Bidi concepts please read "Bidirectional script support - A primer" available from http://www.ibm.com/developerworks/websphere/library/techarticles/bidi/bidigen.html.

As of February 2011, Bidi engine has following limitations:

  1. No support for following numeric shaping options:
    • H - Hindi,
    • C - Contextual,
    • N - Nominal.
  2. No support for following shaping options:
    • I - Initial shaping,
    • M - Middle shaping,
    • F - Final shaping,
    • B - Isolated shaping.
  3. No support for source-to-target or/and target-to-source maps.
  4. No support for LRE/RLE/LRO/RLO/PDF (they are handled like neutrals).
  5. No support for Windows compatibility.
  6. No support for insert/remove marks.
  7. No support for code pages (currently only UTF-8 is supported. Ideally we should convert from any code page to UTF-8).

See the dojox/string/BidiEngine reference documentation for more information.

Method Summary

  • bidiTransform(text,formatIn,formatOut) Central public API for Bidi engine.
  • checkContextual(text) Determine the base direction of a bidi text according to its first strong directional character.
  • hasBidiChar(text) Return true if text contains RTL directed character.

Methods

bidiTransform(text,formatIn,formatOut)
Defined by dojox/string/BidiEngine

Central public API for Bidi engine. Transforms the text according to formatIn, formatOut parameters. If formatIn or formatOut parametrs are not valid throws an exception.

Both formatIn and formatOut parameters are 5 letters long strings. For example - "ILYNN". Each letter is associated with specific attribute of Bidi layout. Possible and default values for each one of the letters are provided below:

First letter:

  • Letter position/index: 1
  • Letter meaning: Ordering Schema.
  • Possible values:
    • I - Implicit (Logical).
    • V - Visual.
  • Default value: I

Second letter:

  • Letter position/index: 2
  • Letter meaning: Orientation.
  • Possible values:
    • L - Left To Right.
    • R - Right To Left.
    • C - Contextual Left to Right.
    • D - Contextual Right to Left.
  • Default value: L

Third letter:

  • Letter position/index: 3
  • Letter meaning: Symmetric Swapping.
  • Possible values:
    • Y - Symmetric swapping is on.
    • N - Symmetric swapping is off.
  • Default value: Y

Fourth letter:

  • Letter position/index: 4
  • Letter meaning: Shaping.
  • Possible values:
    • S - Text is shaped.
    • N - Text is not shaped.
  • Default value: N

Fifth letter:

  • Letter position/index: 5
  • Letter meaning: Numeric Shaping.
  • Possible values:
    • N - Nominal.
  • Default value: N

The output of this function is original text (passed via first argument) transformed from input Bidi layout (second argument) to output Bidi layout (last argument).

Sample call: 

mytext = bidiTransform("HELLO WORLD", "ILYNN", "VLYNN");

In this case, "HELLO WORLD" text is transformed from Logical - LTR to Visual - LTR Bidi layout with

default values for symmetric swapping (Yes), shaping (Not shaped) and numeric shaping (Nominal).

Parameter Type Description
text String
formatIn String

Input Bidi layout in which inputText is passed to the function.
formatOut String

Output Bidi layout to which inputText should be transformed.
Returns:String | string | undefined

Original text transformed from input Bidi layout (second argument) to output Bidi layout (last argument). Throws an exception if the bidi layout strings are not valid.

checkContextual(text)
Defined by dojox/string/BidiEngine

Determine the base direction of a bidi text according to its first strong directional character.

Parameter Type Description
text String

The text to check.
Returns:any | string

/String/ "ltr" or "rtl" according to the first strong character. If there is no strong character, returns the value of the document dir property.

hasBidiChar(text)
Defined by dojox/string/BidiEngine

Return true if text contains RTL directed character.

Iterates over the text string, letter by letter starting from its beginning, searching for RTL directed character. Return true if found else false. Needed for vml transformation.

Parameter Type Description
text String

The source string.
Returns:any | boolean

/Boolean/ true - if text has a RTL directed character. false - otherwise.

Error in the documentation? Can’t find what you are looking for? Let us know!