Eclipse Platform
Release 4.2

org.eclipse.equinox.bidi.custom
Class STextTypeHandler

java.lang.Object
  extended by org.eclipse.equinox.bidi.custom.STextTypeHandler

public class STextTypeHandler
extends Object

Generic handler to be used as superclass (base class) for specific structured text handlers.

Here are some guidelines about how to write structured text handlers.


Constructor Summary
STextTypeHandler()
          Creates a new instance of the STextTypeHandler class.
STextTypeHandler(String separators)
          Creates a new instance of the STextTypeHandler class.
 
Method Summary
 int getDirection(ISTextExpert expert, String text)
          Indicates the base text direction appropriate for an instance of structured text.
 int getDirection(ISTextExpert expert, String text, STextCharTypes charTypes)
          Indicates the base text direction appropriate for an instance of structured text.
 String getSeparators(ISTextExpert expert)
          Indicates the separators to use for the current handler.
 int getSpecialsCount(ISTextExpert expert)
          Indicates the number of special cases handled by the current handler.
 int indexOfSpecial(ISTextExpert expert, String text, STextCharTypes charTypes, STextOffsets offsets, int caseNumber, int fromIndex)
          Locates occurrences of special strings within a structured text and returns their indexes one after the other in successive calls.
static void insertMark(String text, STextCharTypes charTypes, STextOffsets offsets, int offset)
          Specifies that a mark character must be added before the character at the specified position of the lean text when generating the full text.
static void processSeparator(String text, STextCharTypes charTypes, STextOffsets offsets, int separLocation)
          Adds a directional mark before a separator if needed for correct display, depending on the base direction of the text and on the class of the characters in the lean text preceding and following the separator itself.
 int processSpecial(ISTextExpert expert, String text, STextCharTypes charTypes, STextOffsets offsets, int caseNumber, int separLocation)
          Handles special cases specific to this handler.
 boolean skipProcessing(ISTextExpert expert, String text, STextCharTypes charTypes)
          Checks if there is a need for processing structured text.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

STextTypeHandler

public STextTypeHandler()
Creates a new instance of the STextTypeHandler class.


STextTypeHandler

public STextTypeHandler(String separators)
Creates a new instance of the STextTypeHandler class.

Parameters:
separators - string consisting of characters that split the text into fragments.
Method Detail

indexOfSpecial

public int indexOfSpecial(ISTextExpert expert,
                          String text,
                          STextCharTypes charTypes,
                          STextOffsets offsets,
                          int caseNumber,
                          int fromIndex)
Locates occurrences of special strings within a structured text and returns their indexes one after the other in successive calls.

This method is called repeatedly if the number of special cases returned by getSpecialsCount(org.eclipse.equinox.bidi.advanced.ISTextExpert) is greater than zero.

A handler handling special cases must override this method.

Parameters:
expert - ISTextExpert instance through which this handler is invoked. The handler can use ISTextExpert methods to query items stored in the expert instance, like the current environment.
text - the structured text string before addition of any directional formatting characters.
charTypes - an object whose methods can be useful to the handler.
offsets - an object whose methods can be useful to the handler.
caseNumber - number of the special case to locate. This number varies from 1 to the number of special cases returned by getSpecialsCount(org.eclipse.equinox.bidi.advanced.ISTextExpert) for this handler. The meaning of this number is internal to the class implementing indexOfSpecial.
fromIndex - the index within text to start the search from.
Returns:
the position where the start of the special case corresponding to caseNumber was located. The method must return the first occurrence of whatever identifies the start of the special case starting from fromIndex. The method does not have to check if this occurrence appears within the scope of another special case (e.g. a comment starting delimiter within the scope of a literal or vice-versa).
If no occurrence is found, the method must return -1.
Throws:
IllegalStateException - If not overridden, this method throws an IllegalStateException. This is appropriate behavior (and does not need to be overridden) for handlers whose number of special cases is zero, which means that indexOfSpecial should never be called for them.

processSpecial

public int processSpecial(ISTextExpert expert,
                          String text,
                          STextCharTypes charTypes,
                          STextOffsets offsets,
                          int caseNumber,
                          int separLocation)
Handles special cases specific to this handler. It is called when a special case occurrence is located by indexOfSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int).

If a special processing cannot be completed within a current call to processSpecial (for instance, a comment has been started in the current line but its end appears in a following line), processSpecial should specify a final state by calling ISTextExpert.setState(Object). The meaning of this state is internal to the handler.

On a later call, processSpecial will be called with -1 for parameter separLocation. It should then retrieve the last state by calling ISTextExpert.getState() and clear the state by calling ISTextExpert.clearState(). After that, it should perform whatever initializations are required depending on the last state.

A handler handling special cases (with a number of special cases greater than zero) must override this method.

Parameters:
expert - ISTextExpert instance through which this handler is invoked. The handler can use ISTextExpert methods to query items stored in the expert instance, like the current environment.
text - the structured text string before addition of any directional formatting characters.
charTypes - an object whose methods can be useful to the handler.
offsets - an object whose methods can be useful to the handler.
caseNumber - number of the special case to handle.
separLocation - the position returned by indexOfSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int). After calls to ISTextExpert.leanToFullText(java.lang.String) and other methods of ISTextExpert which set a non-null final state, processSpecial is called when initializing the processing with value of separLocation equal to -1.
Returns:
the position after the scope of the special case ends. For instance, the position after the end of a comment, the position after the end of a literal.
A value greater or equal to the length of text means that there is no further occurrence of this case in the current structured text.
Throws:
IllegalStateException - If not overridden, this method throws an IllegalStateException. This is appropriate behavior (and does not need to be overridden) for handlers whose number of special cases is zero, which means that processSpecial should never be called for them.

insertMark

public static final void insertMark(String text,
                                    STextCharTypes charTypes,
                                    STextOffsets offsets,
                                    int offset)
Specifies that a mark character must be added before the character at the specified position of the lean text when generating the full text. This method can be called from within indexOfSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int) or processSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int) in extensions of STextTypeHandler. 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 method, but its position is noted and will be used when generating the full text.

Parameters:
text - is the structured text string received as parameter to indexOfSpecial or processSpecial.
charTypes - is a parameter received by indexOfSpecial or processSpecial.
offsets - is a parameter received by indexOfSpecial or processSpecial.
offset - position of the character in the lean text. It must be a non-negative number smaller than the length of the lean text. For the benefit of efficiency, it is better to insert multiple marks in ascending order of the offsets.

processSeparator

public static final void processSeparator(String text,
                                          STextCharTypes charTypes,
                                          STextOffsets offsets,
                                          int separLocation)
Adds a directional mark before a separator if needed for correct display, depending on the base direction of the text and on the class of the characters in the lean text preceding and following the separator itself. This method can be called from within indexOfSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int) or processSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int) in extensions of STextTypeHandler.

The logic implemented in this method considers the text before separLocation and the text following it. If, and only if, a directional mark is needed to insure that the two parts of text will be laid out according to the base direction, a mark will be added when generating the full text.

Parameters:
text - is the structured text string received as parameter to indexOfSpecial or processSpecial.
charTypes - is a parameter received by indexOfSpecial or processSpecial.
offsets - is a parameter received by indexOfSpecial or processSpecial.
separLocation - offset of the separator in the lean text. It must be a non-negative number smaller than the length of the lean text.

getSeparators

public String getSeparators(ISTextExpert expert)
Indicates the separators to use for the current handler. This method is invoked before starting the processing.

If no separators are specified, this method returns an empty string.

Parameters:
expert - ISTextExpert instance through which this handler is invoked. The handler can use ISTextExpert methods to query items stored in the expert instance, like the current environment.
Returns:
a string grouping one-character separators which separate the structured text into tokens.

getDirection

public int getDirection(ISTextExpert expert,
                        String text)
Indicates the base text direction appropriate for an instance of structured text. This method is invoked before starting the processing.

If not overridden, this method returns DIR_LTR.

Parameters:
expert - ISTextExpert instance through which this handler is invoked. The handler can use ISTextExpert methods to query items stored in the expert instance, like the current environment.
text - the structured text string to process.
Returns:
the base direction of the structured text. This direction may not be the same depending on the environment and on whether the structured text contains Arabic or Hebrew letters.
The value returned is either DIR_LTR or DIR_RTL.

getDirection

public int getDirection(ISTextExpert expert,
                        String text,
                        STextCharTypes charTypes)
Indicates the base text direction appropriate for an instance of structured text. This method is invoked before starting the processing.

If not overridden, this method returns DIR_LTR.

Parameters:
expert - ISTextExpert instance through which this handler is invoked. The handler can use ISTextExpert methods to query items stored in the expert instance, like the current environment.
text - is the structured text string to process.
charTypes - is a parameter received by indexOfSpecial or processSpecial.
Returns:
the base direction of the structured text. This direction may not be the same depending on the environment and on whether the structured text contains Arabic or Hebrew letters.
The value returned is either DIR_LTR or DIR_RTL.

getSpecialsCount

public int getSpecialsCount(ISTextExpert expert)
Indicates the number of special cases handled by the current handler. This method is invoked before starting the processing. If the number returned is zero, indexOfSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int) and processSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int) will not be invoked.

If not overridden, this method returns zero.

Parameters:
expert - ISTextExpert instance through which this handler is invoked. The handler can use ISTextExpert methods to query items stored in the expert instance, like the current environment.
Returns:
the number of special cases for the associated handler. Special cases exist for some types of structured text handlers. They are implemented by overriding methods indexOfSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int) and processSpecial(org.eclipse.equinox.bidi.advanced.ISTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.STextCharTypes, org.eclipse.equinox.bidi.custom.STextOffsets, int, int). Examples of special cases are comments, literals, or anything which is not identified by a one-character separator.

skipProcessing

public boolean skipProcessing(ISTextExpert expert,
                              String text,
                              STextCharTypes charTypes)
Checks if there is a need for processing structured text. This method is invoked before starting the processing. If the handler returns true, no directional formatting characters are added to the lean text and the processing is shortened.

If not overridden, this method returns false.

Parameters:
expert - ISTextExpert instance through which this handler is invoked. The handler can use ISTextExpert methods to query items stored in the expert instance, like the current environment.
text - is the structured text string to process.
charTypes - is a parameter received by indexOfSpecial or processSpecial.
Returns:
a flag indicating if there is no need to process the structured text to add directional formatting characters.

Eclipse Platform
Release 4.2

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2013. All rights reserved.