org.apache.fop.area

## Class AreaTreeHandler

- java.lang.Object
- - org.apache.fop.fo.FOEventHandler
  - - org.apache.fop.area.AreaTreeHandler

-     public class AreaTreeHandler
      extends FOEventHandler

  Area tree handler for formatting objects. Concepts: The area tree is to be as small as possible. With minimal classes and data to fully represent an area tree for formatting objects. The area tree needs to be simple to render and follow the spec closely. This area tree has the concept of page sequences. Wherever possible information is discarded or optimized to keep memory use low. The data is also organized to make it possible for renderers to minimize their output. A page can be saved if not fully resolved and once rendered a page contains only size and id reference information. The area tree pages are organized in a model that depends on the type of renderer.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected AreaTreeModel` | `model` The AreaTreeModel in use

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

      `fontInfo, foUserAgent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AreaTreeHandler(FOUserAgent userAgent, String outputFormat, OutputStream stream)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addUnresolvedIDRef(String idref, Resolvable res)` Deprecated. use getIDTracker().addUnresolvedIDRef(idref, res) instead
    `boolean` | `alreadyResolvedID(String id)` Deprecated. use getIDTracker().alreadyResolvedID(id) instead
    `void` | `associateIDWithPageViewport(String id, PageViewport pv)` Deprecated. use getIDTracker().associateIDWithPageViewport(id, pv) instead
    `void` | `endDocument()` End the document.
    `void` | `endExternalDocument(ExternalDocument document)` Process the end of the external-document extension.
    `void` | `endPageSequence(PageSequence pageSequence)` End the PageSequence.
    `String` | `generatePageViewportKey()` Generates and returns a unique key for a page viewport.
    `AreaTreeModel` | `getAreaTreeModel()` Get the area tree model for this area tree.
    `IDTracker` | `getIDTracker()` Get the IDTracker for this area tree.
    `LayoutManagerMaker` | `getLayoutManagerMaker()` Get the LayoutManager maker for this area tree.
    `List<PageViewport>` | `getPageViewportsContainingID(String id)` Deprecated. use getIDTracker().getPageViewportsContainingID(id) instead
    `FormattingResults` | `getResults()` Get information about the rendered output, like number of pages created.
    `boolean` | `isComplexScriptFeaturesEnabled()` Check whether complex script features are enabled.
    `void` | `notifyPageSequenceFinished(AbstractPageSequence pageSequence, int pageCount)` Called by the PageSequenceLayoutManager when it is finished with a page-sequence.
    `protected void` | `setupModel(FOUserAgent userAgent, String outputFormat, OutputStream stream)` Sets up the AreaTreeModel instance for use by the AreaTreeHandler.
    `void` | `signalIDProcessed(String id)` Deprecated. use getIDTracker().signalIDProcessed(id) instead
    `void` | `signalPendingID(String id)` Deprecated. use getIDTracker().signalPendingID(id) instead
    `void` | `startDocument()` Prepare AreaTreeHandler for document processing This is called from FOTreeBuilder.startDocument()
    `void` | `startExternalDocument(ExternalDocument document)` Process the start of the external-document extension.
    `void` | `startPageSequence(PageSequence pageSequence)`
    `void` | `startRoot(Root root)` Called upon start of root element.
    `void` | `tryIDResolution(PageViewport pv)` Deprecated. use getIDTracker().tryIDResolution(pv) instead

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

      `character, characters, endBlock, endBlockContainer, endBody, endCell, endColumn, endFlow, endFooter, endFootnote, endFootnoteBody, endHeader, endInline, endInstreamForeignObject, endLeader, endLink, endList, endListBody, endListItem, endListLabel, endMarkup, endPageNumber, endPageNumberCitation, endPageNumberCitationLast, endRetrieveMarker, endRetrieveTableMarker, endRoot, endRow, endStatic, endTable, endWrapper, getFontInfo, getUserAgent, image, pageRef, restoreState, restoreState, startBlock, startBlockContainer, startBody, startCell, startColumn, startFlow, startFooter, startFootnote, startFootnoteBody, startHeader, startInline, startInstreamForeignObject, startLeader, startLink, startList, startListBody, startListItem, startListLabel, startMarkup, startPageNumber, startPageNumberCitation, startPageNumberCitationLast, startRetrieveMarker, startRetrieveTableMarker, startRow, startStatic, startTable, startWrapper`

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

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

- - ### Field Detail

    - #### model

          protected AreaTreeModel model

      The AreaTreeModel in use

  - ### Constructor Detail

    - #### AreaTreeHandler

          public AreaTreeHandler(FOUserAgent userAgent,
                                 String outputFormat,
                                 OutputStream stream)
                          throws FOPException

      Constructor.
      Parameters:
        `userAgent` - FOUserAgent object for process
        `outputFormat` - the MIME type of the output format to use (ex. "application/pdf").
        `stream` - OutputStream
      Throws:
        `FOPException` - if the RenderPagesModel cannot be created

  - ### Method Detail

    - #### setupModel

          protected void setupModel(FOUserAgent userAgent,
                                    String outputFormat,
                                    OutputStream stream)
                             throws FOPException

      Sets up the AreaTreeModel instance for use by the AreaTreeHandler.
      Parameters:
        `userAgent` - FOUserAgent object for process
        `outputFormat` - the MIME type of the output format to use (ex. "application/pdf").
        `stream` - OutputStream
      Throws:
        `FOPException` - if the RenderPagesModel cannot be created

    - #### getAreaTreeModel

          public AreaTreeModel getAreaTreeModel()

      Get the area tree model for this area tree.
      Returns:
        AreaTreeModel the model being used for this area tree

    - #### getLayoutManagerMaker

          public LayoutManagerMaker getLayoutManagerMaker()

      Get the LayoutManager maker for this area tree.
      Returns:
        LayoutManagerMaker the LayoutManager maker being used for this area tree

    - #### getIDTracker

          public IDTracker getIDTracker()

      Get the IDTracker for this area tree.
      Returns:
        IDTracker used to track reference ids for items in this area tree

    - #### getResults

          public FormattingResults getResults()

      Get information about the rendered output, like number of pages created.
      Overrides:
        `getResults` in class `FOEventHandler`
      Returns:
        the results structure

    - #### isComplexScriptFeaturesEnabled

          public boolean isComplexScriptFeaturesEnabled()

      Check whether complex script features are enabled.
      Returns:
        true if using complex script features

    - #### startDocument

          public void startDocument()
                             throws SAXException

      Prepare AreaTreeHandler for document processing This is called from FOTreeBuilder.startDocument()
      Overrides:
        `startDocument` in class `FOEventHandler`
      Throws:
        `SAXException` - if there is an error

    - #### startRoot

          public void startRoot(Root root)

      Description copied from class: `FOEventHandler`
      Called upon start of root element.
      Overrides:
        `startRoot` in class `FOEventHandler`
      Parameters:
        `root` - element

    - #### startPageSequence

          public void startPageSequence(PageSequence pageSequence)

      Overrides:
        `startPageSequence` in class `FOEventHandler`
      Parameters:
        `pageSequence` - PageSequence that is starting.

    - #### endPageSequence

          public void endPageSequence(PageSequence pageSequence)

      End the PageSequence. The PageSequence formats Pages and adds them to the AreaTree. The area tree then handles what happens with the pages.
      Overrides:
        `endPageSequence` in class `FOEventHandler`
      Parameters:
        `pageSequence` - the page sequence ending

    - #### startExternalDocument

          public void startExternalDocument(ExternalDocument document)

      Process the start of the external-document extension.
      Overrides:
        `startExternalDocument` in class `FOEventHandler`
      Parameters:
        `document` - the external-document node

    - #### endExternalDocument

          public void endExternalDocument(ExternalDocument document)

      Process the end of the external-document extension.
      Overrides:
        `endExternalDocument` in class `FOEventHandler`
      Parameters:
        `document` - the external-document node

    - #### notifyPageSequenceFinished

          public void notifyPageSequenceFinished(AbstractPageSequence pageSequence,
                                                 int pageCount)

      Called by the PageSequenceLayoutManager when it is finished with a page-sequence.
      Parameters:
        `pageSequence` - the page-sequence just finished
        `pageCount` - The number of pages generated for the page-sequence

    - #### endDocument

          public void endDocument()
                           throws SAXException

      End the document.
      Overrides:
        `endDocument` in class `FOEventHandler`
      Throws:
        `SAXException` - if there is some error

    - #### generatePageViewportKey

          public String generatePageViewportKey()

      Generates and returns a unique key for a page viewport.
      Returns:
        the generated key.

    - #### associateIDWithPageViewport

          @Deprecated
          public void associateIDWithPageViewport(String id,
                                                              PageViewport pv)

      Deprecated. use getIDTracker().associateIDWithPageViewport(id, pv) instead
      Tie a PageViewport with an ID found on a child area of the PV. Note that an area with a given ID may be on more than one PV, hence an ID may have more than one PV associated with it.
      Parameters:
        `id` - the property ID of the area
        `pv` - a page viewport that contains the area with this ID

    - #### signalPendingID

          @Deprecated
          public void signalPendingID(String id)

      Deprecated. use getIDTracker().signalPendingID(id) instead
      This method tie an ID to the areaTreeHandler until this one is ready to be processed. This is used in page-number-citation-last processing so we know when an id can be resolved.
      Parameters:
        `id` - the id of the object being processed

    - #### signalIDProcessed

          @Deprecated
          public void signalIDProcessed(String id)

      Deprecated. use getIDTracker().signalIDProcessed(id) instead
      Signals that all areas for the formatting object with the given ID have been generated. This is used to determine when page-number-citation-last ref-ids can be resolved.
      Parameters:
        `id` - the id of the formatting object which was just finished

    - #### alreadyResolvedID

          @Deprecated
          public boolean alreadyResolvedID(String id)

      Deprecated. use getIDTracker().alreadyResolvedID(id) instead
      Check if an ID has already been resolved
      Parameters:
        `id` - the id to check
      Returns:
        true if the ID has been resolved

    - #### tryIDResolution

          @Deprecated
          public void tryIDResolution(PageViewport pv)

      Deprecated. use getIDTracker().tryIDResolution(pv) instead
      Tries to resolve all unresolved ID references on the given page.
      Parameters:
        `pv` - page viewport whose ID refs to resolve

    - #### getPageViewportsContainingID

          @Deprecated
          public List<PageViewport> getPageViewportsContainingID(String id)

      Deprecated. use getIDTracker().getPageViewportsContainingID(id) instead
      Get the set of page viewports that have an area with a given id.
      Parameters:
        `id` - the id to lookup
      Returns:
        the list of PageViewports

    - #### addUnresolvedIDRef

          @Deprecated
          public void addUnresolvedIDRef(String idref,
                                                     Resolvable res)

      Deprecated. use getIDTracker().addUnresolvedIDRef(idref, res) instead
      Add an Resolvable object with an unresolved idref
      Parameters:
        `idref` - the idref whose target id has not yet been located
        `res` - the Resolvable object needing the idref to be resolved

Copyright © 2025 Apache Software Foundation. All rights reserved.