Package com.adobe.xfa.text

Class TextStream

  • Direct Known Subclasses:
    TextField, TextSparseStream
    public class TextStream
extends TextLegacy
    A text stream is a container of rich text, embedded fields and other objects. Class TextStream embodies this functionality, but does not support rendering directly. There are two branches from TextStream in the inheritance tree: one for streams that can be rendered (TextDispStr), and one for fields (TextField).

    • Field Detail

      • DEFAULT_STREAM

        public static final TextStream DEFAULT_STREAM

    • Constructor Detail

      • TextStream

        public TextStream()
        Default constructor.

        The text stream contains no content and has no pool/mapping assocotiation.

      • TextStream

        public TextStream​(TextStream oSource,
                  TextGfxSource poPool)
        Copy constructor with graphics source information.

        Copy all stream content from the source stream, using optional graphic attribute pool.

        Parameters:
        oSource - Source text stream to copy content from.
        poPool - Graphic attribute pool to use.

      • TextStream

        public TextStream​(TextStream oSource)

      • TextStream

        public TextStream​(java.lang.String sSource)
        Constructor with source text string.

        Create a text stream whose initial content is copied from the given string. The text stream initially has no attribute pool association.

        Parameters:
        sSource - String whose contents are to be copied to the text stream.

    • Method Detail

      • enumEmbed

        public void enumEmbed​(java.util.List<TextEmbed> oEmbeds)
        Enumerate embeded objects in the stream.

        Populates an array with pointers to all embedded objects in the stream. This is a flat enumeration (i.e., it doesn't descend into embedded fields looking for embedded objects). These embedded objects remain property of the text stream and must not be deleted by the caller.

        Parameters:
        oEmbeds - Array to contain the resultant set of pointers. The array size is set to zero before repopulating.

      • enumField

        public void enumField​(java.util.List<TextField> oFields)
        Enumerate embeded fields in the stream.

        Populates an array with pointers to all embedded fields in the stream. This is a flat enumeration (i.e., it doesn't descend into those embedded fields looking for further embedded fields). These embedded fields remain property of the text stream and must not be deleted by the caller. The array size is set to zero before repopulating.

        Parameters:
        oFields - Array to contain the resultant set of pointers. The array size is set to zero before repopulating.

      • enumMarker

        public void enumMarker​(java.util.List<TextMarker> oMarkers,
                       boolean bPositionMarkers,
                       boolean bRangeMarkers)
        Enumerate all markers on the stream.

        Populates an array with pointers to all markers on the stream. This is a flat enumeration (i.e., it doesn't descend into embedded fields looking for additional markers). These markers remain property of the text stream and must not be deleted by the caller, though the client can cache pointers to these markers provide that it participates in the marker reference counting mechanism. The array size is set to zero before repopulating.

        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.
        bPositionMarkers - - True (default) if all position markers are to be included in the array. False if position markers are to be excluded.
        bRangeMarkers - - True (default) if all range markers are to be included in the array. False if range markers are to be excluded.

      • text

        public java.lang.String text​(boolean bIncludeFields)
        Obtain the raw (unformatted) text of the stream.

        Return a string containing all the text in the stream. Optionally descend into embedded fields when constructing the string.

        Parameters:
        bIncludeFields - (default TRUE) Indicates that the text retrieval is to recurse into embedded fields, if TRUE. Otherwise, only the text of the specified stream is returned.

      • text

        public java.lang.String text()

      • contiguousText

        public void contiguousText​(java.util.List<TextRange> oRanges)
        Return a set of ranges corresponding to the chunks of raw text in the stream.

        This method returns an array of text ranges. Each such range corresponds to one chunk of contiguous raw text (i.e., between attributes, embedded objects and fields) in the stream.

        Parameters:
        oRanges - Resultant array of text ranges. For some reason, this is not emptied before repopulating.

      • setText

        public void setText​(java.lang.String sText)
        Replace the stream's text with the given text.

        Replace all text in the stream with the contents of the given string. This also has the effect of removing any embedded objects and fields from the stream. If the stream contains embedded attribute changes, only the attributes in effect at the start remain in effect after the call.

        Parameters:
        sText - New text to place in the stream.

      • append

        public void append​(java.lang.String sText)
        Add text to the end of the stream.

        The various Append() methods allow the caller to build up a text stream sequentially, without having to resort to using text position objects. This overload adds text to the end of the stream. Whatever attributes were in effect at the end of the stream before the call apply to the newly added text.

        Parameters:
        sText - Text string to add to the end of the stream.

      • append

        public void append​(TextAttr oAttr)
        Add an attribute to the end of the stream.

        The various Append() methods allow the caller to build up a text stream sequentially, without having to resort to using text position objects. This overload adds an attribute change to the end of the stream. Note that attributes are somewhat transient. If the next call on the stream appends text, that text will inherit the new attributes. However most other manipulations will cause the newly added attributes to be deemed redundant and removed from the stream.

        Parameters:
        oAttr - Attribute object to add to the end of the stream.

      • append

        public void append​(TextField poField)
        Add an embedded field to the end of the stream.

        The various Append() methods allow the caller to build up a text stream sequentially, without having to resort to using text position objects. This overload adds an embedded field to the end of the stream. Whatever attributes were in effect at the end of the stream before the call apply to the field (unless it starts with its own attributes).

        Parameters:
        poField - Field to add to the end of the stream. The method clones a copy, so ownership of the object passed in remains with the caller.

      • append

        public void append​(TextEmbed poEmbed)
        Add an embedded object to the end of the stream.

        The various Append() methods allow the caller to build up a text stream sequentially, without having to resort to using text position objects. This overload adds an embedded object to the end of the stream.

        Parameters:
        poEmbed - Object to embed at the end of the stream. The method clones a copy, so ownership of the object passed in remains with the caller.

      • append

        public void append​(TextMarker oMarker)
        Add a position marker at the end of the stream.

        Note that there is no way to append a range marker through the text stream API. Generally markers are inserted through operations on text position and range objects.

        Parameters:
        oMarker - - Pointer to marker to add. 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.

      • append

        public void append​(TextStream oText)
        Add rich text to the end of the stream.

        The various Append() methods allow the caller to build up a text stream sequentially, without having to resort to using text position objects. This overload adds rich text to the end of the stream. If the given rich text does not start with an attribute, then whatever attributes were in effect at the end of this stream before the call apply to the start of the newly added rich text.

        Parameters:
        oText - Rich text to add to the end of the stream.

      • display

        public TextDisplay display()
        Obtain a pointer to the stream's display object.

        Return a pointer to the stream's associated text display object. Note that this method makes sense for embedded fields, as well as the root displayable stream. All streams in a hiearchy will refer to the same text display object. Client code that manages the editing of a field doesn't need to track down the root displayable stream in order to find the field's display.

        Returns:
        A pointer to the associated display, or NULL if there is no display currently associated. Note that ownership of the display belongs with the root displayable stream. The caller must not delete the display.

      • suppressFormat

        public void suppressFormat​(boolean bSuppress)
        Suppress reformatting of the display for faster multiple updates.

        If an application plans to make multiple changes to the same stream, it doesn't want to incur the overhead of reformatting on each call. This method allows it to turn off formatting and then turn it on later when all the changes are done. It is only when turned on again that the formatting occurs.

        Parameters:
        bSuppress - TRUE is suppressing formatting, FALSE if restoring it. Note that calls are actually "stacked", so that two consecutive calls with TRUE will require two calls with FALSE to resume formatting. This allows code to attempt to turn formatting off and back on without having to worry about subverting the caller's use of this method.

      • fontService

        public void fontService​(FontService poNewFontService)

      • gfxSource

        public TextGfxSource gfxSource()
        Obtain graphic source information used by the stream.

        AXTE collects the various sources and pools of graphic information (Gfx attribute pools, and font service) into a text graphic source object (TextGfxSource). This method returns the current graphic source of the stream.

        Returns:
        Constant reference to the text stream's graphic source

      • maxSize

        public int maxSize()
        Query the stream's current maximum content size.

        Any text stream can have an optional maximum number of characters. This number actually is the maximum number of characters, paragraph marks and embedded objects. This method returns the current maximum size of the stream.

        Returns:
        Maximum content size for the stream. A value of zero indicates the size is unlimited.

      • maxSize

        public void maxSize​(int nNewSize,
                    boolean bAllowExistingOverflow)
        Change the stream's maximum content size.

        Any text stream can have an optional maximum number of characters. This number actually is the maximum number of characters, paragraph marks and embedded objects. This method sets a new maximum size for the stream.

        Parameters:
        nNewSize - New maximum content size for the stream. A value of zero indicates the size is to be unlimited.
        bAllowExistingOverflow - Controls behaviour when the current content of the stream exceeds its new maximum size. If TRUE, the size is changed and the existing overflow is retained, but it is not treated as an error. If FALSE, the content is retained, the maximum size is not changed and an exception is thrown.

      • currentSize

        public int currentSize()
        Return the current content size of the stream
        Returns:
        The current number of characters, paragraph marks and embedded objects in the stream.

      • spaceLeft

        public int spaceLeft()
        Return the amount of content size left in the stream.

        Any text stream can have an optional maximum number of characters. This number actually is the maximum number of characters, paragraph marks and embedded objects. This method returns the number of characters that can still be added to the stream before its maximum content size is exceeded param return Number of characters that can still be added. If the maximum content size is unlimited, UINT_MAX is returned. If the current content already exceeds the maximum size, zero is returned.

      • allowNewLines

        public boolean allowNewLines()
        Does the text stream allow new line characters.

        In form-filling applications, it often doesn't make sense to allow new-line characters in fields. A stream can be told not to allow new-lines. Note that paragraph marks are not considered new-lines. This method returns a flag that indicates whether the stream allows new-lines.

        Returns:
        TRUE if the stream allows new-lines; FALSE if it doesn't.

      • allowNewLines

        public void allowNewLines​(boolean bNewAllow)
        Does the text stream allow new line characters.

        In form-filling applications, it often doesn't make sense to allow new-line characters in fields. Note that paragraph marks are not considered new-lines. This method tells the stream whether or not to allow new-lines.

        Parameters:
        bNewAllow - TRUE if the stream is to allow new-lines; FALSE if it not. If the stream already contains one or more new-lines when this value is set to FALSE, an exception is thrown.

      • anyNewLines

        public boolean anyNewLines()
        Does the text stream contain any new line characters
        Returns:
        TRUE if the stream contains any new-lines; FALSE if it doesn't.

      • find

        public boolean find​(java.lang.String sSearch,
                    TextPosnBase poFoundPosn)
        Search the stream for a given string.

        This method scans the string for the exact Unicode character match to a given string. It optionally returns a text position that points to the start of the match. Embedded attribute changes are ignored during the search, but embedded objects and fields are treated as non-matching characters.

        Parameters:
        sSearch - String to search for. Note that an empty search string always fails to match.
        poFoundPosn - Optional pointer to position object to receive the location of the start of the match. A NULL pointer (default value) may be passed when the caller isn't interested in the position.
        Returns:
        TRUE if the string was found; FALSE otherwise.

      • find

        public boolean find​(java.lang.String sSearch)

      • markup

        public void markup​(MarkupOut oMarkup,
                   TextAttr poInitAttr,
                   boolean bDefaultInitAttr,
                   boolean bFlattenFields)
        Convert the string contents to markup.

        Convert the entire stream contents to 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 it indicates ambient attributes, it 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 (this) root stream. If FALSE (default) field references are written to the markup.

      • markup

        public void markup​(MarkupOut oMarkup,
                   TextAttr poInitAttr,
                   boolean bDefaultInitAttr)

      • markup

        public void markup​(MarkupOut oMarkup)

      • markup

        public void markup​(MarkupIn oMarkup)
        Replace this streams content by processing the given markup.

        Process source in a given markup language and replace the stream's content with content described by the markup source. The particular language is determined by which derived class of TextMkOut is passed.

        Parameters:
        oMarkup - Markup engine to process the markup. Note that this pre-populated with the markup source text.

      • isDescendentOf

        public boolean isDescendentOf​(TextStream poAncestor,
                              TextPosnBase poPosn)
        Determine if this stream is contained under a given stream.

        Parameters:
        poPosn - Optional position object to describe the position of this stream (or its penultimate ancestor) in the ancestor stream. If the ancestor is this stream or is not an ancestor, the position object is not modified.
        Returns:
        TRUE if this stream is a descendent of the given stream; FALSE if not.

      • isDescendentOf

        public boolean isDescendentOf​(TextStream poAncestor)

      • legacyPositioning

        public void legacyPositioning​(boolean bLegacyPositioning)
        Set the value of the legacy positioning flag.

        For compatibility with version 6 layout idiosyncracies, legacy positioning mode can be enabled for a text stream (actually, it really makes sense only for displayable streams; see class TextDispStr). This method sets the flag for the stream and cascades it to all embedded fields and objects. It currently does not cause a relayout; therefore legacy positioning must be set before the display is created.

        Parameters:
        bLegacyPositioning - - TRUE if legacy positioning enabled for this stream; FALSE (default) if not.

      • cascadeLegacyLevel

        public void cascadeLegacyLevel​(int eLevel)
        Set legacy positioning by level enumeration and cascade to descendent streams and objects.
        Parameters:
        eLevel - - New legacy level to set.

      • copyFrom

        public void copyFrom​(TextStream oSource)
        Assign this stream's content from the given stream.

        Replace this stream's content with a copy of the content of the given stream. The graphic source information is not copied. In other words, fonts will be re-mapped in this stream's font service and attributes will be re-pooled in any attribute pool associated with this stream.

        Parameters:
        oSource - Stream containing source content to copy.

      • equals

        public boolean equals​(java.lang.Object object)
        Compare text streams for content equality.

        Compare this stream against the one passed on the parameter oCompare for content equality. The graphics sources of the streams are not compared. To be equal, the streams' content must match in all aspects: raw text, attributes, embedded field content, and so on.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - Text Stream object to compare against
        Returns:
        TRUE if the streams are equal; FALSE otherwise.

      • hashCode

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

      • notEqual

        public boolean notEqual​(TextStream oCompare)
        Compare text streams for content inequality.

        Compare this stream against the one passed on the parameter oCompare for content inequality. The graphics sources of the streams are not compared. This is the exact opposite of the equality comparison.

        Parameters:
        oCompare - Stream to compare against
        Returns:
        TRUE if the streams are unequal; FALSE otherwise.

      • getContext

        public TextContext getContext()
        Get the stream's text context object.

        The text context allows multiple streams to share common objects that are used at layout time, thereby reducing resource usage. This method returns a pointer to the text context in effect for this stream. Only displayable streams (see class TextDispStr) carry contexts. The default implementation of this virtual method looks back up through the stream containment hierarchy for a displayable stream and returns its context.

        Returns:
        Pointer to the text context; NULL if none is in effect or no displatable stream found.

      • position

        public TextPosn position()
        Get this stream's position in its parent stream.

        This virtual method is overridden by class TextField, the embedded field class. It returns a text position object associated with the parent stream that represent's the field's position in its parent. With this method, the caller can traverse back up the ancestry hierarchy toward the root. The default implementation returns a NULL pointer, indicating that stream is not embedded in another stream.

        Returns:
        Pointer to a const position object representing this stream's position in its parent; NULL if the stream is not embedded in another stream.

      • updateNotification

        public void updateNotification()
        Notify derived class of content change.

        When an API call changes the content of the stream, it calls this method to notify any derived class that changes have occurred. The default implementation does nothing. Currently, none of the derived classes implemented in Text Services use this feature.

      • posnCount

        public int posnCount()

      • posnNext

        public int[] posnNext​(TextPosnBase oPosn,
                      int eNullFrameMode,
                      boolean bTestOnly)

      • posnNextType

        public int posnNextType​(TextPosnBase oPosn,
                        int eNullFrameMode,
                        boolean bTestOnly)

      • posnNextType

        public int posnNextType​(TextPosnBase oPosn,
                        int eNullFrameMode)

      • posnPrev

        public int[] posnPrev​(TextPosnBase oPosn,
                      int eNullFrameMode,
                      boolean bTestOnly)

      • posnPrevType

        public int posnPrevType​(TextPosnBase oPosn,
                        int eNullFrameMode,
                        boolean bTestOnly)

      • posnPrevType

        public int posnPrevType​(TextPosnBase oPosn,
                        int eNullFrameMode)

      • posnNextChar

        public int posnNextChar​(TextPosnBase oPosn,
                        boolean bTestOnly)

      • posnPrevChar

        public int posnPrevChar​(TextPosnBase oPosn,
                        boolean bTestOnly)

      • posnInsertPara

        public void posnInsertPara​(TextPosnBase oPosn)

      • posnUpdateStreamLoc

        public void posnUpdateStreamLoc​(TextPosnBase oPosn,
                                int nIndex)

      • rangeEnumMarker

        public void rangeEnumMarker​(TextPosnBase oStart,
                            TextPosnBase oEnd,
                            java.util.List<TextMarker> oMarkers,
                            boolean bPositionMarkers,
                            boolean bRangeMarkers,
                            boolean bSubsetOnly)

      • splitMarker

        public TextMarker splitMarker​(TextMarker poSource,
                              int nSplitStart,
                              int nSplitEnd,
                              int eMarkerSplitReason)

      • removeMarker

        public void removeMarker​(TextMarker poRemove,
                         boolean bEditOnly)

      • findRangeMarkerOver

        public TextMarker findRangeMarkerOver​(int nIndex,
                                      int nSpan)

      • debug

        public void debug()