FOText (Apache FOP 2.7 API)
Date: 2022-01-12

org.apache.fop.fo

## Class FOText

- java.lang.Object
- - org.apache.fop.fo.FONode
  - - org.apache.fop.fo.FOText

- All Implemented Interfaces:
    java.lang.CharSequence, java.lang.Cloneable, TextFragment

      public class FOText
      extends FONode
      implements java.lang.CharSequence, TextFragment

  A text node (PCDATA) in the formatting object tree.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.fop.fo.FONode

      `FONode.FONodeIterator, FONode.GatherContextInfoFunction`

  - ### Field Summary

    - ### Fields inherited from class org.apache.fop.fo.FONode

      `FO_URI, FOX_URI, locator, log, nodeChangeBarList, parent, siblings, startOfNodeChangeBarList`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FOText(FONode parent)` Creates a new FO text node.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `bidiLevelAt(int position)` Obtain bidirectional level of character at specified position, which must be a non-negative integer less than the length of this FO.
    `void` | `bind(PropertyList pList)` Bind the given `PropertyList` to this node Does nothing by default.
    `protected void` | `characters(char[] data, int start, int length, PropertyList list, org.xml.sax.Locator locator)` Adds characters.
    `char` | `charAt(int position)` Obtain character at specified index within this fragment's sub-sequence, where index 0 corresponds to beginning index in overal text source, and subSequenceIndex must be less than ending index - beginning index.
    `CharIterator` | `charIterator()` Return a `CharIterator` over all characters in this node
    `FONode` | `clone(FONode parent, boolean removeChildren)` Performs a shallow cloning operation, sets the clone's parent, and optionally cleans the list of child nodes
    `protected java.util.Stack<DelimitedTextRange>` | `collectDelimitedTextRanges(java.util.Stack<DelimitedTextRange> ranges, DelimitedTextRange currentRange)` Collect the sequence of delimited text ranges, where each new range is pushed onto RANGES, where default implementation collects ranges of child nodes.
    `protected void` | `createBlockPointers(Block ancestorBlock)` This method is run as part of the ancestor Block's flushText(), to create xref pointers to the previous FOText objects within the same Block
    `void` | `endOfNode()` Primarily used for making final content model validation checks and/or informing the `FOEventHandler` that the end of this FO has been reached.
    `void` | `finalizeNode()` Finalize this node.
    `protected java.lang.String` | `gatherContextInfo()` Gathers context information for the getContextInfo() method.
    `Length` | `getBaseLineShift()`
    `int` | `getBeginIndex()` Obtain beginning index (inclusive) of sub-sequence of fragment in overall text source.
    `int` | `getBidiLevel()` Obtain associated bidi level (if known) or -1 if not.
    `int[]` | `getBidiLevels()` Obtain bidirectional level of each character represented by this FOText.
    `int[]` | `getBidiLevels(int start, int end)` Obtain bidirectional level of each character over interval [start,end).
    `java.lang.CharSequence` | `getCharSequence()` Return the array of characters for this instance.
    `java.awt.Color` | `getColor()`
    `CommonFont` | `getCommonFont()`
    `CommonHyphenation` | `getCommonHyphenation()`
    `java.lang.String` | `getCountry()`
    `int` | `getEndIndex()` Obtain ending index (exclusive) of sub-sequence of fragment in overall text source.
    `java.text.CharacterIterator` | `getIterator()` Obtain reference to underlying iterator.
    `KeepProperty` | `getKeepTogether()`
    `java.lang.String` | `getLanguage()` Obtain associated language (if designated) or "none" if not.
    `Property` | `getLetterSpacing()`
    `SpaceProperty` | `getLineHeight()`
    `java.lang.String` | `getLocalName()` Returns the local name (i.e.
    `java.lang.String` | `getNormalNamespacePrefix()` Returns the normally used namespace prefix for this node
    `java.lang.String` | `getScript()` Obtain associated script (if designated) or "auto" if not.
    `StructureTreeElement` | `getStructureTreeElement()` Returns the structure tree element associated to this object.
    `CommonTextDecoration` | `getTextDecoration()`
    `int` | `getWhitespaceTreatment()`
    `Property` | `getWordSpacing()`
    `int` | `getWrapOption()`
    `boolean` | `isDelimitedTextRangeBoundary(int boundary)` Determine if node has a delimited text range boundary.
    `int` | `length()`
    `void` | `resetBuffer()` Resets the backing `java.nio.CharBuffer`
    `void` | `setBidiLevel(int level, int start, int end)` Set bidirectional level over interval [start,end).
    `void` | `setStructureTreeElement(StructureTreeElement structureTreeElement)` Sets the structure tree element.
    `java.lang.CharSequence` | `subSequence(int start, int end)`
    `java.lang.String` | `toString()`
    `boolean` | `willCreateArea()` Check if this text node will create an area.

    - ### Methods inherited from class org.apache.fop.fo.FONode

      `addCharacters, addChildNode, attachSiblings, canHaveMarkers, clone, collectDelimitedTextRanges, createPropertyList, decorateWithContextInfo, errorText, getBuilderContext, getChangeBarList, getChildNodes, getChildNodes, getContentHandlerFactory, getContextInfo, getContextInfoAlt, getExtensionAttachment, getFOEventHandler, getFOValidationEventProducer, getLocator, getLocatorString, getLogger, getName, getName, getNameId, getNamespaceURI, getNodePrefix, getNodeString, getParent, getRoot, getUserAgent, inMarker, invalidChildError, invalidChildError, invalidPropertyValueError, isBidiRangeBlockItem, isChangeBarElement, missingChildElementError, missingChildElementError, missingPropertyError, nodesOutOfOrderError, nodesOutOfOrderError, notSupportedChildError, processNode, removeChild, setLocator, startOfNode, tooManyNodesError, tooManyNodesError, tooManyNodesError, validateChildNode, validateChildNode, warningText`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.CharSequence

      `chars, codePoints`

- - ### Constructor Detail

    - #### FOText

          public FOText(FONode parent)

      Creates a new FO text node.
      Parameters:
        `parent` - FONode that is the parent of this object

  - ### Method Detail

    - #### characters

          protected void characters(char[] data,
                                    int start,
                                    int length,
                                    PropertyList list,
                                    org.xml.sax.Locator locator)
                             throws FOPException

      Adds characters. Does nothing by default. To be overridden in subclasses that allow `#PCDATA` content.
      Overrides:
        `characters` in class `FONode`
      Parameters:
        `data` - array of characters containing text to be added
        `start` - starting array element to add
        `length` - number of elements to add
        `list` - currently applicable PropertyList
        `locator` - location in the XSL-FO source file.
      Throws:
        `FOPException` - if there's a problem during processing

    - #### getCharSequence

          public java.lang.CharSequence getCharSequence()

      Return the array of characters for this instance.
      Returns:
        a char sequence containing the text

    - #### clone

          public FONode clone(FONode parent,
                              boolean removeChildren)
                       throws FOPException

      Performs a shallow cloning operation, sets the clone's parent, and optionally cleans the list of child nodes
      Overrides:
        `clone` in class `FONode`
      Parameters:
        `parent` - the intended parent of the clone
        `removeChildren` - if true, clean the list of child nodes
      Returns:
        the cloned FO node
      Throws:
        `FOPException` - if there's a problem while cloning the node

    - #### bind

          public void bind(PropertyList pList)
                    throws FOPException

      Bind the given `PropertyList` to this node Does nothing by default. Subclasses should override this method in case they want to use the properties available on the `PropertyList`.
      Overrides:
        `bind` in class `FONode`
      Parameters:
        `pList` - the `PropertyList`
      Throws:
        `FOPException` - if there was an error when processing the `PropertyList`

    - #### endOfNode

          public void endOfNode()
                         throws FOPException

      Primarily used for making final content model validation checks and/or informing the `FOEventHandler` that the end of this FO has been reached. The default implementation simply calls `FONode.finalizeNode()`, without sending any event to the `FOEventHandler`.

      Note: the recommended way to override this method in subclasses is

      `super.endOfNode(); // invoke finalizeNode()`

      `getFOEventHandler().endXXX(); // send endOfNode() notification`

      Overrides:
        `endOfNode` in class `FONode`
      Throws:
        `FOPException` - if there's a problem during processing

    - #### finalizeNode

          public void finalizeNode()

      Finalize this node. This method can be overridden by subclasses to perform finishing tasks (cleanup, validation checks, ...) without triggering endXXX() events in the `FOEventHandler`. The method is called by the default `FONode.endOfNode()` implementation.
      Overrides:
        `finalizeNode` in class `FONode`

    - #### willCreateArea

          public boolean willCreateArea()

      Check if this text node will create an area. This means either there is non-whitespace or it is preserved whitespace. Maybe this just needs to check length > 0, since char iterators handle whitespace.
      Returns:
        true if this will create an area in the output

    - #### charIterator

          public CharIterator charIterator()

      Description copied from class: `FONode`
      Return a `CharIterator` over all characters in this node
      Overrides:
        `charIterator` in class `FONode`
      Returns:
        a new TextCharIterator

    - #### createBlockPointers

          protected void createBlockPointers(Block ancestorBlock)

      This method is run as part of the ancestor Block's flushText(), to create xref pointers to the previous FOText objects within the same Block
      Parameters:
        `ancestorBlock` - the ancestor fo:block

    - #### getCommonFont

          public CommonFont getCommonFont()

      Returns:
        the Common Font Properties.

    - #### getCommonHyphenation

          public CommonHyphenation getCommonHyphenation()

      Returns:
        the Common Hyphenation Properties.

    - #### getColor

          public java.awt.Color getColor()

      Returns:
        the "color" trait.

    - #### getKeepTogether

          public KeepProperty getKeepTogether()

      Returns:
        the "keep-together" trait.

    - #### getLetterSpacing

          public Property getLetterSpacing()

      Returns:
        the "letter-spacing" trait.

    - #### getLineHeight

          public SpaceProperty getLineHeight()

      Returns:
        the "line-height" trait.

    - #### getWhitespaceTreatment

          public int getWhitespaceTreatment()

      Returns:
        the "white-space-treatment" trait

    - #### getWordSpacing

          public Property getWordSpacing()

      Returns:
        the "word-spacing" trait.

    - #### getWrapOption

          public int getWrapOption()

      Returns:
        the "wrap-option" trait.

    - #### getTextDecoration

          public CommonTextDecoration getTextDecoration()

      Returns:
        the "text-decoration" trait.

    - #### getBaseLineShift

          public Length getBaseLineShift()

      Returns:
        the baseline-shift trait

    - #### getCountry

          public java.lang.String getCountry()

      Returns:
        the country trait

    - #### getIterator

          public java.text.CharacterIterator getIterator()

      Description copied from interface: `TextFragment`
      Obtain reference to underlying iterator.
      Specified by:
        `getIterator` in interface `TextFragment`

    - #### getBeginIndex

          public int getBeginIndex()

      Description copied from interface: `TextFragment`
      Obtain beginning index (inclusive) of sub-sequence of fragment in overall text source.
      Specified by:
        `getBeginIndex` in interface `TextFragment`

    - #### getEndIndex

          public int getEndIndex()

      Description copied from interface: `TextFragment`
      Obtain ending index (exclusive) of sub-sequence of fragment in overall text source.
      Specified by:
        `getEndIndex` in interface `TextFragment`

    - #### getLanguage

          public java.lang.String getLanguage()

      Description copied from interface: `TextFragment`
      Obtain associated language (if designated) or "none" if not.
      Specified by:
        `getLanguage` in interface `TextFragment`

    - #### getScript

          public java.lang.String getScript()

      Description copied from interface: `TextFragment`
      Obtain associated script (if designated) or "auto" if not.
      Specified by:
        `getScript` in interface `TextFragment`

    - #### getBidiLevel

          public int getBidiLevel()

      Description copied from interface: `TextFragment`
      Obtain associated bidi level (if known) or -1 if not.
      Specified by:
        `getBidiLevel` in interface `TextFragment`

    - #### toString

          public java.lang.String toString()

      Specified by:
        `toString` in interface `java.lang.CharSequence`
      Overrides:
        `toString` in class `java.lang.Object`

    - #### getLocalName

          public java.lang.String getLocalName()

      Returns the local name (i.e. without namespace prefix) of the node
      Specified by:
        `getLocalName` in class `FONode`
      Returns:
        the local name of this node

    - #### getNormalNamespacePrefix

          public java.lang.String getNormalNamespacePrefix()

      Returns the normally used namespace prefix for this node
      Specified by:
        `getNormalNamespacePrefix` in class `FONode`
      Returns:
        the normally used namespace prefix for this kind of node (ex. "fo" for XSL-FO)

    - #### gatherContextInfo

          protected java.lang.String gatherContextInfo()

      Gathers context information for the getContextInfo() method.
      Overrides:
        `gatherContextInfo` in class `FONode`
      Returns:
        the collected context information or null, if none is available

    - #### charAt

          public char charAt(int position)

      Obtain character at specified index within this fragment's sub-sequence, where index 0 corresponds to beginning index in overal text source, and subSequenceIndex must be less than ending index - beginning index.
      Specified by:
        `charAt` in interface `java.lang.CharSequence`
      Specified by:
        `charAt` in interface `TextFragment`

    - #### subSequence

          public java.lang.CharSequence subSequence(int start,
                                                    int end)

      Specified by:
        `subSequence` in interface `java.lang.CharSequence`
      Specified by:
        `subSequence` in interface `TextFragment`

    - #### length

          public int length()

      Specified by:
        `length` in interface `java.lang.CharSequence`

    - #### resetBuffer

          public void resetBuffer()

      Resets the backing `java.nio.CharBuffer`

    - #### isDelimitedTextRangeBoundary

          public boolean isDelimitedTextRangeBoundary(int boundary)

      Description copied from class: `FONode`
      Determine if node has a delimited text range boundary. N.B. that we report this to be true by default, while specific subclasses override this method to report false.
      Overrides:
        `isDelimitedTextRangeBoundary` in class `FONode`
      Parameters:
        `boundary` - one of {EN_BEFORE, EN_AFTER, or EN_BOTH} enumeration constants
      Returns:
        true if indicated boundary (or boundaries) constitute a delimited text range boundary.

    - #### setStructureTreeElement

          public void setStructureTreeElement(StructureTreeElement structureTreeElement)

      Description copied from class: `FONode`
      Sets the structure tree element.
      Overrides:
        `setStructureTreeElement` in class `FONode`
      Parameters:
        `structureTreeElement` - set.

    - #### getStructureTreeElement

          public StructureTreeElement getStructureTreeElement()

      Description copied from class: `FONode`
      Returns the structure tree element associated to this object.
      Overrides:
        `getStructureTreeElement` in class `FONode`
      Returns:
        the structure tree element

    - #### setBidiLevel

          public void setBidiLevel(int level,
                                   int start,
                                   int end)

      Set bidirectional level over interval [start,end).
      Parameters:
        `level` - the resolved level
        `start` - the starting index of interval
        `end` - the ending index of interval

    - #### getBidiLevels

          public int[] getBidiLevels()

      Obtain bidirectional level of each character represented by this FOText.
      Returns:
        a (possibly empty) array of bidi levels or null in case no bidi levels have been assigned

    - #### getBidiLevels

          public int[] getBidiLevels(int start,
                                     int end)

      Obtain bidirectional level of each character over interval [start,end).
      Parameters:
        `start` - the starting index of interval
        `end` - the ending index of interval
      Returns:
        a (possibly empty) array of bidi levels or null in case no bidi levels have been assigned

    - #### bidiLevelAt

          public int bidiLevelAt(int position)
                          throws java.lang.IndexOutOfBoundsException

      Obtain bidirectional level of character at specified position, which must be a non-negative integer less than the length of this FO.
      Parameters:
        `position` - an offset position into FO's characters
      Returns:
        a resolved bidi level or -1 if default
      Throws:
        `java.lang.IndexOutOfBoundsException` - if position is not non-negative integer or is greater than or equal to length

    - #### collectDelimitedTextRanges

          protected java.util.Stack<DelimitedTextRange> collectDelimitedTextRanges(java.util.Stack<DelimitedTextRange> ranges,
                                                                                   DelimitedTextRange currentRange)

      Description copied from class: `FONode`
      Collect the sequence of delimited text ranges, where each new range is pushed onto RANGES, where default implementation collects ranges of child nodes.
      Overrides:
        `collectDelimitedTextRanges` in class `FONode`
      Parameters:
        `ranges` - a stack of delimited text ranges
        `currentRange` - the current range or null (if none)
      Returns:
        the (possibly) updated stack of delimited text ranges

Copyright 1999-2022 The Apache Software Foundation. All Rights Reserved.