Class TextRange
- java.lang.Object
-
- com.adobe.xfa.text.TextRange
-
- Direct Known Subclasses:
TextSelection
public class TextRange extends java.lang.Object
-
-
Field Summary
Fields Modifier and Type Field Description static int
POSN_ANCHOR
static int
POSN_END
static int
POSN_LOOSE
static int
POSN_START
-
Constructor Summary
Constructors Constructor Description TextRange()
Default constructor.TextRange(TextRange oSource)
Copy constructor.TextRange(TextStream poStream)
Constructor with stream.TextRange(TextStream poStream, int nNewAnchor, int nNewLoose)
Constructor with stream and indexes.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description TextPosn
anchor()
Query the anchor position.void
anchor(int nNewIndex)
Set the anchor position by index.void
anchor(TextPosn oNewPosn)
Set the anchor position by text position object.void
associate(TextStream poStream)
Overridden: Associate range with a new stream.void
associate(TextStream poStream, int nNewAnchor, int nNewLoose)
Overridden: Associate range with a new stream, specifying range indexes.TextAttr
attribute()
Obtain the attributes in effect over the range.void
attribute(TextAttr oNewAttr)
void
attribute(TextAttr oNewAttr, boolean bRaw)
Change text attributes over the range.TextPosnBase
charPosition(int lIndex)
Create a position with the associated stream, given a character index.TextRange
charRange(int lStart, int lLength)
Create a range with the associated stream, given a character index and length.void
copyFrom(TextRange oSource)
Assignment operator.int
count()
Count the number of items in the range.int
countEmbed()
Count the number of embedded objects in the range.int
countField()
Count the number of embedded fields in the range.int
countText()
Count the number of characters in the range.void
delete()
void
delete(boolean bRaw)
Delete the contents of the range.TextPosn
end()
Query the end position.void
end(int nNewIndex)
Set the end position by index.void
end(TextPosn oNewPosn)
Set the end position by text position object.void
enumerateMarkers(java.util.List<TextMarker> oMarkers)
void
enumerateMarkers(java.util.List<TextMarker> oMarkers, boolean bPositionMarkers, boolean bRangeMarkers, boolean bSubsetOnly)
Enumerate markers contained within this range.boolean
equals(java.lang.Object object)
Equality comparison.boolean
getSelectionRectangles(java.util.List<Rect> oRectangles)
Obtain the rectangle(s) in the laid-out text corresponding to this range.boolean
grabLine()
Extend the range to include complete lines.boolean
grabPara()
Extend the range to include complete paragraphs.boolean
grabWord()
boolean
grabWord(int eWordMode)
Extend the range to include complete words.int
hashCode()
TextMarker
insert(TextMarker poMarker)
Insert a range marker at the position represented by this position object.boolean
isEmpty()
Is the range empty?TextPosn
loose()
Query the loose position.void
loose(int nNewIndex)
Set the loose position by index.void
loose(TextPosn oNewPosn)
Set the loose position by text position object.void
markup(MarkupIn oMarkup)
Apply markup to the range.void
markup(MarkupOut oMarkup, TextAttr poInitAttr, boolean bDefaultInitAttr, boolean bFlattenFields)
Convert the range contents to markup.boolean
notEqual(TextRange oCompare)
Inequality comparison.TextPosn
position(int ePosition)
Obtain one of the range endpoints as a text position.void
position(int ePosition, int nNewPosition)
Change a range endpoint by index number.void
position(int ePosition, TextPosn oNewPosn)
Change a range endpoint by text position.void
replace(char cReplace)
void
replace(char cReplace, boolean bRaw)
Replace the range contents with a single character.void
replace(TextStream oReplace)
void
replace(TextStream oReplace, boolean bRaw)
Replace the range contents with rich text.void
replace(java.lang.String sReplace)
void
replace(java.lang.String sReplace, boolean bRaw)
Replace the range contents with string of text.TextPosn
start()
Query the start position.void
start(int nNewIndex)
Set the start position by index.void
start(TextPosn oNewPosn)
Set the start position by text position object.TextStream
stream()
Optain a pointer to the associated stream.java.lang.String
text()
java.lang.String
text(boolean bIncludeFields)
Obtain the range content as plain text.void
text(TextStream oText)
Obtain the range content as rich text.void
tighten()
Try to exclude spurious attr changes from range.boolean
union(TextRange oAdd, TextRange oResult)
Return the union of two text ranges.
-
-
-
Field Detail
-
POSN_ANCHOR
public static final int POSN_ANCHOR
- See Also:
- Constant Field Values
-
POSN_LOOSE
public static final int POSN_LOOSE
- See Also:
- Constant Field Values
-
POSN_START
public static final int POSN_START
- See Also:
- Constant Field Values
-
POSN_END
public static final int POSN_END
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
TextRange
public TextRange()
Default constructor.The range is not initially associated with any stream.
-
TextRange
public TextRange(TextRange oSource)
Copy constructor.Copy all contents of the source range, including stream association, and start/end indexes.
- Parameters:
oSource
- Source position object to copy.
-
TextRange
public TextRange(TextStream poStream)
Constructor with stream.Construct a range object associated with the given stream. The range initially covers the entire content of the stream.
- Parameters:
poStream
- Stream to associate with. NULL creates a range object with no initial association.
-
TextRange
public TextRange(TextStream poStream, int nNewAnchor, int nNewLoose)
Constructor with stream and indexes.Construct a range object associated with the given stream and covering the range of items indicated by the index values.
- Parameters:
poStream
- Stream to associate with. NULL creates a range object with no initial association.nNewAnchor
- Anchor index for the range. Will be truncated if too large.nNewLoose
- (optional) Loose end index for the range. Default is to include up to the end of the stream. Note that the loose index may be less than, equal to, or greater than the anchor index.
-
-
Method Detail
-
associate
public void associate(TextStream poStream)
Overridden: Associate range with a new stream.This method associates the range object with the specified stream, automatically including all stream content in the range. The range object will be tracked by the new stream (if not NULL) and will no longer be tracked by its old stream.
- Parameters:
poStream
- Stream to associate with. NULL leaves the range object unassociated (and untracked).
-
associate
public void associate(TextStream poStream, int nNewAnchor, int nNewLoose)
Overridden: Associate range with a new stream, specifying range indexes.This method associates the range object with the specified stream, including the portion indicated by index numbers passed as parameters. The range object will be tracked by the new stream (if not NULL) and will no longer be tracked by its old stream.
- Parameters:
poStream
- Stream to associate with. NULL leaves the range object unassociated (and untracked).nNewAnchor
- Anchor index for the range. Will be truncated if too large.nNewLoose
- (optional) Loose end index for the range. Default is to include up to the end of the stream. Note that the loose index may be less than, equal to, or greater than the anchor index.
-
stream
public TextStream stream()
Optain a pointer to the associated stream.- Returns:
- Pointer to the associated text stream; NULL if the range currently has no stream association.
-
count
public int count()
Count the number of items in the range.- Returns:
- Number of items included in the range.
-
countText
public int countText()
Count the number of characters in the range.- Returns:
- Number of characters included in the range.
-
countField
public int countField()
Count the number of embedded fields in the range.- Returns:
- Number of embedded fields included in the range.
-
countEmbed
public int countEmbed()
Count the number of embedded objects in the range.- Returns:
- Number of embedded objects included in the range.
-
isEmpty
public boolean isEmpty()
Is the range empty?- Returns:
- TRUE if the range contains no items; FALSE if it contains at least one item.
-
position
public TextPosn position(int ePosition)
Obtain one of the range endpoints as a text position.- Parameters:
ePosition
- A member of the local PosnCode enumeration indicating which range endpoint is desired. Value must be one of POSN_ANCHOR, POSN_LOOSE, POSN_START or POSN_END.- Returns:
- A text position corresponding to the requested endpoint. Will not be associated with any stream if the range has no stream association.
-
position
public void position(int ePosition, int nNewPosition)
Change a range endpoint by index number.Given an endpoint position code and an index number, this method sets that endpoint of the range to the new index. Whether setting by anchor/loose or start/end, it is OK to set the endpoint to occur before the start point; the range will simply reorient itself. The call is ignored if the range currently has no stream association.
- Parameters:
ePosition
- A member of the local PosnCode enumeration indicating which range endpoint is desired. Value must be one of POSN_ANCHOR, POSN_LOOSE, POSN_START or POSN_END.nNewPosition
- Index number to move the endpoint to. Will be truncated if too large.
-
position
public void position(int ePosition, TextPosn oNewPosn)
Change a range endpoint by text position.Given an endpoint position code and text position object, this method sets that endpoint of the range to the new new position. Whether setting by anchor/loose or start/end, it is OK to set the endpoint to occur before the start point; the range will simply reorient itself. The call is ignored if the range currently has no stream association.
- Parameters:
ePosition
- A member of the local PosnCode enumeration indicating which range endpoint is desired. Value must be one of POSN_ANCHOR, POSN_LOOSE, POSN_START or POSN_END.oNewPosn
- New position to set for specified range endpoint. If this position is associated with a different stream, only its index number is used.
-
anchor
public TextPosn anchor()
Query the anchor position.- Returns:
- Anchor position.
-
anchor
public void anchor(int nNewIndex)
Set the anchor position by index.- Parameters:
nNewIndex
- New index for the anchor position. Will be truncated if too large.
-
anchor
public void anchor(TextPosn oNewPosn)
Set the anchor position by text position object.- Parameters:
oNewPosn
- New position for the anchor. If associated with a different stream, only its index is used.
-
loose
public TextPosn loose()
Query the loose position.- Returns:
- Loose position.
-
loose
public void loose(int nNewIndex)
Set the loose position by index.- Parameters:
nNewIndex
- New index for the loose position. Will be truncated if too large.
-
loose
public void loose(TextPosn oNewPosn)
Set the loose position by text position object.- Parameters:
oNewPosn
- New position for the loose. If associated with a different stream, only its index is used.
-
start
public TextPosn start()
Query the start position.- Returns:
- Start position.
-
start
public void start(int nNewIndex)
Set the start position by index.- Parameters:
nNewIndex
- New index for the start position. Will be truncated if too large.
-
start
public void start(TextPosn oNewPosn)
Set the start position by text position object.- Parameters:
oNewPosn
- New position for the start. If associated with a different stream, only its index is used.
-
end
public TextPosn end()
Query the end position.- Returns:
- End position.
-
end
public void end(int nNewIndex)
Set the end position by index.- Parameters:
nNewIndex
- New index for the end position. Will be truncated if too large.
-
end
public void end(TextPosn oNewPosn)
Set the end position by text position object.- Parameters:
oNewPosn
- New position for the end. If associated with a different stream, only its index is used.
-
union
public boolean union(TextRange oAdd, TextRange oResult)
Return the union of two text ranges.The union of two ranges is defined as including all items in both ranges, as well as all items between if the ranges do not overlap. Given a second range, this method performs the union operation and populates a third range with the resulf.
- Parameters:
oAdd
- Range to union with this one.oResult
- Range resulting from the union.- Returns:
- TRUE if the two ranges overlapped; FALSE if not or the ranges refer to different streams. Contiguous ranges are considered as overlapping.
-
text
public java.lang.String text(boolean bIncludeFields)
Obtain the range content as plain text.- Parameters:
bIncludeFields
- (optional) If TRUE, the operation recursively descends through embedded fields within the range to include their text as well. If FALSE (default) only text from the associated stream is returned.
-
text
public java.lang.String text()
-
text
public void text(TextStream oText)
Obtain the range content as rich text.Copy the content of the range to another stream, replacing its previous content. The destination stream retains its graphic source, which may be different from that of the associated stream. All graphics objects copied are reconciled in the destination stream's graphic source. Because this is a copy, the destination stream will get clones of any embedded objects or fields.
- Parameters:
oText
- Destination text stream. Not modified if this range has no stream association.
-
enumerateMarkers
public void enumerateMarkers(java.util.List<TextMarker> oMarkers, boolean bPositionMarkers, boolean bRangeMarkers, boolean bSubsetOnly)
Enumerate markers contained within this range.- Parameters:
oMarkers
- - Array to contain pointers to the enumerated markers. Any previous contents are removed by the call. Even though the returned array contains non-const pointers to markers, those markers are owned by AXTE and must not be deleted by the client, though the client can cache pointers to these markers provide that it participates in the marker reference counting mechanism.bPositionMarkers
- - True if all position markers at this position are to be included in the array. False (default) if position markers are to be excluded. A position marker is considered to be in the text range if it occurs at or after the start of the range, and before or at the end of the range.bRangeMarkers
- - True (default) if all range markers that span this position are to be included in the array. False if range markers are to be excluded.bSubsetOnly
- - Applies to range markers only. True to limit included range markers to those that span a (possibly complete) subset of this range; false (default) if any range marker that overlaps the this range is to be included.
-
enumerateMarkers
public void enumerateMarkers(java.util.List<TextMarker> oMarkers)
-
delete
public void delete(boolean bRaw)
Delete the contents of the range.Delete all items in the associated stream that fall within this range. Normally, there may be fix-up required after such a deletion. If there are any attribute changes in the deleted items, the last one must be preserved for text that follows the deletion. Also, if the deletion spans paragraphs, the result may be a paragraph with conflicting paragraph attributes. These are reconciled in favour of the first paragraph (if it still has text left after the delete). Alternatively, one can invoke a raw delete that doesn't do the fix-ups (not recommended, except for very special cases). This is referred to as a raw delete.
- Parameters:
bRaw
- (optional) TRUE for raw delete (see above); FALSE (default) for normal delete.
-
delete
public void delete()
-
replace
public void replace(char cReplace, boolean bRaw)
Replace the range contents with a single character.This method deletes the content of the range and then inserts a single character. When it returns, the range will contain only the inserted character.
- Parameters:
cReplace
- Character to insert.bRaw
- (optional) TRUE for raw delete; FALSE (default) for normal delete. Please see the description of raw deletion with the Delete() method.
-
replace
public void replace(char cReplace)
-
replace
public void replace(java.lang.String sReplace, boolean bRaw)
Replace the range contents with string of text.This method deletes the content of the range and then inserts a text string When it returns, the range will contain only the inserted text.
- Parameters:
sReplace
- Text to insert.bRaw
- (optional) TRUE for raw delete; FALSE (default) for normal delete. Please see the description of raw deletion with the Delete() method.
-
replace
public final void replace(java.lang.String sReplace)
-
replace
public void replace(TextStream oReplace, boolean bRaw)
Replace the range contents with rich text.This method deletes the content of the range and then inserts rich text. When it returns, the range will contain only the inserted character.
- Parameters:
oReplace
- Rich text to insert. May have a different graphic source from the associated stream. All stream content is copied. In other words, the associated stream gets clones of embedded objects and fields in the source stream.bRaw
- (optional) TRUE for raw delete; FALSE (default) for normal delete. Please see the description of raw deletion with the Delete() method.
-
replace
public final void replace(TextStream oReplace)
-
insert
public TextMarker insert(TextMarker poMarker)
Insert a range marker at the position represented by this position object.If this range is not associated with any text stream, the call is ignored.
- Parameters:
poMarker
- - Pointer to marker to insert. Note that markers are always cloned on insertion, so a copy actually gets inserted. The caller continues to retain ownership of the instance referred to by this parameter, and can delete it any time after the call.- Returns:
- Pointer to the cloned copy actually inserted in the text stream. While this is a non-const pointer, it is owned by AXTE and must not be deleted by the client, though the client can cache a pointers to this marker provide that it participates in the marker reference counting mechanism.
-
attribute
public TextAttr attribute()
Obtain the attributes in effect over the range.Returns a text attribute structure describing the attributes over the range. Any attribute that remains constant over the range will have an enabled value in the result. Any attribute that changes over the range will be disabled in the result.
- Returns:
- Text attribute object describing the attributes in effect over the range.
-
attribute
public void attribute(TextAttr oNewAttr, boolean bRaw)
Change text attributes over the range.Given a text attribute object, this method applies enabled attributes over the entire range. Disabled attributes in the given object are not changed.
- Parameters:
oNewAttr
- Attribute object with enabled attributes to apply.bRaw
- (optional) TRUE for raw change; FALSE (default) for normal change Please see the description of raw deletion with the Delete() method.
-
attribute
public final void attribute(TextAttr oNewAttr)
-
markup
public void markup(MarkupOut oMarkup, TextAttr poInitAttr, boolean bDefaultInitAttr, boolean bFlattenFields)
Convert the range contents to markup.Convert the range contents to text output in a markup language. The particular language is determined by which derived class of TextMkOut is passed. The caller may request that fields are flattened into stream content in the markup, or retained as references.
- Parameters:
oMarkup
- Output markup engine to generate the markup language.poInitAttr
- (optional) Ambient/initial attributes. This parameter, if not NULL, works in concert with the bDefaultInitAttr parameter. If that parameter indicates ambient attributes, this represents default attributes that need not be written to the markup if they apply to the stream. If it indicates initial attributes, all enabled values are written to the markup. If NULL (default value) it is ignored.bDefaultInitAttr
- (optional) If FALSE (default), parameter poInitAttr represents initial attributes to write. If TRUE, poInitAttr represents ambient attributes as described above.bFlattenFields
- Optional. If TRUE, embedded field content is written to the markup as if it was part of the range's content. If FALSE (default) field references are written to the markup.
-
markup
public void markup(MarkupIn oMarkup)
Apply markup to the range.Replace the range's current contents with rich text derived from a markup language.
- Parameters:
oMarkup
- Markup engine that processes the markup language. This must be pre-initialized with the markup source.
-
grabWord
public boolean grabWord(int eWordMode)
Extend the range to include complete words.The start of the range moves back to the start of the word containing it. The end of the range moves forward to the end of the word that contains it. If either position is not within a word or adjacent to one, it does not move.
- Returns:
- TRUE if the resulting range contains any items; FALSE if it is empty (typically occurs when you call this on an empty range that is not positioned at a word.
-
grabWord
public boolean grabWord()
-
grabLine
public boolean grabLine()
Extend the range to include complete lines.Note: the associated stream must have a text display for line operations to succeed. The start of the range moves back to the start of the line containing it. The end of the range moves forward to the end of the line that contains it.
- Returns:
- FALSE if no display; TRUE otherwise.
-
grabPara
public boolean grabPara()
Extend the range to include complete paragraphs.Note: a paragraph starts after a paragraph mark and runs until just after the next paragraph mark. If our end position is already just beyond a paragraph mark, we normally won't want to move it. The exception is when our start is also just after the same mark (empty range once tightened). In this case, we maintain the start and move the end after the next mark.
- Returns:
- Always returns TRUE;
-
tighten
public void tighten()
Try to exclude spurious attr changes from range.This method "tightens" the range around text and other objects so that attribute changes at the extremities don't distort what gets returned by an Attribute() call.
If the range is empty, we do the following special handling: If the range is between attribute changes, we leave it alone (they were probably just inserted). Otherwise, we test to see if we're at the start of the line. If so, move both positions over any leading attribute changes so that we show the attributes in effect at the start of the line. Otherwise, we move both positions back over all attribute changes, to be consistent with position user item handling.
-
charPosition
public TextPosnBase charPosition(int lIndex)
Create a position with the associated stream, given a character index.Return text position object that is associated with the same stream as this object, but is positioned immediately after the Nth character, where N is passed as a parameter.
- Parameters:
lIndex
- Character position to search for.- Returns:
- Resulting position object.
-
charRange
public TextRange charRange(int lStart, int lLength)
Create a range with the associated stream, given a character index and length.Return text range object that is associated with the same stream as this object. The range will start after the Nth character and include M characters, where N and M are passed as parameters.
- Parameters:
lStart
- Character position to search for.lLength
- Number of characters to include in the range.- Returns:
- Resulting range object.
-
getSelectionRectangles
public boolean getSelectionRectangles(java.util.List<Rect> oRectangles)
Obtain the rectangle(s) in the laid-out text corresponding to this range.A single range might yield multiple rectangles if it spans multiple lines or there is bidirectional text. Note: This call makes sense only for single frame displays. In a multi-frame environment it makes more sense to call TextFrame::GetSelectionRectangles() on each frame, in order to get rectangles that are positioned relative to their frame.
- Parameters:
oRectangles
- - Array to receive the rectangles.- Returns:
- True if any rectangles were found; false otherwise. This method could return false if the range has no stream associated, the stream has no display, or the range is degenerate.
-
copyFrom
public void copyFrom(TextRange oSource)
Assignment operator.Copy the entire content of the source range object including stream association and indexes.
- Parameters:
oSource
- Source range object to copy.
-
equals
public boolean equals(java.lang.Object object)
Equality comparison.Two text ranges are considered equal if they are associated with the same stream and have the same pair of index numbers. Note that the current implementation is rather crude in that it still compares indexes even when both streams are NULL.
- Overrides:
equals
in classjava.lang.Object
- Parameters:
object
- Range to compare against.- Returns:
- TRUE if the ranges are equal; FALSE if not.
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
notEqual
public boolean notEqual(TextRange oCompare)
Inequality comparison.Two text ranges are considered unequal if they are associated with different stream and have different index numbers. Note that the current implementation is rather crude in that it still compares indexes even when both streams are NULL.
- Parameters:
oCompare
- Range to compare against.- Returns:
- TRUE if the ranges are not equal; FALSE if they are equal.
-
-