Package com.adobe.xfa.text

Class TextPosnBase

  • Direct Known Subclasses:
    TextPosn
    public class TextPosnBase
extends TextMarkupBase

    Class TextPosnBase represents a position in a particular text stream.

    Positions occur between items (typically characters) in the stream, as well as before the first item and after the last. A position has an index number; zero corresponds to the position at the start of the stream and values increment from there. Thus, the last position index is equal to the total number of items in the stream.

    Technically there are actually two positions between each pair of items. Though they share the same index number, one comes before the other. These are referred to as a before position and an after position. When an insertion happens between the two characters, the before position does not advance while the after one does. The before and after distinction is largely an internal feature of AXTE.

    A text position also has an affinity to one of the two surrounding items. Affinity is independent from the notion of before/after. For example a before position might have an affinity to the character that comes after. Affinity is used only in resolving ambiguous positions in bi-directional text. It is normally used only within AXTE. The default affinity is to the character that comes after the position.

    With the addition of support for bidirectional text, the text position object now carries a directionality flag. The RTL (right to left) flag is true if the position object was populated in an operation that processed RTL text. This flag is normally not used by application-level software. Typically only AXTE uses it, to "remember" state for ambiguous positions.

    An instance of this class points into an instance of a text stream, but that stream has no knowledge of the TextPosnBase objects looking at it. Modifying the text stream may cause some or all of those objects to become invalid. Typically one uses class TextPosnBase for short-term stream manipulation, and derived class TextPosition for longer-term access to the text stream.

    This class supports a number of text unit movement operations, for example next word or previous character. The concepts of next and previous can be interpred in either a logical or a visual sense. Logical moves apply to the underlying text stream data. Any Next operation increases the position's stream index, while any Previous operation decreases it. For visual moves, Next implies to the right and Previous to the left. In right-to-left text, left is synonomous with decreasing index and right with increasing index. In right-to-left text, left corresoponds to increasing index and right corresponds to decreasing index. The caller choses logical or visual mode in the parameter list of movement operations. For visual moves to be effective, there must be a text display associated with the stream.

    For more information, please see the extenral documentation.

    • Field Detail

      • POSN_AFTER

        public static final int POSN_AFTER
        Position type enumeration.

        As mentioned in the class description, each position object can be designated as a before position or an after position. These enumeration values are used with methods that manipulate the position type.

        • POSN_AFTER: Designates an "after" position. Insertions at this position will cause the position to move, so that it stays after the insertions.
        • POSN_BEFORE: Designates a "before" position. Insertions at this position will not change position, so that it remains before the insertions.
        See Also:
        Constant Field Values

      • AFFINITY_AFTER

        public static final int AFFINITY_AFTER
        Affinity enumeration.

        As mentioned in the class description, each position object has an affinity to either the character that comes before in logical order or the one that comes after. The affinity is used to determine where to place the cursor when a direction change at the position causes the glyphs for the surrounding characters to be disjoint.

        • AFFINITY_AFTER: The position has an affinity to the character that comes after.
        • AFFINITY_BEFORE: The position has an affinity to the character that comes before.
        See Also:
        Constant Field Values

      • WORD_MODE_LEGACY

        public static final int WORD_MODE_LEGACY
        Word positioning modes.

        AXTE was originally developed with a relatively simple sense of word boundaries. Essentially these occured only between space and non-space characters. With the advent of language-related features such as spelling and hyphenation, more sophisticated word analysis became necessary.

        This enumeration has values that can be used in word-oriented methods of a number of AXTE classes to specify the type of word handling required.

        • WORD_MODE_LEGACY: Legacy word handling; word breaks occur between space and non-space characters only. This is the current API default, in order to ensure backward compatibility.
        • WORD_MODE_ALGORITHMIC: Apply the Unicode UAX29 algorithm to distinguish more accurate word boundaries, notably between letters and punctuation.
        • WORD_MODE_LOCALE_SENSITIVE: Use the locale for further refinement of word processing algorithms. This would be useful in a language like Thai, where a dictionary is required to find word breaks. Note: this setting is not yet implemented, and behaviour reverts to WORD_MODE_ALGORITHMIC if it is selected.
        See Also:
        Constant Field Values

      • WORD_MODE_LOCALE_SENSITIVE

        public static final int WORD_MODE_LOCALE_SENSITIVE
        See Also:
        Constant Field Values

    • Constructor Detail

      • TextPosnBase

        public TextPosnBase()
        Default constructor.

        The position is not initially associated with any stream.

      • TextPosnBase

        public TextPosnBase​(TextPosnBase oSource)
        Copy constructor.

        Copy all contents of the source position, including stream association, index and before/after state.

        Parameters:
        oSource - Source position object to copy.

      • TextPosnBase

        public TextPosnBase​(TextStream poNewStream,
                    int nNewIndex,
                    int eNewPosn)
        Constructor with stream, index and optional position type.

        Construct a position object associated with the given stream and optional position type. The position is placed at the specified index.

        Parameters:
        poNewStream - Stream to associate with. NULL creates a position object with no initial association.
        nNewIndex - Index number for the position. Will be truncated if too large.
        eNewPosn - (optional) Position type to use for the object. Default is POSN_AFTER.

      • TextPosnBase

        public TextPosnBase​(TextStream poNewStream,
                    int nNewIndex)

      • TextPosnBase

        public TextPosnBase​(TextStream poNewStream)

    • Method Detail

      • associate

        public void associate​(TextStream poNewStream,
                      int nNewIndex,
                      int eNewPosn)
        Overridable: Associate position with a new stream and index.

        This method associates the position object with the specified stream, at the specified index position.

        Parameters:
        poNewStream - Stream to associate with. NULL leaves the position object unassociated (and untracked).
        nNewIndex - Index of this position in the new stream. If the value is too large, it is truncated.
        eNewPosn - (optional) Position type to use for the object. Default is POSN_AFTER.

      • associate

        public void associate​(TextStream poNewStream,
                      int nNewIndex)

      • associate

        public void associate​(TextStream poNewStream)

      • index

        public int index()
        Return the index number of this position within its stream.
        Returns:
        This position's index in its associated stream.

      • index

        public void index​(int nNewIndex)
        Change the position's index number. Move the position to a new index number. The position remains associated with the same stream.
        Parameters:
        nNewIndex - - New index within the associated stream. If the value is too large, it is truncated.

      • position

        public int position()
        Obtain the position type (before or after) of this position.
        Returns:
        POSN_BEFORE if this is a before position; POSN_AFTER if this is an after position.

      • position

        public void position​(int ePosition)
        Change the position type (before/after) of this position.
        Parameters:
        ePosition - POSN_BEFORE changes to a before position; POSN_AFTER changes to an after position.

      • affinity

        public int affinity()
        Obtain the affinity of this position.
        Returns:
        AFFINITY_BEFORE if this position associates with the item before; AFFINITY_AFTER if it associates with the one after.

      • affinity

        public void affinity​(int eAffinity)
        Change the position type (before/after) of this position.
        Parameters:
        eAffinity - AFFINITY_BEFORE if this position is to associate with the item before; AFFINITY_AFTER to associate with the one after.

      • isRTL

        public boolean isRTL()
        Query whether the position was populated as a result of processing RTL text.

        This method exists primarily for internal AXTE use and tends to have a meaningful value only in interactive applications.

        Returns:
        TRUE if the position was populated as a result of processing RTL text; FALSE otherwise.

      • setRTL

        public void setRTL​(boolean bRTL)
        Change the position object's RTL flag.

        This method exists primarily for internal AXTE use. The RTL flag tends to have a meaningful value only in interactive applications.

        Parameters:
        bRTL - TRUE if the position was populated as a result of processing RTL text; FALSE otherwise.

      • enumerateMarkers

        public void enumerateMarkers​(java.util.List<TextMarker> oMarkers,
                             boolean bPositionMarkers,
                             boolean bRangeMarkers)
        Enumerate markers at this position.
        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 (default) if all position markers at this position are to be included in the array. False if position markers are to be excluded.
        bRangeMarkers - - True if all range markers that span this position are to be included in the array. False (default) if range markers are to be excluded. A range marker spans the position if it starts before or at the position, and ends at or after the position.

      • first

        public void first​(boolean bVisual)
        Move to the first position in the associated stream. Note: the first position is not the same as position zero. This method positions before the first non-attribute item in the stream. In an interactive application we do not want the user inserting text before their attributes.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.

      • first

        public void first()

      • last

        public void last​(boolean bVisual)
        Move to the last position in the associated stream.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.

      • last

        public void last()

      • next

        public int next​(boolean bTestOnly)
        Move to the next position in the associated stream. This method advances the position in the stream. In doing so, the position passes over a single item, whose type is returned.
        Parameters:
        bTestOnly - - (optional) If TRUE, the position simply returns the next item type and does not actually move. If FALSE (default), the position does move.
        Returns:
        Item type of the item passed over. Returns TextItem.UNKNOWN if at the last position.

      • next

        public int next​(int eNullFrameMode)

      • next

        public int next()

      • next

        public int next​(int eNullFrameMode,
                boolean bTestOnly)

      • nextData

        public int[] nextData​(boolean bTestOnly)

      • prev

        public int prev​(boolean bTestOnly)
        Move to the previous position in the associated stream. This method backs up the position in the stream. In doing so, the position passes over a single item, whose type is returned.
        Parameters:
        bTestOnly - - (optional) If TRUE, the position simply returns the previous item type and does not actually move. If FALSE (default), the position does move.
        Returns:
        Item type of the item passed over. Returns TextItem.UNKNOWN if at position zero.

      • prev

        public int prev​(int eNullFrameMode)

      • prev

        public int prev()

      • prev

        public int prev​(int eNullFrameMode,
                boolean bTestOnly)

      • prevData

        public int[] prevData​(boolean bTestOnly)

      • nextChar

        public int nextChar​(boolean bTestOnly)
        Obtain the next character. Scan forward from the current position until a character (or end of stream) is encountered. Return the character value.
        Parameters:
        bTestOnly - - (optional) If TRUE, this position remains unchanged after the call. If FALSE (default), the position is advanced so that it falls immediately after the character returned.
        Returns:
        Character value. Null character if no characters after the position.

      • nextChar

        public int nextChar()

      • prevChar

        public int prevChar​(boolean bTestOnly)
        Obtain previous next character. Scan backward from the current position until a character (or start of stream) is encountered. Return the character value.
        Parameters:
        bTestOnly - - (optional) If TRUE, this position remains unchanged after the call. If FALSE (default), the position is backed up so that it falls immediately before the character returned.
        Returns:
        Character value. Null character if no characters before the position.

      • prevChar

        public int prevChar()

      • nextField

        public TextField nextField​(boolean bTestOnly)
        Obtain the next embedded field object. Scan forward from the current position until an embedded field object (or end of stream) is encountered. Return the embedded field pointer.
        Parameters:
        bTestOnly - - (optional) If TRUE, this position remains unchanged after the call. If FALSE (default), the position is advanced so that it falls immediately after the embedded field object.
        Returns:
        Embedded field pointer. NULL if no embedded fields after the position.

      • prevField

        public TextField prevField​(boolean bTestOnly)
        Obtain previous next embedded field object. Scan backward from the current position until an embedded field object (or start of stream) is encountered. Return the embedded field pointer.
        Parameters:
        bTestOnly - - (optional) If TRUE, this position remains unchanged after the call. If FALSE (default), the position is backed up so that it falls immediately before the embedded field object.
        Returns:
        Embedded field pointer. NULL if no embedded fields before the position.

      • nextEmbed

        public TextEmbed nextEmbed​(boolean bTestOnly)
        Obtain the next embedded object. Scan forward from the current position until an embedded object (or end of stream) is encountered. Return the embedded object pointer.
        Parameters:
        bTestOnly - - (optional) If TRUE, this position remains unchanged after the call. If FALSE (default), the position is advanced so that it falls immediately after the embedded object.
        Returns:
        Embedded object pointer. NULL if no embedded objects after the position.

      • prevEmbed

        public TextEmbed prevEmbed​(boolean bTestOnly)
        Obtain previous next embedded object. Scan backward from the current position until an embedded object (or start of stream) is encountered. Return the embedded object pointer.
        Parameters:
        bTestOnly - - (optional) If TRUE, this position remains unchanged after the call. If FALSE (default), the position is backed up so that it falls immediately before the embedded object.
        Returns:
        Embedded object pointer. NULL if no embedded objects before the position.

      • nextAttr

        public TextAttr nextAttr​(boolean bTestOnly)
        Obtain the next attribute change. Scan forward from the current position until an attribute change (or end of stream) is encountered. Return the attribute object.
        Parameters:
        bTestOnly - - (optional) If TRUE, this position remains unchanged after the call. If FALSE (default), the position is advanced so that it falls immediately after the attribute object returned.
        Returns:
        attribute object pointer. NULL if no attribute changes after the position.

      • prevAttr

        public TextAttr prevAttr​(boolean bTestOnly)
        Obtain the previous attribute change. Scan backward from the current position until an attribute change (or start of stream) is encountered. Return the attribute object.
        Parameters:
        bTestOnly - - (optional) If TRUE, this position remains unchanged after the call. If FALSE (default), the position is backed up so that it falls immediately before the attribute object returned.
        Returns:
        attribute object pointer. NULL if no attribute changes before the position.

      • nextUserPosn

        public boolean nextUserPosn​(boolean bVisual)
        Advance one user position. A user position is described as one where a caret may be placed in an interactive application. Attribute items are transparent to user positions. This method advances by one user position.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.
        Returns:
        TRUE if the object moved to a new user position; FALSE if it was already at the last user position in the stream or there is no displey.

      • nextUserPosn

        public boolean nextUserPosn()

      • prevUserPosn

        public boolean prevUserPosn​(boolean bVisual)
        Back up one user position. A user position is described as one where a caret may be placed in an interactive application. Attribute items are transparent to user positions. This method backs up to the previous user position.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.
        Returns:
        TRUE if the object moved to a new user position; FALSE if it was already at the first user position in the stream or there is no display.

      • prevUserPosn

        public boolean prevUserPosn()

      • nextUserPosnType

        public int nextUserPosnType​(boolean bVisual)
        Advance one user position; return item type. A user position is described as one where a caret may be placed in an interactive application. Attribute items are transparent to user positions. This method advances by one user position and returns the (user) item type stepped over.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.
        Returns:
        Item type if the object moved to a new user position; TextItem.UNKNOWN if it was already at the last user position in the stream.

      • nextUserPosnType

        public int nextUserPosnType()

      • nextUserPosnType

        public int nextUserPosnType​(int eNullFrameMode)

      • nextUserPosnType

        public int nextUserPosnType​(int eNullFrameMode,
                            boolean bVisual)

      • nextUserPosnTypeData

        public int[] nextUserPosnTypeData​(boolean bVisual)

      • prevUserPosnType

        public int prevUserPosnType​(boolean bVisual)
        Back up one user position; return item type. A user position is described as one where a caret may be placed in an interactive application. Attribute items are transparent to user positions. This method backs up to the previous user position and returns the (user) item type stepped over.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.
        Returns:
        Item type if the object moved to a new user position; TextItem.UNKNOWN if it was already at the first user position in the stream.

      • prevUserPosnType

        public int prevUserPosnType()

      • prevUserPosnType

        public int prevUserPosnType​(int eNullFrameMode)

      • prevUserPosnType

        public int prevUserPosnType​(int eNullFrameMode,
                            boolean bVisual)

      • prevUserPosnTypeData

        public int[] prevUserPosnTypeData​(boolean bVisual)

      • nextWord

        public boolean nextWord​(boolean bVisual,
                        int eWordMode)
        Position at the start of the next word. This method scans the associated stream from this position for the start of the next word. If the position is in a word (even at its start), the current word is ignored. If the position is already in or after the last word of the stream, it advances to the last user position.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.
        eWordMode - - Word positioning mode (see the enumeration described in class TextPosnBase).
        Returns:
        TRUE if the position moved; FALSE if it was already at the last user position in the stream or there is no display.

      • nextWord

        public boolean nextWord​(boolean bVisual)

      • nextWord

        public boolean nextWord()

      • prevWord

        public boolean prevWord​(boolean bVisual,
                        int eWordMode)
        Position at the start of the previous word. This method scans the associated stream from this position for the start of the previous word. If the position is in a word (but not at its start), it moves to the start of the current word. If the position is already before the first word of the stream, it moves to the first user position.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.
        eWordMode - - Word positioning mode (see the enumeration described in class TextPosnBase).
        Returns:
        TRUE if the position moved; FALSE if it was already at the first user position in the stream or there is no display.

      • prevWord

        public boolean prevWord​(boolean bVisual)

      • prevWord

        public boolean prevWord()

      • nextLine

        public boolean nextLine()
        Move to the start of the next line. Note: the associated stream must have a text display for line operations to succeed. This method moves to the start of the next line in the stream. If already positioned on the last line, this method moves to the end of the stream.
        Returns:
        TRUE if the position moved. FALSE if there is no display or the position was already at the last user position in the stream.

      • prevLine

        public boolean prevLine()
        Move to the start of the current or previous line. Note: the associated stream must have a text display for line operations to succeed. This method finds the previous start-of-line. If the position is not at the start of a line, it is moved to the start. Otherwise it is moved to the start of the previous line.
        Returns:
        TRUE if the position moved. FALSE if there is no display or the position was already at the first user position in the stream.

      • nextPara

        public boolean nextPara()
        Move to the start of the next paragraph. Advance the position such that it is positioned immediately after the next paragraph break in the associated stream.
        Returns:
        TRUE if another paragraph break was found; FALSE if the position was already in or after the last paragraph in the stream.

      • prevPara

        public boolean prevPara()
        Move to the start of the current or previous paragraph. Advance the position such that it is positioned immediately after the previous paragraph break in the associated stream. If the position is already at the start of a paragraph, it moves to the start of the previous paragraph. Otherwise, it moves to the start of the current paragraph.
        Returns:
        TRUE if the position moved (even if no previous paragraph); FALSE if already at the first user position in the stream.

      • wordStart

        public void wordStart​(int eWordMode)
        Move to the start of the current word. Note: this method assumes the position is within a word or immediately adjacent to it. If the position is in white space, it does not move. The position moves to the start of the current word. If already at the start, the position does not move.
        Parameters:
        eWordMode - - Word positioning mode (see the enumeration described in class TextPosnBase).

      • wordStart

        public void wordStart()

      • wordEnd

        public void wordEnd​(int eWordMode)
        Move to the end of the current word. Note: this method assumes the position is within a word or immediately adjacent to it. If the position is in white space, it does not move. The position moves to the end of the current word. If already at the end, the position does not move.
        Parameters:
        eWordMode - - Word positioning mode (see the enumeration described in class TextPosnBase).

      • wordEnd

        public void wordEnd()

      • paraStart

        public void paraStart()
        Move to the start of the current paragraph. The position moves to the start of the current paragraph (i.e., immediately after the previous paragraph mark. If already at the paragraph start, the position does not move. If there are no paragraph marks between the position and the start of the stream, it moves to the first user position.

      • paraEnd

        public void paraEnd()
        Move to the end of the current paragraph. The position moves to the end of the current paragraph (i.e., immediately before the next paragraph mark. If already at the paragraph end, the position does not move. If there are no paragraph marks between the position and the end of the stream, it moves to the last user position.

      • up

        public boolean up()
        Move up one line. Note: the associated stream must have a text display for line operations to succeed. This method moves the position up one line in the displayed text. If already on the first line, the position does not move. Upward and downward movement attempts to reestablish the caret X co-ordinate as close as possible to its location on the old line. Repeated calls to up/down methods use the original position, so that moving through a short line doesn't truncate the target X co-ordinate.
        Returns:
        TRUE if the position moved up; FALSE if no display or already on the first line.

      • down

        public boolean down()
        Move down one line. Note: the associated stream must have a text display for line operations to succeed. This method moves the position down one line in the displayed text. If already on the last line, the position does not move. Upward and downward movement attempts to reestablish the caret X co-ordinate as close as possible to its location on the old line. Repeated calls to up/down methods use the original position, so that moving through a short line doesn't truncate the target X co-ordinate.
        Returns:
        TRUE if the position moved down; FALSE if no display or already on the last line.

      • start

        public boolean start​(boolean bVisual)
        Move to the start of the line. Note: the associated stream must have a text display for line operations to succeed. This method moves the position to the start of the current line.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.
        Returns:
        FALSE if no display; TRUE otherwise.

      • start

        public boolean start()

      • end

        public boolean end​(boolean bVisual)
        Move to the end of the line. Note: the associated stream must have a text display for line operations to succeed. This method moves the position to the end of the current line.
        Parameters:
        bVisual - - TRUE for a visual move; FALSE (default) for a logical move.
        Returns:
        FALSE if no display; TRUE otherwise.

      • end

        public boolean end()

      • isAtStart

        public boolean isAtStart​(boolean bCheckFirstLineOnly)
        Determine whether the position is at the start of a line. Note: the associated stream must have a text display for line operations to succeed.
        Parameters:
        bCheckFirstLineOnly - - (optional) If TRUE, further restrict the test to check for start of the first line only. If FALSE (default), check for the start of any line.
        Returns:
        TRUE if the position is at the start of the line; FALSE if not or no display.

      • isAtStart

        public boolean isAtStart()

      • tighten

        public void tighten​(boolean bSkipAhead)
        Adjust the position around attribute changes. Typically used when constructing text ranges, this method adjusts the position to be either before or after any adjacent attribute change. Typically a text range does not include attribute changes at either end, so its start position must be advanced if before an attribute change and its end position must back up if after an attribute change.
        Parameters:
        bSkipAhead - - If TRUE, advance the position over any immediately subsequent attribute changes in the stream. If FALSE, back up the position over any immediately previous attribute changes in the stream.

      • charPosition

        public int charPosition()
        Return the number of characters that precede this position.
        Returns:
        Number of characters before this position.

      • charPosition

        public TextPosnBase charPosition​(int nIndex)
        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:
        nIndex - - Character position to search for.
        Returns:
        Resulting position object. Note: this is a const reference to a static object in thread-local storage. The caller should make a copy of the result, lest another call to this method clobber it.

      • charRange

        public TextRange charRange​(int lStart,
                           int lLength)
        Create a range with the associated, 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. Note: this is a const reference to a static object in thread-local storage. The caller should make a copy of the result, lest another call to this method clobber it.

      • insert

        public void insert​(char cInsert)
        Insert a character at this position. The specified character is inserted at this position and the position object then advances so that it is immediately after the inserted character. The call is ignored id there is no associated stream.
        Parameters:
        cInsert - - Character to insert.

      • insert

        public void insert​(java.lang.String sInsert)
        Insert a string at this position. The contents of the specified string are inserted at this position and the position object then advances so that it is immediately after the last inserted character. The call is ignored id there is no associated stream.
        Parameters:
        sInsert - - String to insert.

      • insert

        public void insert​(TextStream oInsert)
        Insert rich text at this position. The contents of the specified text stream are inserted (copied) at this position and the position object then advances so that it is immediately after the last inserted item. The call is ignored id there is no associated stream. Note that rich text insertion may involve the reconciliation of attributes. For example, if the inserted stream specifically sets attributes to be the same as those in the target stream, the inserted attribute change is redundant and will be removed. On the other hand, if the inserted stream changes attributes from those of the target, an attribute change must be manufactured after the insert to restore attributes for subsequent text in the target stream.
        Parameters:
        oInsert - - Rich text stream to insert.

      • insert

        public TextField insert​(TextField poField)
        Insert an embedded field at this position. Clone a copy of the given text field object and insert the clone as an embedded field at this position in the associated stream. This position advances so that it is immediately after the inserted field. The call is ignored id there is no associated stream.
        Parameters:
        poField - - Field to insert.
        Returns:
        Pointer to cloned field that has been embedded in the associated stream. This object belongs to the stream and must not be deleted by the caller.

      • insert

        public TextEmbed insert​(TextEmbed poEmbed)
        Insert an embedded object at this position. Clone a copy of the given embedded object and insert the clone as an embedded object at this position in the associated stream. This position advances so that it is immediately after the inserted object. The call is ignored id there is no associated stream.
        Parameters:
        poEmbed - - Object to insert.
        Returns:
        Pointer to cloned object that has been embedded in the associated stream. This object belongs to the stream and must not be deleted by the caller.

      • insertPara

        public void insertPara()
        Insert a paragraph mark at this position. The specified paragraph mark is inserted at this position and the position object then advances so that it is immediately after the inserted paragraph mark. The call is ignored id there is no associated stream.

      • insert

        public TextMarker insert​(TextMarker poMarker)
        Insert a position marker at the position represented by this position object. If this position 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.

      • deleteAhead

        public void deleteAhead​(int nDelete,
                        boolean bRaw)
        Delete ahead from this position in the associated stream. Delete items in the associated stream that come after this position. 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).
        Parameters:
        nDelete - - (optional) Number of items to delete. Default is 1.
        bRaw - - (optional) TRUE for raw delete (see above); FALSE (default) for normal delete.

      • deleteAhead

        public void deleteAhead​(int nDelete)

      • deleteAhead

        public void deleteAhead()

      • deleteBack

        public void deleteBack​(int nDelete,
                       boolean bRaw)
        Delete back from this position in the associated stream. Delete items in the associated stream that come before this position. 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).
        Parameters:
        nDelete - - (optional) Number of items to delete. Default is 1.
        bRaw - - (optional) TRUE for raw delete (see above); FALSE (default) for normal delete.

      • deleteBack

        public void deleteBack​(int nDelete)

      • deleteBack

        public void deleteBack()

      • attributePtr

        public TextAttr attributePtr()
        Obtain a pointer to the attributes in effect at this position. Scan back from this position for the attribute item applies. Return a pointer to those attributes. If there are no such attributes, this method will attempt to move up recursively through the text stream ancestry (e.g., this might be a field in a parent stream that has attributes).
        Overrides:
        attributePtr in class TextMarkupBase
        Returns:
        Pointer to attributes in effect at this position. NULL if no such attributes could be found.

      • attribute

        public TextAttr attribute()
        Obtain the attributes in effect at this position. Scan back from this position for the attribute item applies. Return those attributes. If there are no such attributes, this method will attempt to move up recursively through the text stream ancestry (e.g., this might be a field in a parent stream that has attributes). This method is generally not considered as efficient as AttributePtr().
        Returns:
        Attributes in effect at this position. Default values if no such attributes could be found.

      • attribute

        public void attribute​(TextAttr oNewAttr,
                      boolean bRaw)
        Set attributes at this position. One uses this method to set attributes immediately before inserting text with the new attributes. The act of setting attributes alone does not change the appearance of any text already in the stream. If you make any call other than inserting text at this position after inserting the attributes, the inserted attributes will be considered redundant and removed. The call actually results in two consecutive attribute changes in the stream: the first sets the new attributes for the anticipated text and the second restores attributes for existing subsequent text. This position is adjusted so that it is between the two attribute items.
        Parameters:
        oNewAttr - - Attributes to insert.
        bRaw - - (optional) Deprecated parameter is ignored.

      • attribute

        public final void attribute​(TextAttr oNewAttr)

      • setKeyboard

        public void setKeyboard()
        Establish the keyboard (left-to-right or right-to-left), based on this position object.

      • copyFrom

        public void copyFrom​(TextPosnBase oSource)
        Assignment operator.

        Copy the entire content of the source position object including stream association, index and before/after type.

        Parameters:
        oSource - Source position object to copy.

      • equals

        public boolean equals​(java.lang.Object object)
        Equality comparison. Two text positions are considered equal if they are associated with the same stream, have the same index number. Note that the operation does not compare any other attributes (e.g., before/after, affinity, RTL etc.) This is so that equality comparison has a consistent behaviour with greater/less than comparisons.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - - Position to compare against.
        Returns:
        TRUE if the positions are equal; FALSE if not.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • notEqual

        public boolean notEqual​(TextPosnBase oCompare)
        Inequality comparison.

        Two text positions are considered unequal if they are associated with the different streams, have the different index numbers or the different before/after position types. Note that the current implementation is rather crude in that it still compares index even when both streams are NULL.

        Parameters:
        oCompare - Position to compare against.
        Returns:
        TRUE if the positions are not equal; FALSE if not.

      • lt

        public boolean lt​(TextPosnBase oCompare)
        Is this position less than the given one?. The comparison is rather crude in that it compares index number only, completely ignoring streams and before/after position types.
        Parameters:
        oCompare - - Position to compare against.
        Returns:
        TRUE if this position is less than the given one; FALSE otherwise.

      • lte

        public boolean lte​(TextPosnBase oCompare)
        Is this position less than or equal to the given one?. The comparison is rather crude in that it compares index number only, completely ignoring streams and before/after position types.
        Parameters:
        oCompare - - Position to compare against.
        Returns:
        TRUE if this position is less than or equal to the given one; FALSE otherwise.

      • gt

        public boolean gt​(TextPosnBase oCompare)
        Is this position greater than the given one?. The comparison is rather crude in that it compares index number only, completely ignoring streams and before/after position types.
        Parameters:
        oCompare - - Position to compare against.
        Returns:
        TRUE if this position is greater than the given one; FALSE otherwise.

      • gte

        public boolean gte​(TextPosnBase oCompare)
        Is this position greater than or equal to the given one?. The comparison is rather crude in that it compares index number only, completely ignoring streams and before/after position types.
        Parameters:
        oCompare - - Position to compare against.
        Returns:
        TRUE if this position is greater than or equal to the given one; FALSE otherwise.

      • para

        public void para()
        Overridden: Insert a paragraph mark. This method implements a virtual method declared in base class TextMkBase. It simply calls the InsertPara() method.
        Specified by:
        para in class TextMarkupBase

      • field

        public void field​(TextField poField)
        Overridden: Insert field. This method implements a virtual method declared in base class TextMkBase. It simply calls the appropriate Insert() overload.
        Overrides:
        field in class TextMarkupBase
        Parameters:
        poField - - Field to be inserted.

      • text

        public void text​(java.lang.String sText)
        Overridden: Insert text. This method implements a virtual method declared in base class TextMkBase. It simply calls the appropriate Insert() overload.
        Specified by:
        text in class TextMarkupBase
        Parameters:
        sText - - Text to be inserted.

      • attr

        public void attr​(TextAttr oAttr)
        Overridden: Insert attribute change. This method implements a virtual method declared in base class TextMkBase. It simply calls the appropriate Attribute() overload.
        Specified by:
        attr in class TextMarkupBase
        Parameters:
        oAttr - - Attribute change to insert.

      • marker

        public void marker​(TextMarker poMarker)
        Description copied from class: TextMarkupBase
        Append a position marker to the markup output.
        Overrides:
        marker in class TextMarkupBase
        Parameters:
        poMarker - - Pointer to marker to append. 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.

      • markerStart

        public TextMarker markerStart​(TextMarker poMarker)
        Description copied from class: TextMarkupBase
        Start a range marker in the markup output.

        There must be a corresponding call to MarkerEnd() sometime later in the translation for the markup operation to be considered valid.

        Overrides:
        markerStart in class TextMarkupBase
        Parameters:
        poMarker - - Pointer to marker to append. 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 a marker object that represents the range marker in the output. While this is a non-const pointer, it is owned by AXTE and must not be modified by the client. The client must hang on to this pointer to complete the range. The client can perform one of two mutually-exclusive actions with this pointer. Normally, it passes it to a subsequent call to MarkerEnd() to complete the range. Alternatively, it may subsequently remove its reference, cancelling the marker range. The client must not perform both these actions on a single pointer, nor may it perform any other actions on the pointer.

      • markerEnd

        public void markerEnd​(TextMarker poMarker)
        Description copied from class: TextMarkupBase
        End a range marker in the markup output.

        This must occur some time after a corresponding call to MarkerStart() earlier in the translation for the markup operation to be considered valid.

        Overrides:
        markerEnd in class TextMarkupBase
        Parameters:
        poMarker - - Pointer to the marker object returned by the earlier call to MarkerStart(). The client must use the return value of that earlier call, not the value passed into it. In making this call, the client transfers ownership if its reference to AXTE and must not subsequenty attempt to remove that reference on this marker.