Modify the operation of the Bidi algorithm such that it implements some
variant to the basic Bidi algorithm or approximates an "inverse Bidi"
algorithm, depending on different values of the "reordering mode".
This method must be called before
setPara()
, and stays in
effect until called again with a different argument.
The normal operation of the Bidi algorithm as described in the Unicode
Standard Annex #9 is to take text stored in logical (keyboard, typing)
order and to determine how to reorder it for visual rendering.
With the reordering mode set to a value other than
REORDER_DEFAULT
, this method changes the behavior of some of
the subsequent methods in a way such that they implement an inverse Bidi
algorithm or some other algorithm variants.
Some legacy systems store text in visual order, and for operations
with standard, Unicode-based algorithms, the text needs to be transformed
into logical order. This is effectively the inverse algorithm of the
described Bidi algorithm. Note that there is no standard algorithm for
this "inverse Bidi", so a number of variants are implemented here.
In other cases, it may be desirable to emulate some variant of the
Logical to Visual algorithm (e.g. one used in MS Windows), or perform a
Logical to Logical transformation.
- When the Reordering Mode is set to
REORDER_DEFAULT
,
the standard Bidi Logical to Visual algorithm is applied.
- When the reordering mode is set to
REORDER_NUMBERS_SPECIAL
,
the algorithm used to perform Bidi transformations when calling
setPara
should approximate the algorithm used in Microsoft
Windows XP rather than strictly conform to the Unicode Bidi algorithm.
The differences between the basic algorithm and the algorithm addressed
by this option are as follows:
- Within text at an even embedding level, the sequence "123AB"
(where AB represent R or AL letters) is transformed to "123BA" by the
Unicode algorithm and to "BA123" by the Windows algorithm.
- Arabic-Indic numbers (AN) are handled by the Windows algorithm just
like regular numbers (EN).
- When the reordering mode is set to
REORDER_GROUP_NUMBERS_WITH_R
,
numbers located between LTR text and RTL text are associated with the RTL
text. For instance, an LTR paragraph with content "abc 123 DEF" (where
upper case letters represent RTL characters) will be transformed to
"abc FED 123" (and not "abc 123 FED"), "DEF 123 abc" will be transformed
to "123 FED abc" and "123 FED abc" will be transformed to "DEF 123 abc".
This makes the algorithm reversible and makes it useful when round trip
(from visual to logical and back to visual) must be achieved without
adding LRM characters. However, this is a variation from the standard
Unicode Bidi algorithm.
The source text should not contain Bidi control characters other than LRM
or RLM.
- When the reordering mode is set to
REORDER_RUNS_ONLY
,
a "Logical to Logical" transformation must be performed:
- If the default text level of the source text (argument
paraLevel
in setPara
) is even, the source text
will be handled as LTR logical text and will be transformed to the RTL
logical text which has the same LTR visual display.
- If the default level of the source text is odd, the source text
will be handled as RTL logical text and will be transformed to the
LTR logical text which has the same LTR visual display.
This mode may be needed when logical text which is basically Arabic or
Hebrew, with possible included numbers or phrases in English, has to be
displayed as if it had an even embedding level (this can happen if the
displaying application treats all text as if it was basically LTR).
This mode may also be needed in the reverse case, when logical text which
is basically English, with possible included phrases in Arabic or Hebrew,
has to be displayed as if it had an odd embedding level.
Both cases could be handled by adding LRE or RLE at the head of the
text, if the display subsystem supports these formatting controls. If it
does not, the problem may be handled by transforming the source text in
this mode before displaying it, so that it will be displayed properly.
The source text should not contain Bidi control characters other than LRM
or RLM.
- When the reordering mode is set to
REORDER_INVERSE_NUMBERS_AS_L
, an "inverse Bidi"
algorithm is applied.
Runs of text with numeric characters will be treated like LTR letters and
may need to be surrounded with LRM characters when they are written in
reordered sequence (the option INSERT_LRM_FOR_NUMERIC
can
be used with method writeReordered
to this end. This mode
is equivalent to calling setInverse()
with
argument isInverse
set to true
.
- When the reordering mode is set to
REORDER_INVERSE_LIKE_DIRECT
, the "direct" Logical to
Visual Bidi algorithm is used as an approximation of an "inverse Bidi"
algorithm. This mode is similar to mode
REORDER_INVERSE_NUMBERS_AS_L
but is closer to the
regular Bidi algorithm.
For example, an LTR paragraph with the content "FED 123 456 CBA" (where
upper case represents RTL characters) will be transformed to
"ABC 456 123 DEF", as opposed to "DEF 123 456 ABC"
with mode REORDER_INVERSE_NUMBERS_AS_L
.
When used in conjunction with option
OPTION_INSERT_MARKS
, this mode generally
adds Bidi marks to the output significantly more sparingly than mode
REORDER_INVERSE_NUMBERS_AS_L
.
with option
INSERT_LRM_FOR_NUMERIC
in calls to
writeReordered
.
- When the reordering mode is set to
REORDER_INVERSE_FOR_NUMBERS_SPECIAL
, the Logical to Visual
Bidi algorithm used in Windows XP is used as an approximation of an "inverse
Bidi" algorithm.
For example, an LTR paragraph with the content "abc FED123" (where
upper case represents RTL characters) will be transformed to
"abc 123DEF.
In all the reordering modes specifying an "inverse Bidi" algorithm
(i.e. those with a name starting with REORDER_INVERSE
),
output runs should be retrieved using getVisualRun()
, and
the output text with writeReordered()
. The caller should
keep in mind that in "inverse Bidi" modes the input is actually visually
ordered text and reordered output returned by getVisualRun()
or writeReordered()
are actually runs or character string
of logically ordered output.
For all the "inverse Bidi" modes, the source text should not contain
Bidi control characters other than LRM or RLM.
Note that option OUTPUT_REVERSE
of
writeReordered
has no useful meaning and should not be used
in conjunction with any value of the reordering mode specifying "inverse
Bidi" or with value REORDER_RUNS_ONLY
.