diff options
Diffstat (limited to 'src/documentation/content/xdocs/DnI/areatree.xml')
| -rw-r--r-- | src/documentation/content/xdocs/DnI/areatree.xml | 420 |
1 files changed, 420 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/DnI/areatree.xml b/src/documentation/content/xdocs/DnI/areatree.xml new file mode 100644 index 000000000..5d361e3ca --- /dev/null +++ b/src/documentation/content/xdocs/DnI/areatree.xml @@ -0,0 +1,420 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!-- + * Copyright 2004 The Apache Software Foundation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + --> + +<!-- $Id$ --> + +<!-- +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "docbookx.dtd"> + --> + + <chapter> + <title>Phase 2: Building the Area tree</title> + + <section> + <title>Initiating the layout process</title> + +<para>In the <literal>PageSequence.end()</literal> method the +<literal>FOTreeHandler</literal> object +<literal>foInputHandler</literal> notifies the +<literal>FOTreeListeners</literal> of the PageSequence-end +event. There is only one listener, the +<literal>FOTreeControl</literal> object +<literal>foTreeControl</literal>. This listener asks its +<literal>LayoutManagerLS</literal> object to format the FO subtree of +the <literal>PageSequence</literal> FO node. This object constructs a +<literal>PageLayoutManager</literal> for the +<literal>PageSequence</literal> FO node, which does the work.</para> + +<screen> +org.apache.fop.fo.pagination.PageSequence.end(): +this.getFOTreeControl().getFOInputHandler().endPageSequence(this): +-> foTreeControl.getFOInputHandler().endPageSequence(this) +-> foInputHandler.endPageSequence(this) (type FOTreeHandler): +</screen> + +<para>This method only calls +<literal>FOTreeHandler.notifyPageSequenceComplete(pageSequence)</literal>, +which notifies the <literal>FOTreeListeners</literal> of the +PageSequence-end event. The <literal>PageSequence</literal> object +attaches itself to the event, from which the listeners can retrieve it +again.</para> + +<para>There is only one listener. It is an +<literal>org.apache.fop.apps.Document</literal> object. It is the same +object as <literal>pageSequence.root.foTreeControl</literal>. Its +method <literal>foPageSequenceComplete(event)</literal> is called, +which is a method of the <literal>FOTreeListener</literal> +interface. It handles an <literal>FOTreeEvent</literal> that is fired +when a <literal>PageSequence</literal> object has been +completed.</para> + +<para>The listener formats the FO subtree of the +<literal>PageSequence</literal> FO node. It calls its layout +strategy's method <literal>LayoutManagerLS.format(pageSeq, +areaTree)</literal>.</para> + +<para>This method creates a new <literal>PageLayoutManager</literal> +for the <literal>PageSequence</literal> FO node and calls its +<literal>run</literal> method (could start another thread). The pages +in this page sequence are completely layed out by the +<literal>PageLayoutManager</literal>, in its +<literal>doLayout</literal> method. The first step in the layout +process is getting the page setup from the page masters. Then the FO +tree is processed.</para> + +<screen> + [1] org.apache.fop.layoutmgr.PageLayoutManager.doLayout (PageLayoutManager.java:220) + [2] org.apache.fop.layoutmgr.PageLayoutManager.run (PageLayoutManager.java:208) + [3] org.apache.fop.layoutmgr.LayoutManagerLS.format (LayoutManagerLS.java:83) + [4] org.apache.fop.apps.Document.foPageSequenceComplete (Document.java:348) + [5] org.apache.fop.fo.FOTreeHandler.notifyPageSequenceComplete (FOTreeHandler.java:497) + [6] org.apache.fop.fo.FOTreeHandler.endPageSequence (FOTreeHandler.java:215) + [7] org.apache.fop.fo.pagination.PageSequence.end (PageSequence.java:350) + [8] org.apache.fop.fo.FOTreeBuilder.endElement (FOTreeBuilder.java:223) + ... parser stuff + [16] org.apache.xerces.parsers.AbstractSAXParser.parse (null) + [17] org.apache.fop.apps.Driver.render (Driver.java:622) + [18] org.apache.fop.apps.Driver.render (Driver.java:558) + [19] org.apache.fop.apps.Fop.main (Fop.java:102) +</screen> + +<screen> +main[1] dump pageLM + pageLM = { + pageNumberGenerator: instance of org.apache.fop.fo.pagination.PageNumberGenerator(id=1005) + pageCount: 1 + pageNumberString: "1" + isFirstPage: true + bFirstPage: false + curPage: null + curBody: null + curSpan: null + curSpanColumns: 0 + curFlow: null + flowBPD: 0 + flowIPD: 0 + areaTree: instance of org.apache.fop.area.AreaTree(id=1025) + pageSequence: instance of org.apache.fop.fo.pagination.PageSequence(id=997) + currentSimplePageMaster: null + staticContentLMs: instance of java.util.HashMap(id=1033) + lmls: instance of org.apache.fop.layoutmgr.LayoutManagerLS(id=1034) + org.apache.fop.layoutmgr.AbstractLayoutManager.userAgent: instance of org.apache.fop.apps.FOUserAgent(id=1035) + org.apache.fop.layoutmgr.AbstractLayoutManager.parentLM: null + org.apache.fop.layoutmgr.AbstractLayoutManager.fobj: instance of org.apache.fop.fo.pagination.PageSequence(id=997) + org.apache.fop.layoutmgr.AbstractLayoutManager.foID: null + org.apache.fop.layoutmgr.AbstractLayoutManager.markers: null + org.apache.fop.layoutmgr.AbstractLayoutManager.bFinished: false + org.apache.fop.layoutmgr.AbstractLayoutManager.curChildLM: null + org.apache.fop.layoutmgr.AbstractLayoutManager.childLMiter: instance of org.apache.fop.layoutmgr.LMiter(id=1036) + org.apache.fop.layoutmgr.AbstractLayoutManager.bInited: false +} +</screen> + + <para>The above calling sequence contains two configuration +points. FOP's area tree building process can be modified by +registering other listeners with the FO tree handler. It can also be +configured by giving the Document object a different layout strategy +object. See also the <literal>AddLMVisitor</literal> class which +controls the creation of Layout Managers. +<warning> + <simpara>TO BE EXPANDED</simpara> + </warning></para> + + </section> + + <section> + <title>Creating the page and body areas</title> + + <section> + <title>Overview</title> + + <para>Create the layout (<literal>doLayout</literal>) <itemizedlist spacing="compact"> + <listitem> + <para>First create a new Page Viewport +(<literal>makeNewPage</literal>). <itemizedlist spacing="compact"> + <listitem> + <para>First finish the current page +(<literal>finishPage</literal>).</para> + </listitem> + <listitem> + <para>Then create the new page viewport +(<literal>createPage</literal>). <itemizedlist spacing="compact"> + <listitem> + <para>First get the page master +(<literal>getSimplePageMasterToUse</literal>, +<literal>pageSequence.getPageSequenceMaster</literal> or +<literal>pageSequence.getSimplePageMaster</literal>).</para> + </listitem> + <listitem> + <para>Then get the body +(<literal>currentSimplePageMaster.getRegion</literal>, from +<literal>currentSimplePageMaster</literal>'s +<literal>regions</literal> map).</para> + </listitem> + <listitem> + <para>Then create the page viewport +(<literal>createPageAreas(currentSimplePageMaster)</literal>). +<itemizedlist spacing="compact"> + <listitem> + <para>From the properties of the page +master create the page reference rectangle, a new page, a new +FODimension object, and a CTM object.</para> + </listitem> + <listitem> + <para>For each region in the page master +(in our example we only have a body): <itemizedlist spacing="compact"> + <listitem> + <para>make a region viewport +(<literal>makeRegionViewport</literal>), which involves calculating +the position of the region on the page, using the FODimension and CTM +objects. +</para> + </listitem> + <listitem> + <para>make the reference area +(<literal>makeRegionBodyReferenceArea</literal>, +<literal>makeRegionReferenceArea</literal>).</para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist></para> + </listitem> + </itemizedlist></para> + + <para>At this point the page viewport and its region viewports +have been laid out.</para> + + <para> <itemizedlist spacing="compact"> + <listitem> + <simpara>Then create the body's main reference area +(<literal>createBodyMainReferenceArea</literal>).</simpara> + </listitem> + <listitem> + <simpara>Then create a Span +(<literal>createSpan</literal>).</simpara> + </listitem> + <listitem> + <simpara>And get the flowIPD +(curFlow.<literal>getIPD</literal>()).</simpara> + </listitem> + </itemizedlist></para> + + <para>At this point the body has a single span area with a +single flow area without children. +</para> + + </section> + + <section> + <title>Detailed view</title> + + <para>The call stack when creating the region viewports: +<screen> + [1] org.apache.fop.layoutmgr.PageLayoutManager.makeRegionViewport (PageLayoutManager.java:832) + [2] org.apache.fop.layoutmgr.PageLayoutManager.createPageAreas (PageLayoutManager.java:805) + [3] org.apache.fop.layoutmgr.PageLayoutManager.createPage (PageLayoutManager.java:748) + [4] org.apache.fop.layoutmgr.PageLayoutManager.makeNewPage (PageLayoutManager.java:467) + [5] org.apache.fop.layoutmgr.PageLayoutManager.doLayout (PageLayoutManager.java:220) +</screen> +</para> + +<para>At the end of <literal>createPageAreas</literal> the following +properties of the page have been established:</para> + +<para>The page reference rectangle: +<screen> + pageRefRect = { + x: 56692 + y: 56692 + width: 481891 + height: 728505 + serialVersionUID: -4345857070255674764 +} +</screen> +</para> + +<para>The page reference area: +<screen> + page = { + regionBefore: null + regionStart: null + regionBody: instance of org.apache.fop.area.RegionViewport(id=1279) + regionEnd: null + regionAfter: null + unresolved: null +} +</screen> + +<screen> + page.regionBody = { + region: instance of org.apache.fop.area.BodyRegion(id=1280) + viewArea: instance of java.awt.Rectangle(id=1281) + clip: false + org.apache.fop.area.Area.areaClass: 0 + org.apache.fop.area.Area.ipd: 0 + org.apache.fop.area.Area.props: null +} +</screen> + +<screen> + page.regionBody.region = { + beforeFloat: null + mainReference: null + footnote: null + columnGap: 18000 + columnCount: 1 + refIPD: 0 + org.apache.fop.area.RegionReference.regionClass: 2 + org.apache.fop.area.RegionReference.ctm: instance of org.apache.fop.area.CTM(id=1282) + org.apache.fop.area.RegionReference.blocks: instance of java.util.ArrayList(id=1283) + org.apache.fop.area.Area.areaClass: 0 + org.apache.fop.area.Area.ipd: 0 + org.apache.fop.area.Area.props: null +} +</screen> + +<screen> + page.regionBody.viewArea = { + x: 56692 + y: 56692 + width: 481891 + height: 728505 + serialVersionUID: -4345857070255674764 +} +</screen> +</para> + +<para>The <literal>PageViewport</literal> is returned:</para> + +<screen> + curPage = { + page: instance of org.apache.fop.area.Page(id=1261) + viewArea: instance of java.awt.Rectangle(id=1289) + clip: false + pageNumber: null + idReferences: null + unresolved: null + pendingResolved: null + markerFirstStart: null + markerLastStart: null + markerFirstAny: null + markerLastEnd: null + markerLastAny: null +} +</screen> + +<para>When <literal>makeNewPage</literal> returns, the Page +LayoutManager has a Page Viewport and a Body Region object. The layout +dimensions have been calculated:</para> + +<screen> + this = { + pageNumberGenerator: instance of org.apache.fop.fo.pagination.PageNumberGenerator(id=1003) + pageCount: 1 + pageNumberString: "1" + isFirstPage: false + bFirstPage: false + curPage: instance of org.apache.fop.area.PageViewport(id=1288) + curBody: instance of org.apache.fop.area.BodyRegion(id=1280) + curSpan: null + curSpanColumns: 0 + curFlow: null + flowBPD: 728505 + flowIPD: 0 + areaTree: instance of org.apache.fop.area.AreaTree(id=1005) + pageSequence: instance of org.apache.fop.fo.pagination.PageSequence(id=1006) + currentSimplePageMaster: instance of org.apache.fop.fo.pagination.SimplePageMaster(id=1007) + staticContentLMs: instance of java.util.HashMap(id=1008) + lmls: instance of org.apache.fop.layoutmgr.LayoutManagerLS(id=1009) + org.apache.fop.layoutmgr.AbstractLayoutManager.userAgent: instance of org.apache.fop.apps.FOUserAgent(id=1010) + org.apache.fop.layoutmgr.AbstractLayoutManager.parentLM: null + org.apache.fop.layoutmgr.AbstractLayoutManager.fobj: instance of org.apache.fop.fo.pagination.PageSequence(id=1006) + org.apache.fop.layoutmgr.AbstractLayoutManager.foID: null + org.apache.fop.layoutmgr.AbstractLayoutManager.markers: null + org.apache.fop.layoutmgr.AbstractLayoutManager.bFinished: false + org.apache.fop.layoutmgr.AbstractLayoutManager.curChildLM: null + org.apache.fop.layoutmgr.AbstractLayoutManager.childLMiter: instance of org.apache.fop.layoutmgr.LMiter(id=1011) + org.apache.fop.layoutmgr.AbstractLayoutManager.bInited: false +} +</screen> + +<para>The method <literal>createBodyMainReferenceArea()</literal> adds +a <literal>MainReferenceArea</literal> to the body region:</para> + +<screen> + curBody = { + beforeFloat: null + mainReference: instance of org.apache.fop.area.MainReference(id=1293) + footnote: null + columnGap: 18000 + columnCount: 1 + refIPD: 0 + org.apache.fop.area.RegionReference.regionClass: 2 + org.apache.fop.area.RegionReference.ctm: instance of org.apache.fop.area.CTM(id=1282) + org.apache.fop.area.RegionReference.blocks: instance of java.util.ArrayList(id=1283) + org.apache.fop.area.Area.areaClass: 0 + org.apache.fop.area.Area.ipd: 0 + org.apache.fop.area.Area.props: null +} +</screen> + +<screen> + curBody.mainReference = { + spanAreas: instance of java.util.ArrayList(id=1294) + columnGap: 0 + width: 0 + org.apache.fop.area.Area.areaClass: 0 + org.apache.fop.area.Area.ipd: 0 + org.apache.fop.area.Area.props: null +} +</screen> + +<screen> + curBody.mainReference.spanAreas = "[]" +</screen> + +<para>After <literal>createSpan(1)</literal>:</para> + +<screen> + curBody.mainReference.spanAreas = "[org.apache.fop.area.Span@1581e80]" +</screen> + +<screen> + curBody.mainReference.spanAreas.get(0) = { + flowAreas: instance of java.util.ArrayList(id=1299) + height: 0 + org.apache.fop.area.Area.areaClass: 0 + org.apache.fop.area.Area.ipd: 481891 + org.apache.fop.area.Area.props: null +} +</screen> + + </section> + </section> + </chapter> + +<!-- Local Variables: --> +<!-- current-language-environment: UTF-8 --> +<!-- coding: utf-8 --> +<!-- default-input-method: TeX --> +<!-- End: --> |