1.) More commenting, some simplifications in the Area classes and PSLM.

2.) Renamed Area.Flow to NormalFlow, uglier but more in conformance with the Recommendation (normal-flow-reference-area) and more specific/easier to understand.


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

12 files changed, 78 insertions, 66 deletions

diff --git a/src/java/org/apache/fop/area/BeforeFloat.java b/src/java/org/apache/fop/area/BeforeFloat.java
index d30b287e0..7cd8ec617 100644
--- a/src/java/org/apache/fop/area/BeforeFloat.java
+++ b/src/java/org/apache/fop/area/BeforeFloat.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 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.
@@ -19,9 +19,9 @@
 package org.apache.fop.area;
 
 /**
- * The before float area.
- * This is used to place the before float areas.
+ * The before-float-reference-area optionally generated by an fo:region-body.
  * It has an optional separator and before float block children.
+ * See fo:region-body definition in the XSL Rec for more information.
  */
 public class BeforeFloat extends BlockParent {
     // this is an optional block area that will be rendered
diff --git a/src/java/org/apache/fop/area/BodyRegion.java b/src/java/org/apache/fop/area/BodyRegion.java
index 785e25f56..fbca171ce 100644
--- a/src/java/org/apache/fop/area/BodyRegion.java
+++ b/src/java/org/apache/fop/area/BodyRegion.java
@@ -21,14 +21,15 @@ package org.apache.fop.area;
 import org.apache.fop.fo.Constants;
 
 /**
- * The body region area.
- * This area contains a main reference area and optionally a
- * before float and footnote area.
+ * This class is a container for all areas that may be generated by
+ * an fo:region-body.  It extends the RegionReference that is used
+ * directly by the other region classes.
+ * See fo:region-body definition in the XSL Rec for more information.
  */
 public class BodyRegion extends RegionReference {
-    private BeforeFloat beforeFloat;
-    private MainReference mainReference;
-    private Footnote footnote;
+    private BeforeFloat beforeFloat;  // optional
+    private MainReference mainReference; // mandatory
+    private Footnote footnote; // optional
     private int columnGap;
     private int columnCount;
 
diff --git a/src/java/org/apache/fop/area/Footnote.java b/src/java/org/apache/fop/area/Footnote.java
index 2497c3101..e1b0c453e 100644
--- a/src/java/org/apache/fop/area/Footnote.java
+++ b/src/java/org/apache/fop/area/Footnote.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 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.
@@ -21,8 +21,9 @@ package org.apache.fop.area;
 // may combine with before float into a conditional area
 
 /**
- * Footnote reference area.
+ * The footnote-reference-area optionally generated by an fo:region-body.
  * This areas holds footnote areas and an optional separator area.
+ * See fo:region-body definition in the XSL Rec for more information.
  */
 public class Footnote extends BlockParent {
     private Block separator = null;
diff --git a/src/java/org/apache/fop/area/MainReference.java b/src/java/org/apache/fop/area/MainReference.java
index 8dac9777f..5274d4955 100644
--- a/src/java/org/apache/fop/area/MainReference.java
+++ b/src/java/org/apache/fop/area/MainReference.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 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.
@@ -22,8 +22,10 @@ import java.util.List;
 import java.util.Iterator;
 
 /**
- * The main body reference area.
- * This area that contains the flow via the span areas.
+ * The main-reference-area generated by an fo:region-body
+ * This object holds one or more span-reference-areas (block-areas
+ * stacked in the block progression direction)
+ * See fo:region-body definition in the XSL Rec for more information.
  */
 public class MainReference extends Area {
     private List spanAreas = new java.util.ArrayList();
@@ -69,7 +71,7 @@ public class MainReference extends Area {
                 for (Iterator spaniter = spanAreas.iterator(); spaniter.hasNext(); ) {
                     Span spanArea = (Span) spaniter.next();
                     for (int i = 0; i < spanArea.getColumnCount(); i++) {
-                        Flow flow = spanArea.getFlow(i);
+                        NormalFlow flow = spanArea.getNormalFlow(i);
                         if (flow != null) {
                             if (flow.getChildAreas() != null) {
                                 areaCount += flow.getChildAreas().size();
@@ -87,7 +89,7 @@ public class MainReference extends Area {
     /**
      * Get the column gap in millipoints.
      *
-     * @return the column gap in millioints
+     * @return the column gap in millipoints
      */
     public int getColumnGap() {
         return columnGap;
diff --git a/src/java/org/apache/fop/area/Flow.java b/src/java/org/apache/fop/area/NormalFlow.java
index e451292ad..32dfbc7d8 100644
--- a/src/java/org/apache/fop/area/Flow.java
+++ b/src/java/org/apache/fop/area/NormalFlow.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 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.
@@ -19,17 +19,15 @@
 package org.apache.fop.area;
 
 /**
- * The normal flow reference area class.
- * This area contains a list of block areas from the flow.
+ * The normal-flow-reference-area class.
+ * Each span-reference-area contains one or more of these objects
+ * See fo:region-body definition in the XSL Rec for more information.
  */
-public class Flow extends BlockParent {
-    // the list of blocks created from the flow
-    private int stacking = TB;
-
+public class NormalFlow extends BlockParent {
     /**
      * Constructor.
      */
-    public Flow() {
+    public NormalFlow() {
         addTrait(Trait.IS_REFERENCE_AREA, Boolean.TRUE);
     }
 }
diff --git a/src/java/org/apache/fop/area/Span.java b/src/java/org/apache/fop/area/Span.java
index ddad76d48..926e9d05b 100644
--- a/src/java/org/apache/fop/area/Span.java
+++ b/src/java/org/apache/fop/area/Span.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 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.
@@ -21,14 +21,18 @@ package org.apache.fop.area;
 import java.util.List;
 
 /**
- * The span reference area.
- * This is a reference area block area with 0 border and padding
- * The span reference areas are stacked inside the main reference area.
+ * The span-reference-area.
+ * This is a block-area with 0 border and padding that is stacked
+ * within the main-reference-area
+ * This object holds one or more normal-flow-reference-area children
+ * based on the column-count trait in effect for this span.
+ * See fo:region-body definition in the XSL Rec for more information. 
  */
 public class Span extends Area {
     // the list of flow reference areas in this span area
     private List flowAreas;
     private int height;
+    private int columnCount;
 
     /**
      * Create a span area with the number of columns for this span area.
@@ -37,25 +41,26 @@ public class Span extends Area {
      */
     public Span(int cols) {
         flowAreas = new java.util.ArrayList(cols);
+        columnCount = cols;
         addTrait(Trait.IS_REFERENCE_AREA, Boolean.TRUE);
     }
 
     /**
-     * Add a flow area to this span area.
+     * Add a normal-flow-reference-area to this span-reference-area.
      *
-     * @param flow the flow area to add
+     * @param flow the normal-flow-reference-area to add
      */
-    public void addFlow(Flow flow) {
+    public void addNormalFlow(NormalFlow flow) {
         flowAreas.add(flow);
     }
 
     /**
-     * Create a new flow and add it to this span area
+     * Create a new normal flow and add it to this span area
      *
-     * @return the newly made Flow object
+     * @return the newly made NormalFlow object
      */
-    public Flow addNewFlow() {
-        Flow newFlow = new Flow();
+    public NormalFlow addNewNormalFlow() {
+        NormalFlow newFlow = new NormalFlow();
         newFlow.setIPD(getIPD());
         flowAreas.add(newFlow);
         return newFlow;
@@ -64,9 +69,18 @@ public class Span extends Area {
     /**
      * Get the column count for this span area.
      *
-     * @return the number of columns in this span area
+     * @return the number of columns defined for this span area
      */
     public int getColumnCount() {
+        return columnCount;
+    }
+
+    /**
+     * Get the count of normal flows for this span area.
+     *
+     * @return the number of normal flows attached to this span
+     */
+    public int getNormalFlowCount() {
         return flowAreas.size();
     }
 
@@ -80,13 +94,13 @@ public class Span extends Area {
     }
 
     /**
-     * Get the flow area for a particular column.
+     * Get the normal flow area for a particular column.
      *
      * @param count the column number for the flow
      * @return the flow area for the requested column
      */
-    public Flow getFlow(int count) {
-        return (Flow) flowAreas.get(count);
+    public NormalFlow getNormalFlow(int columnNumber) {
+        return (NormalFlow) flowAreas.get(columnNumber);
     }
 
 }
diff --git a/src/java/org/apache/fop/layoutmgr/LeaderLayoutManager.java b/src/java/org/apache/fop/layoutmgr/LeaderLayoutManager.java
index d5b4f7df9..8fef3f18e 100644
--- a/src/java/org/apache/fop/layoutmgr/LeaderLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/LeaderLayoutManager.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 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.
diff --git a/src/java/org/apache/fop/layoutmgr/LeafNodeLayoutManager.java b/src/java/org/apache/fop/layoutmgr/LeafNodeLayoutManager.java
index 30eee8927..e0feca999 100644
--- a/src/java/org/apache/fop/layoutmgr/LeafNodeLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/LeafNodeLayoutManager.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 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.
diff --git a/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java b/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
index 097163f45..8d120e455 100644
--- a/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/PageSequenceLayoutManager.java
@@ -25,7 +25,7 @@ import org.apache.fop.area.AreaTreeHandler;
 import org.apache.fop.area.AreaTreeModel;
 import org.apache.fop.area.Area;
 import org.apache.fop.area.PageViewport;
-import org.apache.fop.area.Flow;
+import org.apache.fop.area.NormalFlow;
 import org.apache.fop.area.LineArea;
 import org.apache.fop.area.Page;
 import org.apache.fop.area.RegionViewport;
@@ -89,11 +89,8 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
     /** Current span being filled */
     private Span curSpan;
 
-    /** Number of columns in current span area. */
-    private int curSpanColumns;
-
-    /** Current flow-reference-area (column) being filled. */
-    private Flow curFlow;
+    /** Current normal-flow-reference-area being filled. */
+    private NormalFlow curFlow;
 
     private int flowBPD = 0;
     private int flowIPD = 0;
@@ -400,14 +397,14 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
             return;
         }
         if (childArea.getAreaClass() == Area.CLASS_NORMAL) {
-            placeFlowRefArea(childArea);
+            placeNormalFlowRefArea(childArea);
         } else {
              // todo: all the others!
         }
     }
 
     /**
-     * Place a FlowReferenceArea into the current span. The FlowLM is
+     * Place a normal-flow-reference-area into the current span. The FlowLM is
      * responsible for making sure that it will actually fit in the
      * current span area. In fact the area has already been added to the
      * current span, so we are just checking to see if the span is "full",
@@ -415,7 +412,7 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
      *
      * @param area the area to place
      */
-    protected void placeFlowRefArea(Area area) {
+    protected void placeNormalFlowRefArea(Area area) {
         // assert (curSpan != null);
         // assert (area == curFlow);
         // assert (curFlow == curSpan.getFlow(curSpan.getColumnCount()-1));
@@ -434,7 +431,7 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         //                   ":" + curSpan.getMaxBPD().min);
         /*if (area.getAllocationBPD().max >= curSpan.getMaxBPD().min) {
             // Consider it filled
-            if (curSpan.getColumnCount() == curSpanColumns) {
+            if (curSpan.getColumnCount() == curSpan.getNormalFlowCount()) {
                 finishPage();
             } else
                 curFlow = null; // Create new flow on next getParentArea()
@@ -588,9 +585,9 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
             if (curSpan == null) {
                 createBodyMainReferenceArea();
                 bNeedSpan = true;
-            } else if (numCols != curSpanColumns) {
+            } else if (numCols != curSpan.getNormalFlowCount()) {
                 // todo: BALANCE EXISTING COLUMNS
-                if (curSpanColumns > 1) {
+                if (curSpan.getNormalFlowCount() > 1) {
                     // balanceColumns();
                 }
                 bNeedSpan = true;
@@ -599,7 +596,7 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
                 // Make a new span and the first flow
                 createSpan(numCols);
             } else if (curFlow == null) {
-                curFlow = curSpan.addNewFlow();
+                curFlow = curSpan.addNewNormalFlow();
             }
             return curFlow;
         } else {
@@ -636,10 +633,10 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
      */
     private void handleBreak(int breakVal) {
         if (breakVal == Constants.EN_COLUMN) {
-            if (curSpan != null
-                    && curSpan.getColumnCount() != curSpanColumns) {
+            if (curSpan != null // TODO: change below to < or <=
+                    && curSpan.getNormalFlowCount() != curSpan.getColumnCount()) {
                 // Move to next column
-                curFlow = curSpan.addNewFlow();
+                curFlow = curSpan.addNewNormalFlow();
                 return;
             }
             // else need new page
@@ -717,7 +714,6 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         //}
         //else newpos = new MinOptMax();
         curSpan = new Span(numCols);
-        curSpanColumns = numCols;
         // get Width or Height as IPD for span
 
         RegionViewport rv = curPage.getPage().getRegionViewport(FO_REGION_BODY);
@@ -727,7 +723,7 @@ public class PageSequenceLayoutManager extends AbstractLayoutManager {
         curSpan.setIPD(ipdWidth);
         //curSpan.setPosition(BPD, newpos);
         curBody.getMainReference().addSpan(curSpan);
-        curFlow = curSpan.addNewFlow();
+        curFlow = curSpan.addNewNormalFlow();
     }
 
     private PageViewport createPageAreas(SimplePageMaster spm) {
diff --git a/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java b/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
index f9cfe5104..350676208 100644
--- a/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
+++ b/src/java/org/apache/fop/layoutmgr/list/ListBlockLayoutManager.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 1999-2004 The Apache Software Foundation.
+ * Copyright 1999-2005 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.
diff --git a/src/java/org/apache/fop/render/AbstractRenderer.java b/src/java/org/apache/fop/render/AbstractRenderer.java
index ab017e007..2492ab129 100644
--- a/src/java/org/apache/fop/render/AbstractRenderer.java
+++ b/src/java/org/apache/fop/render/AbstractRenderer.java
@@ -37,7 +37,7 @@ import org.apache.fop.area.Block;
 import org.apache.fop.area.BlockViewport;
 import org.apache.fop.area.BodyRegion;
 import org.apache.fop.area.CTM;
-import org.apache.fop.area.Flow;
+import org.apache.fop.area.NormalFlow;
 import org.apache.fop.area.Footnote;
 import org.apache.fop.area.LineArea;
 import org.apache.fop.area.MainReference;
@@ -380,7 +380,7 @@ public abstract class AbstractRenderer
                     - (span.getColumnCount() - 1) * mr.getColumnGap())
                     / span.getColumnCount() + mr.getColumnGap();
             for (int c = 0; c < span.getColumnCount(); c++) {
-                Flow flow = (Flow) span.getFlow(c);
+                NormalFlow flow = (NormalFlow) span.getNormalFlow(c);
 
                 renderFlow(flow);
                 currentIPPosition += offset;
@@ -395,7 +395,7 @@ public abstract class AbstractRenderer
      *
      * @param flow  The flow reference area
      */
-    protected void renderFlow(Flow flow) {
+    protected void renderFlow(NormalFlow flow) {
         // the normal flow reference area contains stacked blocks
         List blocks = flow.getChildAreas();
         if (blocks != null) {
diff --git a/src/java/org/apache/fop/render/xml/XMLRenderer.java b/src/java/org/apache/fop/render/xml/XMLRenderer.java
index 4a2e54cf1..8fccab4bd 100644
--- a/src/java/org/apache/fop/render/xml/XMLRenderer.java
+++ b/src/java/org/apache/fop/render/xml/XMLRenderer.java
@@ -47,7 +47,7 @@ import org.apache.fop.area.BeforeFloat;
 import org.apache.fop.area.Block;
 import org.apache.fop.area.BlockViewport;
 import org.apache.fop.area.BodyRegion;
-import org.apache.fop.area.Flow;
+import org.apache.fop.area.NormalFlow;
 import org.apache.fop.area.Footnote;
 import org.apache.fop.area.LineArea;
 import org.apache.fop.area.MainReference;
@@ -445,7 +445,7 @@ public class XMLRenderer extends AbstractRenderer {
             addTraitAttributes(span);
             startElement("span", atts);
             for (int c = 0; c < span.getColumnCount(); c++) {
-                Flow flow = (Flow) span.getFlow(c);
+                NormalFlow flow = (NormalFlow) span.getNormalFlow(c);
 
                 renderFlow(flow);
             }
@@ -457,7 +457,7 @@ public class XMLRenderer extends AbstractRenderer {
     /**
      * @see org.apache.fop.render.AbstractRenderer#renderFlow(Flow)
      */
-    protected void renderFlow(Flow flow) {
+    protected void renderFlow(NormalFlow flow) {
         // the normal flow reference area contains stacked blocks
         atts.clear();
         addAreaAttributes(flow);