Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "New Bidi APIs"
| (4 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | In Eclipse 3.2, new APIs were added to provide proper rendering of strings containing bidirectional text that have implicit left to right semantic meaning. | + | During the Eclipse 3.2 development and testing cycles, specifically in the bidirectional languages (Arabic and Hebrew), it was discovered that a number of strings containing bidirctional text were not rendering properly. The two common threads amongst the problematic strings were that the string should display overall in a left-to-right (LTR) orientation (which goes against normal rendering algorithms on bidirectional platforms) or they contained neutral characters that were bounded with RTL-oriented text on one side and LTR-oriented text on the other side, which made for seemingly unpredictable rendering results. |
| − | The method <strong>org.eclipse.osgi.util.TextProcessor.process(String str, String delimiter)</strong> provides this function. | + | |
| + | <br> | ||
| + | In Eclipse 3.2, new APIs were added to provide proper rendering of strings containing bidirectional text that have implicit left-to-right semantic meaning. The method <strong>org.eclipse.osgi.util.TextProcessor.process(String str, String delimiter)</strong> provides this function. | ||
;str : the string to process | ;str : the string to process | ||
;delimiter : a string of characters used to segment the string. | ;delimiter : a string of characters used to segment the string. | ||
| + | <br> | ||
The text of each segment has directional markers inserted at the beginning and end of it to ensure the entire string is rendered left-to-right and also has the Unicode [http://www.unicode.org/reports/tr9/ Bidirectional algorithm] applied to it in order to render the mixed text of the segment in the proper orientation. | The text of each segment has directional markers inserted at the beginning and end of it to ensure the entire string is rendered left-to-right and also has the Unicode [http://www.unicode.org/reports/tr9/ Bidirectional algorithm] applied to it in order to render the mixed text of the segment in the proper orientation. | ||
| Line 10: | Line 13: | ||
d:\myFolder\REDLOF\ELIFYM.java | d:\myFolder\REDLOF\ELIFYM.java | ||
when using the Unicode Bidi algorithm and segmenting the string according to a specified delimiter set. | when using the Unicode Bidi algorithm and segmenting the string according to a specified delimiter set. | ||
| − | However, since the OS does not understand that the string should be segmented according to each segment of the file path, it | + | <br>However, since the OS does not understand that the string should be segmented according to each segment of the file path, it renders the string as |
java.ELIFYM\REDLOF\d:\myFolder | java.ELIFYM\REDLOF\d:\myFolder | ||
| Line 18: | Line 21: | ||
#File names with extensions (e.g. ABC.java) | #File names with extensions (e.g. ABC.java) | ||
#File associations (e.g. *.java, *.ABC) | #File associations (e.g. *.java, *.ABC) | ||
| + | <br> | ||
| + | To use the API, determine what delimiter characters should be used to segment the string, then simply call | ||
| + | TextProcessor.process(string, delimiter); | ||
| + | |||
| + | <strong>Example 1</strong><br> | ||
| + | The delimiter string for a file path would be "/\:." to account for volume separator (:), path separators (/ and \) and file extension separator (.). | ||
| + | |||
| + | <strong>Example 2</strong><br> | ||
| + | The delimiter string for a URL would be ":/". | ||
| + | |||
| + | <br> | ||
| + | <strong>Note</strong> that the <strong>TextProcessor#process</strong> methods should only be called on strings that are to be displayed in the user interface (UI), as the length of the string will increase when the directional markers are inserted. The directional markers are only inserted in the string when Eclipse is running in a bidirectinal locale (Arabic or Hebrew). | ||
| + | |||
| + | <br> | ||
| + | The Eclipse Platform has begun to use this API in the Eclipse 3.3 development stream. Examples of places where it is currently being used are the Info property page (for paths), the Properties view (for paths and file names with extensions), and the Navigator view (also for file names with extensions). | ||
| − | + | <br> | |
| + | It has been suggested that APIs be provided for the most common usages so that users won't have to figure out for themselves the most common usages of this API - watch [https://bugs.eclipse.org/bugs/show_bug.cgi?id=146220 bug 146220] for progress on this issue. | ||
Latest revision as of 09:56, 19 June 2006
During the Eclipse 3.2 development and testing cycles, specifically in the bidirectional languages (Arabic and Hebrew), it was discovered that a number of strings containing bidirctional text were not rendering properly. The two common threads amongst the problematic strings were that the string should display overall in a left-to-right (LTR) orientation (which goes against normal rendering algorithms on bidirectional platforms) or they contained neutral characters that were bounded with RTL-oriented text on one side and LTR-oriented text on the other side, which made for seemingly unpredictable rendering results.
In Eclipse 3.2, new APIs were added to provide proper rendering of strings containing bidirectional text that have implicit left-to-right semantic meaning. The method org.eclipse.osgi.util.TextProcessor.process(String str, String delimiter) provides this function.
- str
- the string to process
- delimiter
- a string of characters used to segment the string.
The text of each segment has directional markers inserted at the beginning and end of it to ensure the entire string is rendered left-to-right and also has the Unicode Bidirectional algorithm applied to it in order to render the mixed text of the segment in the proper orientation.
As an example, a file path such as
d:\myFolder\FOLDER\MYFILE.java
(where capital letters indicate RTL-oriented text) should render as
d:\myFolder\REDLOF\ELIFYM.java
when using the Unicode Bidi algorithm and segmenting the string according to a specified delimiter set.
However, since the OS does not understand that the string should be segmented according to each segment of the file path, it renders the string as
java.ELIFYM\REDLOF\d:\myFolder
Types of strings to which this API should be applied are:
- File paths (e.g. d:\myFolder\abc\DEF)
- URLs (e.g. http://abc/DEF )
- File names with extensions (e.g. ABC.java)
- File associations (e.g. *.java, *.ABC)
To use the API, determine what delimiter characters should be used to segment the string, then simply call
TextProcessor.process(string, delimiter);
Example 1
The delimiter string for a file path would be "/\:." to account for volume separator (:), path separators (/ and \) and file extension separator (.).
Example 2
The delimiter string for a URL would be ":/".
Note that the TextProcessor#process methods should only be called on strings that are to be displayed in the user interface (UI), as the length of the string will increase when the directional markers are inserted. The directional markers are only inserted in the string when Eclipse is running in a bidirectinal locale (Arabic or Hebrew).
The Eclipse Platform has begun to use this API in the Eclipse 3.3 development stream. Examples of places where it is currently being used are the Info property page (for paths), the Properties view (for paths and file names with extensions), and the Navigator view (also for file names with extensions).
It has been suggested that APIs be provided for the most common usages so that users won't have to figure out for themselves the most common usages of this API - watch bug 146220 for progress on this issue.