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

6 files changed, 55 insertions, 39 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);
     }
 
 }