Package com.adobe.xfa.text

Class TextMarker

  • public abstract class TextMarker
extends java.lang.Object

    • Field Detail

      • SPLIT_NONE

        public static final int SPLIT_NONE
        Conditions on which a marker instance should be split.

        Some range marker derivations will need to be split into two separate markers when insertions occur or around the presence of particular content. This enumeration describes that splitting.

        SPLIT_NONE -The range marker is never automatically split.

        SPLIT_PARA - The marker is to be split into separate markers around paragraph marks.

        SPLIT_INSERT - The marker is to be split into separate markers on any insertion within the marker's range.

        SPLIT_INSERT_WRAP - The marker is to be split into separate markers on any insertion within the marker's range. In addition, the marker will be split if word-wrapping causes its range to spread over two or more lines.

        Superficially, a value of SPLIT_PARA may appear to be a specialization of SPLIT_INSERT. However, they are mutually exclusive settings that have different semantics for certain operations. For more information, please see the external specification.

        See Also:
        Constant Field Values

      • SPLIT_REASON_UNKNOWN

        public static final int SPLIT_REASON_UNKNOWN
        Reason that a marker is about to be split.

        This enumeration is intended primarily for use in the OnSplit() call-back described later. Enumeration values have the following meanings:

        SPLIT_REASON_UNKNOWN - This value is for internal purposes and will never be passed to the call-back. It should not be used by the client.

        SPLIT_REASON_FORCED - A split was forced by the client.

        SPLIT_REASON_INSERT_EMBED - An embedded object has been inserted within the marker's range.

        SPLIT_REASON_INSERT_FIELD - A nested field has been inserted within the marker's range.

        SPLIT_REASON_INSERT_PARA_BREAK - A paragraph break has been inserted within the marker's range (and the marker has a split state of SPLIT_INSERT).

        SPLIT_REASON_INSERT_TEXT_PLAIN - Plain text has been inserted within the marker's range.

        SPLIT_REASON_INSERT_TEXT_RICH - Potentially rich text has been inserted within the marker's range. Note that the two text insertion types simply mirror the AXTE API calls. Text passed to a rich text API method may be plain.

        SPLIT_REASON_PARA_MARKER - This marker has a split state of SPLIT_PARA and it needs to be split around a paragraph break.

        SPLIT_REASON_WORD_WRAP - The marker is being split due to a word-wrapping operation.

        Note that split reasons SPLIT_REASON_WORD_WRAP and those starting with SPLIT_REASON_INSERT apply to SPLIT_INSERT markers only. They are all considered variations on insertion.

        See Also:
        Constant Field Values

      • SPLIT_REASON_INSERT_EMBED

        public static final int SPLIT_REASON_INSERT_EMBED
        See Also:
        Constant Field Values

      • SPLIT_REASON_INSERT_FIELD

        public static final int SPLIT_REASON_INSERT_FIELD
        See Also:
        Constant Field Values

      • SPLIT_REASON_INSERT_PARA_BREAK

        public static final int SPLIT_REASON_INSERT_PARA_BREAK
        See Also:
        Constant Field Values

      • SPLIT_REASON_INSERT_TEXT_PLAIN

        public static final int SPLIT_REASON_INSERT_TEXT_PLAIN
        See Also:
        Constant Field Values

      • SPLIT_REASON_INSERT_TEXT_RICH

        public static final int SPLIT_REASON_INSERT_TEXT_RICH
        See Also:
        Constant Field Values

      • SPLIT_REASON_PARA_MARKER

        public static final int SPLIT_REASON_PARA_MARKER
        See Also:
        Constant Field Values

    • Method Detail

      • isPositionMarker

        public boolean isPositionMarker()
        Indicate whether this marker is a position marker.
        Returns:
        True if this is a position marker; false if it is a range marker or not contained in any stream.

      • isRangeMarker

        public boolean isRangeMarker()
        Indicate whether this marker is a range marker.
        Returns:
        True if this is a range marker; false if it is a position marker or not contained in any stream.

      • getAutoCoalesce

        public boolean getAutoCoalesce()
        Indicate whether this marker can be automatically coalesced with others during editing. For more information, please see method SetAutoCoalesce().
        Returns:
        True if coalescing is allowed for this marker; false if not.

      • getAutoRemove

        public boolean getAutoRemove()
        Return the current automatic removal state. For more information, please see method SetAutoRemove().
        Returns:
        True if automatic removal is enabled for this marker; false if not.

      • isParaMarker

        public boolean isParaMarker()
        Query whether this is a paragraph marker. For more information, please see method SetParaMarker(). For more information, please see method SetParaMarker().
        Returns:
        True if this is a paragraph marker; false if not.

      • getSplitState

        public int getSplitState()
        Return the current split state.
        Returns:
        The current split state for this marker. See the description of the SplitStateEnum enumeration for more information.

      • getPosition

        public TextPosn getPosition()
        Return the position of this marker in its containing stream. This call is valid only for position markers that are contained in text streams.
        Returns:
        Position of this marker in its containing stream. If the marker is not in any stream or is a range marker, the returned position will be invalid (i.e., its stream will be null).

      • getRange

        public TextRange getRange()
        Return the range of this marker representing its span in the containing stream. This call is valid only for range markers that are contained in text streams.
        Returns:
        Range of this marker in its containing stream. If the marker is not in any stream or is a position marker, the returned range will be invalid (i.e., its stream will be null).

      • remove

        public void remove()
        Remove this marker from the containing stream. If the marker is not in a stream, nothing happens. After this call, the stream will have released its reference on the marker. If the client wishes to hang on to the marker's pointer, it must increase the marker's reference countideally when it first copied the pointer.

      • forceSplit

        public TextMarker forceSplit​(int nSplitStart,
                             int nSplitEnd,
                             int eReason)
        Forces the range marker to be split if it overlaps the given span.

        This call makes sense only for markers that are within text streams. The span is specified as two indexes into the marker's text stream. The method behaves in one of five ways, depending on the relationship between the span and the marker's range:

        If the span does not overlap the marker's range, the call is ignored.

        If the span overlaps the start of the marker's range but not the end, the marker's range is truncated at its start to exclude the overlap.

        If the span overlaps the end of the marker's range but not the start, the marker's range is truncated at its end to exclude the overlap.

        If the span falls completely inside the marker-s range--overlapping neither the start nor the end--the marker is split. Upon return, this marker will correspond to the portion of its original range before the span and the clone will correspond to the portion after.

        If the span is a (possibly exact) superset of the marker's range, the split operation treats the marker in the same way a complete deletion of the marker's text would. The marker is removed from the stream and possibly deleted.

        This method will trigger a call on the marker's OnSplit() event handler if a true split (fourth bullet above) occurs.

        Parameters:
        nSplitStart - - Indicates the start of the split span. This parameter indicates the future end of this marker's range if a true split occurs.
        nSplitEnd - - Indicates the end of the split span. This parameter indicates the future end of this marker's range if a true split occurs.
        eReason - - Reason for the split. It is recommended that the client not override the default of SPLIT_REASON_FORCED.
        Returns:
        New marker instance created if a true split occurred. If null, there was no split.

      • forceCoalesce

        public boolean forceCoalesce​(TextMarker poOther)
        Coalesce this marker with another one.

        Common usage is to coalesce logically adjacent markers, but the client may call this method on disjoint markers as well. Upon successful return, this markers range is extended to include the union of both markers ranges, as well as any intervening content if the markers are not contiguous.

        In order to be coalesced, the following conditions must be met:

        • The two markers refer to the same text stream.
        • The two markers have the same type, as reported by the Obj::Type() virtual method.
        • Both markers have the same values for auto coalesce, auto removal, paragraph state and split state. Note that two markers that disallow coalescing can be explicitly coalesced with this method.

        This method will trigger a call on the marker's OnCoalesce() event handler if the above conditions are met. The implementation of that event handler may prevent the operation from occurring.

        AXTE dispatches the marker being coalesced with this one, either removing it from the stream (if auto-remove is enabled) or shrinking it to a zero-length range at the end of the coalesced range.

        Parameters:
        poOther - - Pointer to marker to be coalesced with this one.
        Returns:
        True if the operation was successful; false if the conditions were not met or the marker prevented the operation in the OnCoalesce() event handler.

      • cloneMarker

        public abstract TextMarker cloneMarker()
        Create a copy of this marker. Implemented by the derived class. The created instance must be of the same class as this object and a deep copy must be performed.
        Returns:
        A pointer to the cloned copy. The copy is owned by AXTE and must not be deleted by the client.

      • onAttributeChange

        public void onAttributeChange​(int nStart,
                              int nEnd,
                              TextAttr poAttr)
        Notifies a range marker that an attribute change overlaps the marker's range. This method is called before the attribute change is applied. The default implementation does nothing.
        Parameters:
        nStart - - Start of the attribute change's range. This range overlaps the marker's range by some amount, but it may or may not include all of the marker's text.
        nEnd - - End of the attribute change's range.
        poAttr - - Pointer to new attributes that are about to be applied.

      • onClick

        public boolean onClick​(TextPosnBase oPosition)
        Handle mouse click event in this range marker. The derived class can override this method if it needs to know about mouse clicks.
        Parameters:
        oPosition - - Position within parent stream where click occurred.
        Returns:
        True if the derived class handled the click and wishes to suppress further click processing. AXTE will call OnClick() for each range marker that spans the click position until one returns true. If none return true, AXTE will move the caret to the click position. The default implementation simply returns false.

      • onCoalesce

        public boolean onCoalesce​(TextMarker oOther)
        Notify the marker that it is about to be coalesced with another.

        AXTE will call this method on a marker instance as a result of a call to ForceCoalesce(). In addition, it will call this method after an editing operation has occurred, if all the following conditions are met:

        • An editing operation (typically a deletion) has caused this marker to become adjacent to the other one, in logical order
        • This marker comes first in logical text order
        • Both markers allow automatic coalescing virtual method
        • The conditions outlined in the ForceCoalesce() method are met

        This is a notification only; the marker derivation may need to update its own data structures to represent the coalesced result, but AXTE updates this marker's range. AXTE also dispatches the adjacent marker, either removing it from the stream (if auto-remove is enabled) or shrinking it to a zero-length range at the end of the coalesced range. Zero-length markers are not eligible for future automatic coalescing operations.

        The marker's implementation can prevent the coalescing from occurring through the return value of this notification method.

        Parameters:
        oOther - - Adjacent marker to be coalesced with this one.
        Returns:
        True if the derived class wants the coalesce operation to occur; false to suppress the coalescing of the two markers. The default implementation simply returns true.

      • onDeleteContent

        public void onDeleteContent​(int nStart,
                            int nEnd)
        Notifies a range marker that part or all of its content is about to be deleted. This method is called before the deletion occurs. The default implementation does nothing.
        Parameters:
        nStart - - Start of the deletion range. This range overlaps the marker's range by some amount, but it may or may not include all of the marker's text.
        nEnd - - End of the deletion range.

      • onRemove

        public void onRemove​(boolean bEditOnly)
        Notifies the marker that it is about to be removed from its containing text stream and deleted. This can occur as a result of one of the following conditions:
        • The marker has automatic removal enabled and a text editing operation within the stream has triggered the removal of the marker.
        • The containing stream is being destroyed.
        After this call, the stream will have released its reference on the marker. If the client wishes to hang on to the marker's pointer, it must increase the marker's reference count--ideally when it first copied the pointer.
        Parameters:
        bEditOnly - - True if this is an editing operation that is about to remove the auto-delete marker. False if the containing stream is being deleted.

      • onSplit

        public TextMarker onSplit​(int nSplitStart,
                          int nSplitEnd,
                          int eReason)
        Notifies the marker that it is about to be split.

        AXTE will call this method when splitting a marker with a split state of either SPLIT_PARA or SPLIT_INSERT. The term split text refers to the text that is not part of either resulting marker after the split occurs. For a SPLIT_INSERT marker, the split text one of the following:

        • The inserted text if an insertion caused the split
        • The sub-range of text that gets the new attribute value if an attribute change caused the split
        • An empty span at the line break point if word-wrapping caused the split

        For a SPLIT_PARA marker, it is a single paragraph break--even if that paragraph break was part of a larger insertion.

        This method is called after the insertion, but before any splitting has occurred. In other words, this marker's range will have been expanded by the number of items in the split text. At the time of the call, it can be thought of as covering three sub-spans:

        • The portion before the split text
        • The split text
        • The portion after the split text

        Parameters to OnSplit() delimit the extent of the split text within the larger marker range.

        The implementation normally creates a new marker instance--much like Clone()--and return it to AXTE. The implementation can use the given parameters for informational purposes, but it is not responsible for adjusting the marker's range or setting the clone's range. AXTE will take care of all of that. The default implementation simply calls Clone().

        The marker can prevent the split from occurring by returning a null pointer in this method. In such a case, the marker will simply remain in its expanded state, spanning the three portions mentioned above. Preventing the split should occur only in specialized circumstances, for example, a text run can handle the insertion of plain text without being split.

        After OnSplit() returns, AXTE will adjust this marker's range to cover the span before the inserted text. It will attach the clone to the span after the inserted text. If this is a SPLIT_PARA marker and there are multiple paragraph breaks, AXTE will split the original marker at the original break. The clone will temporarily cover the remainder of the inserted text--including remaining paragraph breaks--as well as any text from the original marker that occurs after the insertion. AXTE will then iterate on the next paragraph break, calling OnSplit() on the clone, and so on.

        Parameters:
        nSplitStart - - Indicates the start of the split text. This parameter indicates the future end of this marker's range.
        nSplitEnd - - Indicates the end of the split text. This parameter indicates the future start of the new marker's range.
        eReason - - Reason the marker is being split. Please see the SplitReasonEnum definition above for more information.
        Returns:
        New marker instance to use for the portion after the split text; null pointer if the marker is not to be split.

      • onTruncate

        public boolean onTruncate​(int nSplitStart,
                          int nSplitEnd,
                          boolean bEnd,
                          int eReason)
        Notifies the marker that its range has expanded due to an insertion and is about to be truncated. This is really just an extension of the OnSplit() call-back that handles insertions at the start or end of the marker's range. When the call is made, the insertion has occurred and the marker's range is temporarily expanded to include the inserted text. The marker implementation has the choice of letting AXTE truncate the range to exclude the inserted text or leave the range extended. The marker implementation may want to hang on to the inserted text.
        Parameters:
        nSplitStart - - Indicates the start of the split text.
        nSplitEnd - - Indicates the End of the split text.
        bEnd - - True if the range truncation is to occur at the marker range end; false if it is to occur at the range start.
        eReason - - Reason the marker's range is being truncated. Please see the TextMarker::SplitReasonEnum definition above for more information.
        Returns:
        True if the marker's range is to be truncated; false if it is to remain including the inserted text.