public class StructuredTextTypeHandler extends Object
Here are some guidelines about how to write structured text handlers.
structured text handler
.
This common logic uses handler methods to query the
characteristics of the specific handler:
getSeparators(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert)
.getDirection(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String)
.getSpecialsCount(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert)
.skipProcessing(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes)
method.getSeparators(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert)
).getSpecialsCount(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert)
method, the common logic will repeatedly invoke the handler's
indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
method to let it signal the
presence of special strings which may further delimit the source text.processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
method to give it the opportunity to handle it as needed. Typical
actions that the handler may perform are to add directional marks
unconditionally (by calling insertMark(java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int)
or
conditionally (by calling processSeparator(java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int)
).Constructor and Description |
---|
StructuredTextTypeHandler()
Creates a new instance of the StructuredTextTypeHandler class.
|
StructuredTextTypeHandler(String separators)
Creates a new instance of the StructuredTextTypeHandler class.
|
Modifier and Type | Method and Description |
---|---|
int |
getDirection(IStructuredTextExpert expert,
String text)
Indicates the base text direction appropriate for an instance of
structured text.
|
int |
getDirection(IStructuredTextExpert expert,
String text,
StructuredTextCharTypes charTypes)
Indicates the base text direction appropriate for an instance of
structured text.
|
String |
getSeparators(IStructuredTextExpert expert)
Indicates the separators to use for the current handler.
|
int |
getSpecialsCount(IStructuredTextExpert expert)
Indicates the number of special cases handled by the current handler.
|
int |
indexOfSpecial(IStructuredTextExpert expert,
String text,
StructuredTextCharTypes charTypes,
StructuredTextOffsets 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,
StructuredTextCharTypes charTypes,
StructuredTextOffsets 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,
StructuredTextCharTypes charTypes,
StructuredTextOffsets 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(IStructuredTextExpert expert,
String text,
StructuredTextCharTypes charTypes,
StructuredTextOffsets offsets,
int caseNumber,
int separLocation)
Handles special cases specific to this handler.
|
boolean |
skipProcessing(IStructuredTextExpert expert,
String text,
StructuredTextCharTypes charTypes)
Checks if there is a need for processing structured text.
|
String |
toString() |
public StructuredTextTypeHandler()
public StructuredTextTypeHandler(String separators)
separators
- string consisting of characters that split the text into fragments.public int indexOfSpecial(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int caseNumber, int fromIndex)
This method is called repeatedly if the number of special cases
returned by getSpecialsCount(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert)
is greater than zero.
A handler handling special cases must override this method.
expert
- IStructuredTextExpert instance through which this handler
is invoked. The handler can use IStructuredTextExpert 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.IStructuredTextExpert)
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.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).
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.public int processSpecial(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int caseNumber, int separLocation)
indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, 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
IStructuredTextExpert.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 IStructuredTextExpert.getState()
and
clear the state by calling IStructuredTextExpert.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.
expert
- IStructuredTextExpert instance through which this handler
is invoked. The handler can use IStructuredTextExpert 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.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
. After calls to
IStructuredTextExpert.leanToFullText(java.lang.String)
and other
methods of IStructuredTextExpert
which set a non-null
final state, processSpecial
is
called when initializing the processing with value of
separLocation
equal to -1
.text
means that there is no further occurrence of this case in the
current structured text.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.public static final void insertMark(String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int offset)
indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
or
processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
in extensions of
StructuredTextTypeHandler
.
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.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.public static final void processSeparator(String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int separLocation)
indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
or
processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
in extensions of
StructuredTextTypeHandler
.
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.
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.public String getSeparators(IStructuredTextExpert expert)
If no separators are specified, this method returns an empty string.
expert
- IStructuredTextExpert instance through which this handler
is invoked. The handler can use IStructuredTextExpert methods to
query items stored in the expert instance, like the current
environment
.public int getDirection(IStructuredTextExpert expert, String text)
If not overridden, this method returns DIR_LTR
.
expert
- IStructuredTextExpert instance through which this handler
is invoked. The handler can use IStructuredTextExpert methods to
query items stored in the expert instance, like the current
environment
.text
- the structured text string to process.DIR_LTR
or
DIR_RTL
.public int getDirection(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes)
If not overridden, this method returns DIR_LTR
.
expert
- IStructuredTextExpert instance through which this handler
is invoked. The handler can use IStructuredTextExpert 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
.DIR_LTR
or DIR_RTL
.public int getSpecialsCount(IStructuredTextExpert expert)
indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
and processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
will not be invoked.
If not overridden, this method returns zero
.
expert
- IStructuredTextExpert instance through which this handler
is invoked. The handler can use IStructuredTextExpert methods to
query items stored in the expert instance, like the current
environment
.indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
and
processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int)
.
Examples of special cases are comments, literals, or
anything which is not identified by a one-character separator.public boolean skipProcessing(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes)
true
, no directional formatting
characters are added to the lean text and the processing
is shortened.
If not overridden, this method returns false
.
expert
- IStructuredTextExpert instance through which this handler
is invoked. The handler can use IStructuredTextExpert 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
.
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.