Describes the concepts and values of base text direction and how it can be changed interactively in an application.

Describes concepts essential to understanding base text direction.

Bidirectional character type

The Unicode standard assigns to each character its own invariant bidirectional character type.

See http://www.unicode.org/reports/tr9/#Bidirectional_Character_Types.

Strong directional character

Strong directional characters have their own predefined reading direction and can affect the reading direction of neighboring characters.

Characters with the left-to-right, right-to-left, and right-to-left Arabic types are called ““strong directional””, or just ““strong”” characters.

The reading direction of characters that are not ““strong”” depends on their context.

Numbers are a special case; their reading direction is always left to right, but they do not affect the reading direction of neighboring characters. Even numbers that are displayed with Arabic-Indic digits have a left-to-right character direction.

Directional run

Bidirectional text, as its name implies, can contain segments that are read from right to left and segments that are read from left to right.

The following example shows a right-to-left sentence with a mixture of right-to-left words in Arabic, Hebrew, Urdu, and so on, and left-to-right words, for example, in English. Uppercase letters represent letters in Arabic or Hebrew script. The example sentence contains five directional runs.

In the example sentence:

This mixing of different directional runs in the text sequence is called bidirectional text.

A directional run delimits a sequence of adjacent characters that are read in the same direction; it is the formal term for what was earlier referred to as a ““segment””.

Character direction

Character direction refers to the effective reading direction of specific occurrences of characters.

The effective direction can be affected by the context of specific occurrences of characters. Character direction is fixed for strong characters and for digits. For other types of characters, character direction depends on the context. Character direction corresponds to the reading order of letters in words. Character direction is uniform within a directional run. It should not be confused with base text direction.

Base text direction

Base text direction refers to the order in which directional runs are laid out in a sentence.

For left-to-right sentences, for example, in English, the proper base text direction is Left To Right (LTR), even if a sentence includes Arabic, Hebrew, Urdu, or Farsi words. For right-to-left sentences, for example, in Arabic or Hebrew, the proper base text direction is Right To Left (RTL), even if a sentence includes English words or numbers.

Determining whether a sentence is, for example, English or Arabic, is not always easy. Examine the example sentence in Directional run. This sentence is an Arabic and Hebrew sentence and therefore has a right-to-left base text direction. The directional runs must be laid out on the line one after the other from right to left. The following example shows each directional run enclosed in square brackets.

Consecutive English words form a left-to-right directional run even when they are embedded in an Arabic, Hebrew, or Urdu sentence. Consecutive Arabic or Hebrew words form a right-to-left directional run, even when embedded in an English sentence. The ordering of successive directional runs depends on the value of the base text direction.

The natural text direction of a language, right to left for Arabic, Hebrew, or Urdu and left to right for English, is inherent in the script used to write the text and is independent of the component direction, which is handled by the GUI mirroring mode, and of the user locale. Even if the GUI of a product is not mirrored, bidirectional text entered by the user of an application, that is, bidirectional text that the user directly or indirectly introduces and sees through a product’s GUI, should be displayed according to its natural base text direction. The user should have control over document and paragraph base text direction independently of the component direction (GUI mirroring mode).

The base text direction of bidirectional text affects its display. Consider how the string hello world !, listed in logical order, that is, the order in which the text is pronounced, is displayed when its base text direction is changed.

With left-to-right base text direction, the string is displayed:

With right-to-left base text direction, the same string is displayed:

In the example of right-to-left base text direction the exclamation mark (!) appears on the left side of the string.

The string is not displayed as ““! world hello”” when the base text direction is right to left. Even though the base text direction is right to left, consecutive English words always constitute a left-to-right directional run, so that each word is displayed left to right and the progression of words in the run is also left to right.

The following values describe base text direction:

LTR

Left-To-Right base text direction, which is the natural base text direction of most languages, including European, Asian, and Indic languages, with possible embedded runs of the opposite direction. For example:

RTL

Right-To-Left base text direction, which is the natural base text direction for languages such as Arabic, Hebrew, Urdu, and Farsi, with possible embedded runs of the opposite direction. For example:

Contextual-RTL or Contextual-LTR

The base text direction is set according to the first strong character. This choice is appropriate when the main language of the string is not known at the time of setting the base direction.

If you know in advance that a GUI component will always display Hebrew or Arabic text, the base text direction for its content can safely be set to RTL. If it is known that it will always display English or Italian text, the base direction can safely be set to LTR.

You might not have such knowledge in advance. This information might only become available when the content is dynamically generated at run time, for example, by retrieving data from a database or because the user creates the data on the spot by selecting from a list or by keyboard entry. The contextual specifications are intended for such cases; the actual direction of the text for the current occurrence is set according to the analysis of the data by a given algorithm. The algorithm is described by the Unicode organization. See http://www.unicode.org/reports/tr9/#The_Paragraph_Level.

This Unicode documentation broadly indicates that if data contains letters from RTL scripts and no letters from an LTR script, the direction will be RTL. If the data contains letters from LTR scripts and no letters from an RTL script, the direction will be LTR. If the data contains characters of both types (RTL and LTR), then the first strong directional character in logical order will determine the direction.

If the data contains no letter from either LTR or RTL type in the text, which could happen, for example, in purely numeric content, a default must be set. This default should preferably be set by the author of the code and is the reason why two contextual values exist (Contextual-LTR and Contextual-RTL).

These two values give exactly the same results if the data contains at least one LTR or RTL letter; that is, if text includes at least one strong LTR or strong RTL character, the resulting display will be the same for Contextual-LTR or Contextual-RTL.

Only when there is no such letter do the results differ; Contextual-LTR resolves to LTR and Contextual-RTL resolves to RTL. The following example shows text where the display is different for Contextual-LTR and Contextual-RTL.

In logical order:

Contextual-LTR display order:

Contextual-RTL display order:

The less than sign (<) is mirrored in the display order of Contextual-RTL.

When contextual direction is selected for a GUI component, Contextual-LTR should be the default for an LTR-oriented (unmirrored) GUI and Contextual-RTL should be the default for an RTL-oriented (mirrored) GUI.

JViews provides the following constants to support base text direction.

INHERITED_DIRECTION

Implicit value: the default value that is assigned to every Java framework object that displays text. The actual value is looked up on the higher levels of the JViews object hierarchy (up to the root object). If no explicit value is found, the value COMPONENT_DIRECTION is used. If this value is assigned to an object without a parent, the value COMPONENT_DIRECTION is used.

COMPONENT_DIRECTION

Explicit value: the text direction follows the GUI direction (called ““component orientation ”” in the Java world). For a mirrored GUI, it will be RTL; for a GUI that is not mirrored, it will be LTR. The default contextual base text direction in the static context of Java controls is neutralized.

LEFT_TO_RIGHT

Explicit value: base text direction is Left To Right.

RIGHT_TO_LEFT

Explicit value: base text direction is Right To Left.

CONTEXTUAL_DIRECTION

Explicit value: contextual base text direction. For strings starting from Left To RIight strong characters, it is resolved to LTR base text direction; for strings starting from Right To Left strong characters, it is resolved to RTL base text direction.

If the string does not include any strong characters, the behavior is the same as the behavior for text direction set to COMPONENT_DIRECTION.

Namely:

JViews rich client provides controls to support different types of editing. The editing described in this topic is performed by the user of an application and not by its developer.

The user can edit by in-place editing or by Swing or AWT controls. The following figure illustrates in-place editing and shows the presence of the cursor.

The following figure shows editing in static mode by Swing or AWT controls.

The following figure shows editing in editing mode by Swing or AWT controls.

For controls that support editing mode, either in-place editing or editing based on Swing or AWT input field, the user has the following options to change base text direction in this specific control instance:

This level of user control overrides the base text direction set during configuration or by API. It takes precedence over any other setting. The new value is applied immediately and thus is also reflected in the display.

Enforcement of base text direction is enabled by default in JViews. JViews supports a fallback mechanism that can be used by customers who are not interested in bidi support or want to minimize the opportunities of invoking it. This mechanism disables bidi support. This mechanism does not enable dynamic control over calling bidi support at run time. Bidi support must be enabled or disabled at the start of the program and this bidi status should not change during the subsequent run time.

You can disable bidi support in one of the following ways:

If you want to use bidi support, you have no enabling action to take, because bidi support is enabled by default in JViews.

In JViews rich client, public Java API can be used for controlling the base text direction of JViews graphic objects. Usually instances of the IlvGraphic class or its subclasses are used to implement this control. Some exceptions exist.

You can use the following methods to control base text direction:

This section applies to JViews rich client.

If the custom graphic object is a primitive (not a container) and does not have any text, then nothing is required.

Where the custom graphic object has some text or it is a container including child objects that have text, two approaches are available.

By methods of IlvBaseTextDirectionInterface

This functionality is the minimum required for objects that are not subclasses of IlvGraphic. All IlvGraphic objects implement this interface as well. Any container that displays text should implement IlvBaseTextDirectionInterface.

This interface defines the following methods:

Implementation of these methods from scratch requires in depth understanding of the logic and mechanism of control over base text direction in JViews. If such knowledge is not available, a simpler approach can be used. See By subclasses of IlvGraphic.

By subclasses of IlvGraphic

The public methods mentioned in By methods of IlvBaseTextDirectionInterface and some additional ones used for handling base text direction are available in the class IlvGraphic. To control base text direction in a custom graphic object, you can extend this class to use the bidi functionality already implemented in it. The easiest way to do so is by taking as base class IlvBidiGraphic, which contains the full implementations of all methods of IlvBaseTextDirectionInterface.

Subclasses of IlvBidiGraphic should implement:

If you cannot use IlvBidiGraphic as base class, then you can subclass IlvGraphic directly.

You must implement more methods, because IlvGraphic contains only empty or partial implementations:

Override the other methods already mentioned for IlvBidiGraphic. (See the methods listed under [no title] for details.

Rendering

Whichever approach you take (IlvBaseTextDirectionInterface methods or subclasses of IlvGraphic), when text is rendered you must enforce its real base text direction.

JViews provides for the following techniques:

At the map level

No Java classes specific to maps exist for controlling base text direction at the map level. The manager in JViews Framework can be used to control base text direction at this level. You can use this class to set base text direction for the entire map, including the layers. For example:

If all text objects, labels, and annotation have base text direction DIRECTION_INHERITED, this class enables the base text direction to be dynamically changed uniformly for all these objects on all layers of the map. All such text-related objects inherit the same base text direction, which is assigned to the top level programmatically, with similar code to the example Setting base text direction by IlvManager.

At the layer level

Base text direction in JViews Maps is defined as an attribute of map layer style and can be changed individually for each layer. For example:

Base text direction: suitable JViews Maps components

Specifying base text direction for a specific component has the highest priority. Only when base text direction is defined on a specific component as DIRECTION_INHERITED is the value from a higher level used.

 

Enabling dynamic change at run time

You can set base text direction dynamically to have the same value for all text elements of a map or to assign one specific base text direction value to a specific text element of a map.

Dynamically setting a consistent base text direction for all text elements

Setting any of the following values for base text direction in any text-related elements of map layers, including text data objects, data object labels, annotation labels, and labels of grid objects, is an explicit or static assignment:

The only external factor that can affect these settings on a given element is a call to the Java API.

Setting base text direction to one of the following values means that base text direction can be affected by external influences at run time:

Inherited

For example, change of the base specification in the map where the text element is embedded affects the value of the base text direction of text elements in the map.

Component Orientation

For example, change of GUI direction for the container in which the map is embedded affects the base text direction of text elements in the map.

By such a change at run time you can dynamically affect the base text direction in a consistent way for all text elements contained in the map.

For such a dynamic run time change, the following conditions must be satisfied:

Dynamically assigning one specific base text direction value to a specific text element

The lowest level on which base text direction can be specified is the layer. The following example shows how to assign a specific base text direction value for the layer:

At the Diagram level

The default base text direction of the diagram can be set programmatically by changing the property of the current instance. For example:

The same result can be achieved by adding the code for the following selector to the CSS file attached to the Diagram component:

Or you can set the base text direction property of IlvStyleSheetRenderer. Add the code for the following selector to the CSS file:

At the Node level

You can set base text direction for graphic implementation of a specific node or types of nodes to a constant value, for example, Right To Left:

Alternatively, it can be defined by reference to a property. Place baseTextDirection style into the selector that describes such a node or nodes. For example:

Assuming that the property baseTextDirectionProperty is referenced in CSS (see @baseTextDirectionProperty in the example), you can dynamically change base text direction in the selected node or nodes by using the following Java code:

At the Link level

You can set base text direction for graphic implementation of a specific link or types of links to a constant value, for example, Right To Left:

Then, it can be defined by reference to a property; Place baseTextDirection style into the selector that describes such a link or links For example:

Assuming that the property baseTextDirectionProperty is referenced in CSS (see @baseTextDirectionProperty in the example), you can dynamically change base text direction in the selected link or links by using the following Java code:

In the property sheet

You can set base text direction for specific cells of the property sheet. The definition can be static by assigning a constant value or dynamic by assigning a reference to a property. For example, to define base text direction in the property sheet dynamically:

If the property sheet can be edited, you can use a special property editor to edit base text direction. For example:

In the IlvDiagrammer table

You can set base text direction for a specific cell of an IlvDiagrammerTable object. The definition can be static by assigning a constant value or dynamic by assigning a reference to a property. For example, to define base text direction in the IlvDiagrammerTable dynamically:

Base text direction: suitable JViews Diagrammer components

Specifying base text direction for a specific component has the highest priority. Only when base text direction is defined on a specific component as DIRECTION_INHERITED is the value from a higher level used.

 

Enabling dynamic change at run time

You can set base text direction dynamically to have the same value for all text elements of an IlvDiagrammer object or to assign one specific base text direction value to a specific text element of the IlvDiagrammer object.

Dynamically setting a consistent base text direction for all text elements

Setting any of the following values for base text direction in any JViews Diagrammer components (node, link, property sheet, table) is an explicit or static assignment:

The only external factor that can affect these settings on a given component is a call to the Java API.

Setting base text direction to one of the following values means that base text direction can be affected by external influences at run time:

Inherited

For example, change of the base specification in the IlvDiagrammer object in which the text element is embedded affects the value of the base text direction of text elements in the IlvDiagrammer instance.

Component Orientation

For example, change of GUI direction for the container in which the diagram is embedded affects the base text direction of text elements in the diagram.

By such a change at run time you can dynamically affect the base text direction in a consistent way for all text elements contained in the IlvDiagrammer object.

For such a dynamic run time change, the following conditions must be satisfied:

Dynamically assigning one specific base text direction value to a specific text element

You can dynamically assign one specific base text direction value to a specific text element of the IlvDiagrammer object by using the Designer. See Assigning one specific value to a specific text element of an IlvDiagrammer object.

Then, you can implement the setting dynamically at run time by the following code:

where:

linkObj

An instance of the link that contains the Text element.

“myBaseTextDirection”

Name of the parameter added to the link object and identified in the expression that is referenced by the baseTextDirection property; in this example, myBaseTextDirection.

IlvBidiUtil.RIGHT_TO_LEFT

One of the valid values of base text direction.