Package com.adobe.xfa.text

Class TextRange

java.lang.Object
com.adobe.xfa.text.TextRange
Direct Known Subclasses:
TextSelection
public class TextRange extends Object

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    POSN_ANCHOR
     
    static final int
    POSN_END
     
    static final int
    POSN_LOOSE
     
    static final 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

    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.
    final 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(List<TextMarker> oMarkers)
     
    void
    enumerateMarkers(List<TextMarker> oMarkers, boolean bPositionMarkers, boolean bRangeMarkers, boolean bSubsetOnly)
    Enumerate markers contained within this range.
    boolean
    equals(Object object)
    Equality comparison.
    boolean
    getSelectionRectangles(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.
    final void
    replace(TextStream oReplace)
     
    void
    replace(TextStream oReplace, boolean bRaw)
    Replace the range contents with rich text.
    final void
    replace(String sReplace)
     
    void
    replace(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.
    String
    text()
     
    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.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • 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 Details

    • 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 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 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(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(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(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(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(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(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 class Object
      Parameters:
      object - Range to compare against.
      Returns:
      TRUE if the ranges are equal; FALSE if not.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class 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.