summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMatitiahu Allouche2011-11-08 14:42:16 (EST)
committer Oleg Besedin2011-11-08 14:42:16 (EST)
commit3450a64873b0b4c157c9a24d02255881447ab25c (patch)
tree795a2ff26f0e90c922ab582e418d1dbcb2886635
parentb854d31f31eb59741811b41ba9b4b18b47a05128 (diff)
downloadrt.equinox.bundles-3450a64873b0b4c157c9a24d02255881447ab25c.zip
rt.equinox.bundles-3450a64873b0b4c157c9a24d02255881447ab25c.tar.gz
rt.equinox.bundles-3450a64873b0b4c157c9a24d02255881447ab25c.tar.bz2
Bug 183164 - [Implementation for] Display of Complex Expressionsv20111108-1700v20111108-1400
Containing Bidirectional Text
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java60
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java18
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java19
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java26
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java11
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html36
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java14
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java3
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java40
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html10
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java2
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java31
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java11
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java11
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html55
15 files changed, 210 insertions, 137 deletions
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
index 0d6a2e9..c8c23a1 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
@@ -14,8 +14,11 @@ import org.eclipse.equinox.bidi.advanced.*;
import org.eclipse.equinox.bidi.custom.STextTypeHandler;
/**
- * Provides a number of convenience functions facilitating the
- * processing of structured text.
+ * Provides methods to process structured text. The methods in this class
+ * are the most straightforward way to transform <i>lean</i> text into
+ * <i>full</i> text and vice versa (for the meaning of <i>lean</i> and
+ * <i>full</i> text, please see the
+ * <a href="package-summary.html">package documentation</a>).
*
* @noextend This class is not intended to be subclassed by clients.
* @noinstantiate This class is not intended to be instantiated by clients.
@@ -50,9 +53,9 @@ public final class STextProcessor {
}
/**
- * Processes the given text and returns a string with appropriate
- * directional formatting characters. This is equivalent to calling
- * {@link #process(String str, String separators)} with the default
+ * Processes the given (<i>lean</i>) text and returns a string with appropriate
+ * directional formatting characters (<i>full</i> text). This is equivalent to
+ * calling {@link #process(String str, String separators)} with the default
* set of separators.
* <p>
* The processing adds directional formatting characters so that presentation
@@ -66,9 +69,11 @@ public final class STextProcessor {
* <tt>d:\myfolder\REDLOF\ELIFYM.java</tt>.
* </p>
*
- * @param str the text to be processed.
+ * @param str the <i>lean</i> text to process.
*
- * @return the processed string.
+ * @return the processed string (<i>full</i> text).
+ *
+ * @see #deprocess(String)
*/
public static String process(String str) {
return process(str, defaultSeparators);
@@ -77,13 +82,14 @@ public final class STextProcessor {
/**
* Processes a string that has a particular semantic meaning to render
* it correctly on bidi locales.
- *
- * @see #process(String)
+ * For more details, see {@link #process(String)}.
*
- * @param str the text to process.
+ * @param str the <i>lean</i> text to process.
* @param separators characters by which the string will be segmented.
*
- * @return the processed string.
+ * @return the processed string (<i>full</i> text).
+ *
+ * @see #deprocess(String)
*/
public static String process(String str, String separators) {
if ((str == null) || (str.length() <= 1))
@@ -131,17 +137,18 @@ public final class STextProcessor {
/**
* Processes a string that has a particular semantic meaning to render
* it correctly on bidi locales.
+ * For more details, see {@link #process(String)}.
*
- * @see #process(String)
- *
- * @param str the text to process.
- * @param textType an identifier for the handler instance appropriate
- * for the type of the structured text.
+ * @param str the <i>lean</i> text to process.
+ * @param textType an identifier for the structured text handler
+ * appropriate for the type of the text submitted.
* It may be one of the identifiers defined in
* {@link STextTypeHandlerFactory} or a type handler identifier
- * specified in a plug-in.
+ * registered by a plug-in.
*
- * @return the processed string
+ * @return the processed string (<i>full</i> text).
+ *
+ * @see #deprocessTyped
*/
public static String processTyped(String str, String textType) {
if ((str == null) || (str.length() <= 1))
@@ -163,9 +170,9 @@ public final class STextProcessor {
/**
* Removes directional formatting characters in the given string.
*
- * @param str string with directional characters to remove.
+ * @param str string with directional characters to remove (<i>full</i> text).
*
- * @return string without directional formatting characters.
+ * @return string without directional formatting characters (<i>lean</i> text).
*/
public static String deprocess(String str) {
if ((str == null) || (str.length() <= 1))
@@ -195,15 +202,16 @@ public final class STextProcessor {
/**
* Removes directional formatting characters in the given string.
*
- * @param str string with directional characters to remove.
- *
- * @param textType an identifier for the handler instance appropriate
- * for the type of the structured text.
+ * @param str string with directional characters to remove (<i>full</i> text).
+ * @param textType an identifier for the structured text handler
+ * appropriate for the type of the text submitted.
* It may be one of the identifiers defined in
* {@link STextTypeHandlerFactory} or a type handler identifier
- * specified in a plug-in.
+ * registered by a plug-in.
*
- * @return string without directional formatting characters.
+ * @return string without directional formatting characters (<i>lean</i> text).
+ *
+ * @see #processTyped(String, String)
*/
public static String deprocessTyped(String str, String textType) {
if ((str == null) || (str.length() <= 1))
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
index d134e55..4f4513a 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
@@ -10,12 +10,28 @@
******************************************************************************/
package org.eclipse.equinox.bidi;
+import org.eclipse.equinox.bidi.advanced.STextEnvironment;
+import org.eclipse.equinox.bidi.advanced.STextExpertFactory;
import org.eclipse.equinox.bidi.custom.STextTypeHandler;
import org.eclipse.equinox.bidi.internal.STextTypesCollector;
/**
* Provides access to registered structured text handlers.
- *
+ * <p>
+ * A structured text handler is a subclass of {@link STextTypeHandler}
+ * adapted for a given type of structured text.
+ * <p>
+ * The constants in this class are identifiers for structured text
+ * handlers which are defined and supported "out of the box" by this package.
+ * Text handler identifiers can be used when invoking {@link STextProcessor#processTyped(String, String)},
+ * or when invoking <code>getExpert</code> methods in {@link STextExpertFactory}.
+ * <p>
+ * The {@link #getHandler} method in this class can be used to get a
+ * structured text handler reference for one of the handlers defined in this
+ * package or for additional structured text handlers registered by plug-ins.
+ * Text handler references can be used when invoking
+ * {@link STextExpertFactory#getStatefulExpert(STextTypeHandler, STextEnvironment)}.
+ *
* @noinstantiate This class is not intended to be instantiated by clients.
*/
final public class STextTypeHandlerFactory {
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
index 171a2e6..9cea28f 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
@@ -105,6 +105,7 @@ public interface ISTextExpert {
/**
* Obtains the structured type handler associated with this
* <code>ISTextExpert</code> instance.
+ *
* @return the type handler instance.
*/
public STextTypeHandler getTypeHandler();
@@ -214,8 +215,18 @@ public interface ISTextExpert {
* </p><p>
* If necessary, leading and trailing directional formatting characters
* (LRE, RLE and PDF) can be added depending on the value of the
- * <code>affix</code> argument.
- * </p>
+ * <code>affix</code> argument.</p>
+ * <ul>
+ * <li>A value of 1 means that one LRM or RLM must be prefixed, depending
+ * on the direction. This is useful when the GUI component presenting
+ * this text has a contextual orientation.</li>
+ * <li>A value of 2 means that LRE+LRM or RLE+RLM must be prefixed,
+ * depending on the direction, and LRM+PDF or RLM+PDF must be
+ * suffixed, depending on the direction.
+ * This is useful if the GUI component presenting this text needs to
+ * have the text orientation explicitly specified.</li>
+ * <li>A value of 0 means that no prefix or suffix are needed.</li>
+ * </ul>
* @see ISTextExpert#leanBidiCharOffsets(String)
*
* @param text the structured text string
@@ -256,6 +267,7 @@ public interface ISTextExpert {
/**
* Sets the state for the next text processing call.
* This method does nothing if the expert instance is not a stateful one.
+ *
* @param state an object returned by a previous call to {@link #getState}.
*/
public void setState(Object state);
@@ -263,7 +275,8 @@ public interface ISTextExpert {
/**
* Gets the state established by the last text processing call.
* This is <code>null</code> if the expert instance is not a stateful one,
- * or if the last text processing call has nothing to pass to the next call.
+ * or if the last text processing call had nothing to pass to the next call.
+ *
* @return the last established state.
*/
public Object getState();
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
index 474fb00..6705ddf 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
@@ -97,11 +97,11 @@ public class STextEnvironment {
/**
* Creates an instance of a structured text environment.
*
- * @param lang the language to of the environment, encoded as specified
+ * @param lang the language of the environment, encoded as specified
* in ISO-639. Might be <code>null</code>, in which case the default
* locale is used.
* @param mirrored specifies if the environment is mirrored.
- * @param orientation the orientation of the GUI component:
+ * @param orientation the orientation of the GUI component, one of the values:
* {@link #ORIENT_LTR ORIENT_LTR},
* {@link #ORIENT_LTR ORIENT_RTL},
* {@link #ORIENT_CONTEXTUAL_LTR ORIENT_CONTEXTUAL_LTR},
@@ -124,6 +124,7 @@ public class STextEnvironment {
/**
* Returns a 2-letters code representing a language as defined by
* ISO-639.
+ *
* @return language of the environment
*/
public String getLanguage() {
@@ -134,6 +135,7 @@ public class STextEnvironment {
* Returns a flag indicating that structured text processed
* within this environment should assume that the GUI is mirrored
* (globally going from right to left).
+ *
* @return <code>true</code> if environment is mirrored
*/
public boolean getMirrored() {
@@ -145,7 +147,7 @@ public class STextEnvironment {
* component in which the <i>full</i> structured text
* will be displayed.
* <p>
- * The orientation values:
+ * The orientation value is one of the following:
* <ul>
* <li>{@link #ORIENT_LTR ORIENT_LTR},</li>
* <li>{@link #ORIENT_LTR ORIENT_RTL},</li>
@@ -161,7 +163,11 @@ public class STextEnvironment {
}
/**
- * Checks if bidi processing is needed in this environment.
+ * Checks if bidi processing is needed in this environment. The result
+ * depends on the operating system (must be supported by this package)
+ * and on the language supplied when constructing the instance (it
+ * must be a language using a bidirectional script).
+ *
* @return <code>true</code> if bidi processing is needed in this environment.
*/
public boolean isProcessingNeeded() {
@@ -185,6 +191,12 @@ public class STextEnvironment {
return processingNeeded.booleanValue();
}
+ /**
+ * Computes the hashCode based on the values supplied when constructing
+ * the instance and on the result of {@link #isProcessingNeeded()}.
+ *
+ * @return the hash code.
+ */
public int hashCode() {
final int prime = 31;
int result = 1;
@@ -195,6 +207,12 @@ public class STextEnvironment {
return result;
}
+ /**
+ * Compare 2 environment instances and returns true if both instances
+ * were constructed with the same arguments.
+ *
+ * @return true if the 2 instances can be used interchangeably.
+ */
public boolean equals(Object obj) {
if (this == obj)
return true;
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
index d0f7a12..e6e21b8 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
@@ -19,7 +19,11 @@ import org.eclipse.equinox.bidi.internal.STextImpl;
/**
* Obtains ISTextExpert instances.
- * There are two kinds of {@link ISTextExpert} instances (called "experts"):
+ * An {@link ISTextExpert} instance (called in short an "expert") provides
+ * the advanced methods to process a certain type of structured text, and
+ * is thus related to a specific
+ * {@link STextTypeHandler structured text type handler}.
+ * There are two kinds of experts:
* <ul>
* <li>stateful, obtained by calling {@link #getStatefulExpert getStatefulExpert}.</li>
* <li>not stateful, obtained by calling {@link #getExpert getExpert}.</li>
@@ -27,6 +31,11 @@ import org.eclipse.equinox.bidi.internal.STextImpl;
* <p>Only the stateful kind can remember the state established by a call to
* a text processing method and transmit it as initial state in the next call
* to a text processing method.
+ * <p>In other words, the methods
+ * {@link ISTextExpert#getState() getState},
+ * {@link ISTextExpert#setState setState} and
+ * {@link ISTextExpert#clearState() clearState} of
+ * {@link ISTextExpert} are inoperative for experts which are not stateful.
* <p>
* Using a stateful expert is more resource intensive, thus not stateful
* experts should be used when feasible.
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html
index 9b71e0c..438719b 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html
@@ -4,17 +4,11 @@
<META name="Author" content="Matitiahu Allouche">
</head>
<body bgcolor="white">
-
+<p>
This package provides classes for users who need finer control
on structured text handling.
-<br>
-Note that the basic functions are provided in package
-{@link <a href="../package-summary.html">
-org.eclipse.equinox.bidi</a>} and its
-{@link <a href="../STextProcessor.html">STextProcessor</a>} class.
-<p>
In particular, the user should use the methods in the
-{@link <a href="ISTextExpert.html">ISTextExpert</a>} class
+<a href="ISTextExpert.html">ISTextExpert</a> class
in the following cases:</p>
<ul>
<li>The structured type handler to use is not one of those
@@ -27,5 +21,31 @@ in the following cases:</p>
<li>The user needs to manage the offsets where directional formatting
characters are inserted in the text.</li>
</ul>
+<p>
+Note that the basic functions are provided in package
+{@link <a href="../package-summary.html">
+org.eclipse.equinox.bidi</a>} and its
+{@link <a href="../STextProcessor.html">STextProcessor</a>} class.
+</p><p>
+To access the more sophisticated methods for processing structured text,
+the user should proceed as follows:</p>
+<ul>
+ <li>The user has to obtain an appropriate
+ <code>ISTextExpert</code> instance using the methods in
+ <a href="STextExpertFactory.html">STextExpertFactory</a>.</li>
+ <li>The user may then invoke the more sophisticated methods provided by
+ <a href="ISTextExpert.html">ISTextExpert</a>
+ for processing the structured text.</li>
+ <li>If those methods should work in an environment different from the default,
+ the user may specify properties of the environment using the class
+ <a href="STextEnvironment.html">STextEnvironment</a>.
+ <p>
+ This should be done before obtaining a <code>ISTextExpert</code> instance,
+ and the specific environment must be specified when invoking
+ <code>STextExpertFactory</code> methods. This will
+ associate a type handler with the given environment and provide
+ a customized <code>ISTextExpert</code> instance to the user.</p></li>
+</ul>
+
</body>
</html>
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
index f279259..edb8761 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
@@ -14,7 +14,7 @@ import org.eclipse.equinox.bidi.advanced.ISTextExpert;
import org.eclipse.equinox.bidi.advanced.STextEnvironment;
/**
- * Determines bidirectional types of characters in a string.
+ * Provides services related to the bidi classification of characters.
*/
public class STextCharTypes {
@@ -36,9 +36,21 @@ public class STextCharTypes {
private static final int CHARTYPES_ADD = 2;
+ /**
+ * The ISTextExpert instance which created this instance.
+ */
final protected ISTextExpert expert;
+ /**
+ * The STextTypeHandler instance utilized by the expert.
+ */
final protected STextTypeHandler handler;
+ /**
+ * The environment associated with the expert.
+ */
final protected STextEnvironment environment;
+ /**
+ * The source text whose characters are analyzed.
+ */
final protected String text;
// 1 byte for each char in text
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
index 086c950..3433de3 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
@@ -12,7 +12,8 @@ package org.eclipse.equinox.bidi.custom;
/**
* Provides various services related to managing the array of
- * offsets where directional formatting characters will be inserted.
+ * offsets where directional formatting characters should be inserted
+ * in a source string.
*
* @author Matitiahu Allouche
*
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
index 869b5cf..ad6fed4 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
@@ -23,7 +23,9 @@ import org.eclipse.equinox.bidi.internal.STextImpl;
* <ul>
* <li>Handler instances may be accessed simultaneously by
* several threads. They should have no instance variables.</li>
- * <li>The common logic uses handler methods to query the
+ * <li>This class provides common logic in code which can be invoked
+ * by any {@link STextTypeHandler structured text handler}.
+ * This common logic uses handler methods to query the
* characteristics of the specific handler:
* <ul>
* <li>the separators which separate the structured text into
@@ -87,26 +89,21 @@ public class STextTypeHandler {
* is invoked. The handler can use ISTextExpert methods to
* query items stored in the expert instance, like the current
* {@link STextEnvironment environment}.
- *
* @param text the structured text string before
* addition of any directional formatting characters.
- *
* @param charTypes an object whose methods can be useful to the
* handler.
- *
* @param offsets an object whose methods can be useful to the
* handler.
- *
* @param caseNumber number of the special case to locate.
* This number varies from 1 to the number of special cases
* returned by {@link #getSpecialsCount getSpecialsCount}
* for this handler.
* The meaning of this number is internal to the class
* implementing <code>indexOfSpecial</code>.
- *
* @param fromIndex the index within <code>text</code> to start
* the search from.
- *
+ *
* @return the position where the start of the special case
* corresponding to <code>caseNumber</code> was located.
* The method must return the first occurrence of whatever
@@ -131,7 +128,7 @@ public class STextTypeHandler {
/**
* Handles special cases specific to this handler.
* It is called when a special case occurrence
- * is located by {@link #indexOfSpecial}.
+ * is located by {@link #indexOfSpecial indexOfSpecial}.
* <p>
* If a special processing cannot be completed within a current call to
* <code>processSpecial</code> (for instance, a comment has been started
@@ -154,18 +151,13 @@ public class STextTypeHandler {
* is invoked. The handler can use ISTextExpert methods to
* query items stored in the expert instance, like the current
* {@link STextEnvironment environment}.
- *
* @param text the structured text string before
* addition of any directional formatting characters.
- *
* @param charTypes an object whose methods can be useful to the
* handler.
- *
* @param offsets an object whose methods can be useful to the
* handler.
- *
* @param caseNumber number of the special case to handle.
- *
* @param separLocation the position returned by
* {@link #indexOfSpecial indexOfSpecial}. After calls to
* {@link ISTextExpert#leanToFullText leanToFullText} and other
@@ -195,8 +187,10 @@ public class STextTypeHandler {
/**
* Specifies that a mark character must be added before the character
* at the specified position of the <i>lean</i> text when generating the
- * <i>full</i> text. This method can be called from within {@link #indexOfSpecial}
- * or {@link #processSpecial} in extensions of <code>STextTypeHandler</code>.
+ * <i>full</i> text. This method can be called from within
+ * {@link #indexOfSpecial indexOfSpecial} or
+ * {@link #processSpecial processSpecial} in extensions of
+ * <code>STextTypeHandler</code>.
* The mark character will be LRM for structured text
* with a LTR base direction, and RLM for structured text with RTL
* base direction. The mark character is not added physically by this
@@ -206,13 +200,10 @@ public class STextTypeHandler {
* @param text is the structured text string received as
* parameter to <code>indexOfSpecial</code> or
* <code>processSpecial</code>.
- *
* @param charTypes is a parameter received by <code>indexOfSpecial</code>
* or <code>processSpecial</code>.
- *
* @param offsets is a parameter received by <code>indexOfSpecial</code>
* or <code>processSpecial</code>.
- *
* @param offset position of the character in the <i>lean</i> text.
* It must be a non-negative number smaller than the length
* of the <i>lean</i> text.
@@ -228,8 +219,9 @@ public class STextTypeHandler {
* display, depending on the base direction of the text and on the
* class of the characters in the <i>lean</i> text preceding and
* following the separator itself. This method
- * can be called from within {@link #indexOfSpecial} or
- * {@link #processSpecial} in extensions of <code>STextTypeHandler</code>.
+ * can be called from within {@link #indexOfSpecial indexOfSpecial} or
+ * {@link #processSpecial processSpecial} in extensions of
+ * <code>STextTypeHandler</code>.
* <p>
* The logic implemented in this method considers the text before
* <code>separLocation</code> and the text following it. If, and only if,
@@ -240,13 +232,10 @@ public class STextTypeHandler {
* @param text is the structured text string received as
* parameter to <code>indexOfSpecial</code> or
* <code>processSpecial</code>.
- *
* @param charTypes is a parameter received by <code>indexOfSpecial</code>
* or <code>processSpecial</code>.
- *
* @param offsets is a parameter received by <code>indexOfSpecial</code>
* or <code>processSpecial</code>.
- *
* @param separLocation offset of the separator in the <i>lean</i> text.
* It must be a non-negative number smaller than the length
* of the <i>lean</i> text.
@@ -283,7 +272,6 @@ public class STextTypeHandler {
* is invoked. The handler can use ISTextExpert methods to
* query items stored in the expert instance, like the current
* {@link STextEnvironment environment}.
- *
* @param text the structured text string to process.
*
* @return the base direction of the structured text. This direction
@@ -308,9 +296,7 @@ public class STextTypeHandler {
* is invoked. The handler can use ISTextExpert methods to
* query items stored in the expert instance, like the current
* {@link STextEnvironment environment}.
- *
* @param text is the structured text string to process.
- *
* @param charTypes is a parameter received by <code>indexOfSpecial</code>
* or <code>processSpecial</code>.
*
@@ -364,9 +350,7 @@ public class STextTypeHandler {
* is invoked. The handler can use ISTextExpert methods to
* query items stored in the expert instance, like the current
* {@link STextEnvironment environment}.
- *
* @param text is the structured text string to process.
- *
* @param charTypes is a parameter received by <code>indexOfSpecial</code>
* or <code>processSpecial</code>.
*
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html
index 5f7ead0..6b7ac75 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html
@@ -5,11 +5,9 @@
</head>
<body bgcolor="white">
<p>
-This package provides classes for
-developing structured text type handlers.
-</p><p>
-This package is to be used together with package
-{@link <a href="..\package-summary.html">
-org.eclipse.equinox.bidi</a>}.
+This package provides classes for developing structured text type handlers.
+It is to be used together with package
+{@link <a href="..\package-summary.html">org.eclipse.equinox.bidi</a>}.
+</p>
</body>
</html>
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
index d71fcdd..ba6419f 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
@@ -50,7 +50,7 @@ public abstract class STextDelims extends STextTypeHandler {
/**
* Handles the text between start and end delimiters as a token.
- * This methoed inserts a directional mark if needed at position
+ * This method inserts a directional mark if needed at position
* <code>separLocation</code> which corresponds to a start delimiter,
* and skips until after the matching end delimiter.
*
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
index 4285ba6..d26f419 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
@@ -10,8 +10,7 @@
******************************************************************************/
package org.eclipse.equinox.bidi.internal;
-import org.eclipse.equinox.bidi.advanced.ISTextExpert;
-import org.eclipse.equinox.bidi.advanced.STextEnvironment;
+import org.eclipse.equinox.bidi.advanced.*;
import org.eclipse.equinox.bidi.custom.*;
/**
@@ -52,11 +51,30 @@ public class STextImpl implements ISTextExpert {
static final int FIXES_LENGTH = PREFIX_LENGTH + SUFFIX_LENGTH;
static final int[] EMPTY_INT_ARRAY = new int[0];
+ /**
+ * The structured text handler utilized by this expert.
+ */
protected final STextTypeHandler handler;
+ /**
+ * The environment associated with the expert.
+ */
protected final STextEnvironment environment;
+ /**
+ * Flag which is true if the expert is stateful.
+ */
protected final boolean sharedExpert;
+ /**
+ * Last state value set by {@link #setState} or {@link #clearState}.
+ */
protected Object state;
+ /**
+ * Constructor used in {@link STextExpertFactory}.
+ *
+ * @param structuredTextHandler the structured text handler used by this expert.
+ * @param environment the environment associated with this expert.
+ * @param shared flag which is true if the expert is stateful.
+ */
public STextImpl(STextTypeHandler structuredTextHandler, STextEnvironment environment, boolean shared) {
this.handler = structuredTextHandler;
this.environment = environment;
@@ -127,6 +145,9 @@ public class STextImpl implements ISTextExpert {
return nextLocation + (((long) idxLocation) << 32);
}
+ /**
+ * @see STextTypeHandler#processSeparator STextTypeHandler.processSeparator
+ */
static public void processSeparator(String text, STextCharTypes charTypes, STextOffsets offsets, int separLocation) {
int len = text.length();
int direction = charTypes.getDirection();
@@ -226,7 +247,6 @@ public class STextImpl implements ISTextExpert {
* {@link ISTextExpert#leanToFullText leanToFullText} does not add any directional
* formatting characters as either prefix or suffix of the <i>full</i> text.
* <p>
- * @see ISTextExpert#leanToFullText STextEngine.leanToFullText
*/
public String leanToFullText(String text) {
int len = text.length();
@@ -512,8 +532,9 @@ public class STextImpl implements ISTextExpert {
} else {
// When the orientation is RTL, we need to add EMBED at the
// start of the text and PDF at its end.
- // However, because of a bug in Windows' handling of LRE/PDF,
- // we add EMBED_PREFIX at the start and EMBED_SUFFIX at the end.
+ // However, because of a bug in Windows' handling of LRE/RLE/PDF,
+ // we add LRM or RLM (according to the direction) after the
+ // LRE/RLE and again before the PDF.
char curEmbed = EMBEDS[direction];
fullChars[0] = curEmbed;
fullChars[1] = curMark;
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java
index 0c60489..df62726 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java
@@ -10,9 +10,8 @@
******************************************************************************/
package org.eclipse.equinox.bidi.internal;
-import org.eclipse.equinox.bidi.STextTypeHandlerFactory;
-
import java.lang.ref.SoftReference;
+import org.eclipse.equinox.bidi.STextTypeHandlerFactory;
/**
* Records strings which contain structured text. Several static
@@ -80,19 +79,15 @@ public class STextStringRecord {
* and ending offsets for the first segment.
*
* @param string the string to record.
- *
* @param segmentCount number of segments allowed in this string.
* This number must be >= 1.
- *
* @param handlerID identifier for the handler appropriate to handle
* the type of structured text present in the first segment.
* It may be one of the predefined identifiers in
* {@link STextTypeHandlerFactory}, or it may be an identifier
* for a type handler created by a plug-in or by the application.
- *
* @param start offset in the string of the starting character of the first
* segment. It must be >= 0 and less than the length of the string.
- *
* @param limit offset of the character following the first segment. It
* must be greater than the <code>start</code> argument and
* not greater than the length of the string.
@@ -147,10 +142,8 @@ public class STextStringRecord {
* It may be one of the predefined identifiers in
* {@link STextTypeHandlerFactory}, or it may be an identifier
* for a type handler created by a plug-in or by the application.
- *
* @param start offset in the string of the starting character of the
* segment. It must be >= 0 and less than the length of the string.
- *
* @param limit offset of the character following the segment. It must be
* greater than the <code>start</code> argument and not greater
* than the length of the string.
@@ -179,7 +172,7 @@ public class STextStringRecord {
}
/**
- * Checks if a string is recorded and retrieve its record.
+ * Checks if a string is recorded and retrieves its record.
*
* @param string the string to check.
*
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
index 4b94cac..6daa9af 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
@@ -36,10 +36,16 @@ public class STextTypesCollector implements IRegistryEventListener {
registry.addListener(this, EXT_POINT);
}
+ /**
+ * @return a static instance.
+ */
static public STextTypesCollector getInstance() {
return instance;
}
+ /**
+ * @return a list of all the registered structured text handler types.
+ */
public String[] getTypes() {
if (types == null)
read();
@@ -49,6 +55,11 @@ public class STextTypesCollector implements IRegistryEventListener {
return result;
}
+ /**
+ * @param type the identifier for a structured text handler.
+ *
+ * @return the structured text handler instance.
+ */
public STextTypeHandler getHandler(String type) {
if (types == null)
read();
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
index 665718d..1b23975 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
@@ -20,7 +20,8 @@ Bidirectional text offers interesting challenges to presentation systems.
For plain text, the Unicode Bidirectional Algorithm
(<a href="http://www.unicode.org/reports/tr9/">UBA</a>)
generally specifies satisfactorily how to reorder bidirectional text for
-display. This algorithm is implemented in Java's presentation system.
+display. This algorithm is implemented in many presentation and operating
+systems, like Java/Swing, Windows, Linux.
</p><p>
However, all bidirectional text is not necessarily plain text. There
are also instances of text structured to follow a given syntax, which
@@ -72,17 +73,6 @@ For each of these types, an identifier is defined in
These identifiers can be used as argument in some methods of
<b>STextProcessor</b> to specify the type of handler to apply.
</p><p>
-Another class in this package may be used to
-complement the action of
-{@link <a href="STextProcessor.html">STextProcessor</a>}:
-<ul>
- <li>{@link <a href="STextStringRecord.html">STextStringRecord</a>}
- allows to record strings which are structured text with the
- type of the appropriate handler,
- so that another module can check if a given string has been recorded
- as a structured text string and run its type handler.</li>
-</ul>
-<p>
The classes included in this package are intended for users who
need to process structured text in the most straightforward
manner, when the following conditions are satisfied:
@@ -102,51 +92,30 @@ manner, when the following conditions are satisfied:
When their needs go beyond the conditions above,
users can use classes in the
{@link <a href="advanced/package-summary.html">
-org.eclipse.equinox.bidi.advanced</a>} package:
-<ul>
- <li>{@link <a href="advanced/ISTextExpert.html">ISTextExpert</a>}
- provides more sophisticated methods for processing the
- structured text.</li>
- <li>{@link <a href="advanced/STextEnvironment.html">STextEnvironment</a>}
- specifies properties of the environment.</li>
- <li>{@link <a href="advanced/STextExpertFactory.html">STextExpertFactory</a>}
- associates a type handler with an environment and provides
- a <code>STextExpert</code> instance for the user.
-</ul>
-<p>
+org.eclipse.equinox.bidi.advanced</a>} package.
+</p><p>
Developers who want to develop new handlers to support types of
-structured text not currently supported can use the following components
+structured text not currently supported can use components
of the package {@link <a href="custom/package-summary.html">
-org.eclipse.equinox.bidi.custom</a>}:
-<ul>
- <li>{@link <a href="custom/STextTypeHandler.html">STextTypeHandler</a>}
- is a generic handler to be used as superclass for specific
- handlers.</li>
- <li>{@link <a href="custom/STextCharTypes.html">STextCharTypes</a>}
- provides services related to the bidi classification of characters.</li>
- <li>{@link <a href="custom/STextOffsets.html">STextOffsets</a>}
- provides services related to managing an array of offsets to locations
- where directional formatting characters should be added in the source
- string.</li>
-</ul>
-<p>
-There are two other packages associated with the current one:
+org.eclipse.equinox.bidi.custom</a>}.
+</p><p>
+There are two other packages associated with the current one:</p>
<ul>
<li>{@link <a href="internal/package-summary.html">
org.eclipse.equinox.bidi.internal</a>}</li>
<li>{@link <a href="internal/consumable/package-summary.html">
org.eclipse.equinox.bidi.internal.consumable</a>}</li>
</ul>
+<p>
The tools in the first package can serve as example of how to develop
processors for currently unsupported types of structured text.<br>
The latter package contains classes for the processors implementing
the currently supported types of structured text.
-<p>
+</p><p>
However, users wishing to process the currently supported types of
structured text typically don't need to interact with these
two packages.
-
-<p>&nbsp;</p>
+</p>
<h2>Abbreviations used in the documentation of this package</h2>
@@ -188,7 +157,7 @@ attention:</p>
Linux) are very similar but nevertheless have known differences. Those
differences are minor and will not have a visible effect in most cases.
However there might be cases in which the same bidi text on two
-platforms might look different. These differences will surface in Java
+platforms will look different. These differences will surface in Java
applications when they use the platform visual components for their UI
(e.g., AWT, SWT).</li>