First committed version

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@197850 13f79535-47bb-0310-9956-ffa450edef68

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: -->