Package com.adobe.xfa.text

Class TextRange

  • Direct Known Subclasses:
    TextSelection
    public class TextRange
extends java.lang.Object

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

      • Methods inherited from class java.lang.Object

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

    • 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 class java.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 class java.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.