Package com.adobe.xfa.text

Class TextLayoutLine

  • public class TextLayoutLine
extends java.lang.Object
    This class represents an instance of a line in a text layout. The client creates an instance of this class, adds runs to it and then adds the line to the layout. A line caches three pieces of information:
    • The Unicode content of the line
    • The runs that make up the rendering of the line
    • A set of mappings defining the relationships between the Unicode content characters and the glyphs in the runs

    Except for an empty line, a line is considered complete only if it has content, runs and a complete mapping that covers all glyphs and characters. An error will occur if the client attempts to add an incomplete line to a layout object. If a client doesnt have access to the rendering information, it should populate the text stream through the traditional content-based API methods.

    Once editing is complete and the client has requested a new layout from the edited stream, it can retrieve the individual lines from the new layout, and then extract the runs from each line.

    • Field Detail

      • LINE_END_WORD_WRAP

        public static final int LINE_END_WORD_WRAP
        This enumeration describes the possible conditions in effect at the start and end of each line.

        Note that the value at the end of one line is the same as the value at the start of the next one. However, there are times when a previous line is not currently available (e.g., it is in a different frame--one that hasn't been loaded yet). Therefore AXTE requires that both start and end be attributed with these values.

        When loading layout into a text stream and its display, AXTE uses both the start and end states to control a number of aspects of that load operation. Of special note is the relationship between the last character in the line's Unicode content and the line's ending state. The following table describes the states and the last content character processing.

        This enumeration also identifies special cases resulting from hyphenation. Hyphenation typically results in the display of extra glyphs not included in the original content (e.g., the hyphen character). Additionally, hyphenation may result in spelling changes. When hyphenation appears in text layout, the glyphs provide the visual representation of the hyphenated content, while the line content contains the original text. Note that the hyphenated word will be split across the content of two lines. The client application must faithfully preserve the line start and end states, the glyphs and the line content in order to ensure that AXTE will stitch the content back together properly.

        • LINE_END_WORD_WRAP: This is the normal case. The line break was caused by word-wrapping during layout and does not exist as an explicit break in the Unicode content. There is no hyphenation involved in this line break.

          AXTE assumes that all content for the line is present. In most languages, this means that the line ends in a space at which the word-wrapping break occurred in the authoring application. If the Unicode content doesn't end in a space, AXTE assumes that the content at the end of this line runs together with the content at the start of the next line. This would be the case if the authoring application used dictionary-based line breaking (e.g., for Thai).

          When AXTE creates a layout from stream content and word-wrapping occurs at a space, that space will be placed at the end of the line, immediately after the word preceding the break. If a line break occurs due to dictionary-based line breaking or because a single word is larger than the entire line width, no such space appears.

        • LINE_END_HYPHEN: This value indicates the presence of hyphenation. As a line end state, it indicates that the last (logical) word in the line has been hyphenated, and therefore continues on the next line. As a line start state, it indicates that the first word of the line started on the previous line and continues on this one.

          Different languages indicate hyphenation in different ways. There may be one or more glyphs (for example a hyphen) added to the end of the line before the hyphen break and/or there may be glyphs added to the start of the next line. These embellishments are language-dependent.

          When AXTE creates a layout from hyphenated stream content, the line content will represent the original text, while the glyphs will represent the hyphenated display. The client application must preserve these faithfully and hand the same data back to AXTE when reconstructing text from layout.

        • LINE_END_LAST_WORD: Conceptually this is very similar to LINE_END_WORD_WRAP. It indicates that normal word-wrapping took place and there was no hyphenation. However, it also signifies that hyphenation wasn't attempted because the line after the break contained a single word (the last word of a paragraph is not normally hyphenated).

          The client must preserve this value and restore it to AXTE when loading layout into AXTE content. AXTE's incremental layout algorithm needs to distinguish this case from a "normal" word-wrapping break, otherwise hyphenation may not occur at appropriate times during incremental layout.

        • LINE_END_EMERGENCY: The line break was forced by emergency line breaking. This occurs if a word is too large to fit on a line by itself, and it could not be hyphenated.

          There wouldn't normally be a space at the end of the line before the break in this case. When reconstructing content from layout, AXTE assumes that the text of the previous line abuts the text of the next line, and doesn't insert any space.

        • LINE_END_FORCED: The line break was forced by Unicode content but is not a paragraph break. For example a line break character (U+000A) would cause this situation.

          If the line's Unicode content ends with a line break character, AXTE assumes that that character caused the break. The mapped glyph in the line's glyph runs must be the glyph for the space character. If the line's content does not end with a line break character, AXTE will insert one into the text stream content at the end of the line and add a space glyph corresponding to it.

          When generating layout from stream content, if the AXTE stream content contains a line break character, AXTE will place one at the end of the line, manufacture a space glyph corresponding to it, and set the line's end state to LINE_END_FORCED.

        • LINE_END_PARA: This indicates that a paragraph break caused the break between lines.

          If the line's Unicode content ends with a paragraph separator character (U+2029), AXTE replaces it with its own internal paragraph marker in the stream content. The corresponding glyph must be the glyph for the space character. If the line's content does not end with a paragraph separator character, AXTE will insert an internal paragraph marker into the text stream content at the end of the line and add a space glyph corresponding to it.

          When generating layout from stream content, if the AXTE stream content contains a paragraph marker, AXTE will place a Unicode paragraph separator character at the end of the line, manufacture a space glyph corresponding to it, and set the line's end state to LINE_END_PARA.

        • LINE_END_ULTIMATE: Reserved for the start of the first line (in the first frame) and the end of the last line (in the last frame).

          The absolute start and end of text do not have corresponding characters in the lines Unicode content.

          When AXTE creates a layout from stream content, AXTE will designate the start of the first line and the end of the last line with this value.

        See Also:
        Constant Field Values

    • Constructor Detail

      • TextLayoutLine

        public TextLayoutLine()
        Default constructor.

        The line initially has no content, runs or mappings; and effectively describes an empty line.

      • TextLayoutLine

        public TextLayoutLine​(TextLayoutLine oSource)
        Copy Constructor.

        Initializes the line to be a copy of the given source line. Note that runs are copied by reference only.

        Parameters:
        oSource - - Source line to copy.

    • Method Detail

      • reset

        public void reset()
        Reset the layout line object to its initial state.

        The client typically calls this method after adding a line to a layout if it wishes to reuse the line object. There is no harm in calling Reset() repeatedly or calling it on a just-created line object.

      • addRun

        public TextGlyphRun addRun​(TextGlyphRun poRun)
        Add a run to the line.
        Parameters:
        poRun - - Pointer to run object to add to the line. Note that AXTE always caches its own copies of objects. In other words, a clone of the given run will be added to the line. The client is free to delete the run identified by this parameter as soon as the call returns.
        Returns:
        Pointer to the cloned run added to the line. This object is owned by AXTE and should not be deleted by the client. However, the client may wish to retain it for tracking subsequent changes.

      • addRunRef

        public void addRunRef​(TextGlyphRun poRun)
        Add a run to the line, by reference.
        Parameters:
        poRun - - Pointer to run object to add to the line. The run is assumed to be reference counted and AXTE will simply add its own reference. Therefore, the caller must not explicitly delete this object prematurely. This method exists to prevent unnecessary copying.

      • getRunCount

        public int getRunCount()
        Return the number of runs in the line.
        Returns:
        Number of runs in the line.

      • getRun

        public TextGlyphRun getRun​(int nIndex)
        Get one run from the line.
        Parameters:
        nIndex - - Index of run to retrieve.
        Returns:
        Pointer to the requested run.

      • getGlyphCount

        public int getGlyphCount()
        Return the total number of glyphs in the line.
        Returns:
        Total number of glyphs in the line (accumulated across all runs).

      • setContent

        public void setContent​(java.lang.String sContent)
        Specify the line's Unicode content.

        Content must be provided at the line level--as opposed to the run level--because it is possible for a single Unicode content character to span a run boundary.

        This method is not cumulative. The client must provide all the Unicode content in a single call; multiple calls to this method for a given line instance simply replace the content previously specified.

        Parameters:
        sContent - - Unicode content for the line.

      • getContent

        public java.lang.String getContent()
        Get the line's content.
        Returns:
        Unicode content of the line.

      • getCharCount

        public int getCharCount()
        Return the number of Unicode characters in the lines Unicode content.
        Returns:
        Number of Unicode characters in the line. Will differ from the number of UTF-8 bytes in the content string for non-Latin text.

      • setMappings

        public void setMappings​(GFXMappingList oMappings)
        Set the mappings for the line.

        Note: methods SetMappings() and GetMappings() are the intended way to manipulate and access the lines mappings. Other mapping methods below will remain in the interface for some time to come, but are considered deprecated.

        Within the given mapping list object, Unicode character indexes and lengths refer to the implicit Unicode characters from the String object provided in the SetContent() method. This is different from the UTF-8 bytes that make up the actual storage of the String object. Unfortunately many String methods accept index values specified in terms of UTF-8 bytes for historical reasons. However, that class also provides Unicode character methods, and those are used internally by AXTE. Unicode character indexes start at zero.

        When a mapping is specified on a line object, the range of glyph indexes spans all runs in the line. The first glyph of the first run has index number zero. The index number for the first glyph of the second run is equal to the number of glyphs in the first run.

        Parameters:
        oMappings - - Complete set of mappings for the line.

      • getMappings

        public GFXMappingList getMappings()
        Return a description of the line's mappings.
        Returns:
        The line's mappings.

      • addMapping

        public void addMapping​(int nCharIndex,
                       int nGlyphIndex,
                       int nCharLength,
                       int nGlyphLength)
        (deprecated) Specify one character/glyph mapping for the line.

        The client specifies the mapping in terms of four parameters identifying both a sequential run of glyphs (in the line's rendering) and a sequential run of characters (in its Unicode content). Given the parameter names listed in the method declaration, the mapping is interpreted as the nCharLength characters in the Unicode text, starting at index nCharIndex, map to the nGlyphLength glyphs in the rendering starting at nGlyphIndex.

        Note that it takes multiple mappings to ensure all characters and glyphs are mapped, even when the mapping for each is 1:1. For example, specifying that two consecutive characters map to two consecutive glyphs in no way implies that the first character of the pair maps to the first glyph of the pair. It simply means there is a mapping between the pair of glyphs and the pair of characters that cannot be further refined.

        Typically at least one length parameter has a value of one; often both lengths have a value of one.

        Unicode character indexes and lengths refer to the implicit Unicode characters from the String object provided in the SetContent() method. This is different from the UTF-8 bytes that make up the actual storage of the String object. Unfortunately many String methods accept index values specified in terms of UTF-8 bytes for historical reasons. However, that class also provides Unicode character methods, and those are used internally by AXTE. Unicode character indexes start at zero.

        When a mapping is specified on a line object, the range of glyph indexes spans all runs in the line. The first glyph of the first run has index number zero. The index number for the first glyph of the second run is equal to the number of glyphs in the first run.

        Parameters:
        nCharIndex - - Starting character index, in the underlying Unicode characters, of the mapping.
        nGlyphIndex - - Starting glyph index, in the combined set of glyphs from all runs, of the mapping.
        nCharLength - - Number of consecutive Unicode characters in the mapping.
        nGlyphLength - - Number of consecutive glyphs in the mapping.

      • addMapping

        public void addMapping​(TextGlyphRun poRun,
                       int nCharIndex,
                       int nGlyphIndex,
                       int nCharLength,
                       int nGlyphLength)
        (deprecated) Specify one character/glyph mapping for the line, relative to a given run.

        For general information on specifying mappings, please see the other overload of this method. This version differs in that the glyph index is specified relative to a run in the line. For example, an index of zero refers to the first glyph in the run, even if the run isn't the first run in the line. This method cannot be used to specify a mapping that spans a run boundary.

        Parameters:
        poRun - - Pointer to a run that is a member of the line. In other words, this pointer must have been returned by AddRun() for this line instance, or it must have been added by reference.
        nCharIndex - - Starting character index, in the underlying Unicode characters, of the mapping.
        nGlyphIndex - - Starting glyph index, in the sequence of glyphs from this run, of the mapping.
        nCharLength - - Number of consecutive Unicode characters in the mapping.
        nGlyphLength - - Number of consecutive glyphs in the mapping.

      • autoMap

        public void autoMap()
        Perform Latin-based LTR mapping. This is a convenience method that maps glyphs to characters 1:1 from left to right in the line. It is an error if the numbers of characters and glyphs differ.

      • getMappingCount

        public int getMappingCount()
        (deprecated) Return the number of mappings currently in the line.
        Returns:
        Number of mappings currently in the line.

      • getMapping

        public GFXMapping getMapping​(int nIndex)

      • setLineStartState

        public void setLineStartState​(int eState)
        Set the line end state in effect at the start of this line.

        This normally duplicates the line end state in effect at the end of the previous line. However, that value may not be available yet if the previous line is in a different frame.

        Parameters:
        eState - - Line end state in effect at the start of this line.

      • getLineStartState

        public int getLineStartState()
        Retrieve the line end state in effect at the start of the line.
        Returns:
        Line end state in effect at the start of the line.

      • setLineEndState

        public void setLineEndState​(int eState)
        Set the line end state in effect at the end of this line.
        Parameters:
        eState - - Line end state in effect at the end of this line.

      • getLineEndState

        public int getLineEndState()
        Retrieve the line end state in effect at the end of the line.
        Returns:
        Line end state in effect at the end of the line.

      • getFullAscent

        public UnitSpan getFullAscent()
        Return the displacement of the line's baseline from the top of the line's bounding box.
        Returns:
        Full ascent of the line.

      • getFullDescent

        public UnitSpan getFullDescent()
        Return the displacement of the bottom of the line's bounding box from the line's baseline.
        Returns:
        Full descent of the line.

      • copyFrom

        public void copyFrom​(TextLayoutLine oSource)
        Assignment operator.

        Copies the content of the given source line to this line, replacing all of its data members. Note that runs are copied by reference only.

        Parameters:
        oSource - - Source line to copy.

      • setFullAscent

        public void setFullAscent​(UnitSpan oAscent)

      • setFullDescent

        public void setFullDescent​(UnitSpan oDescent)