Renamed some variables and methods for consistency.

Improved javadocs.
Code clean-up and simplification.


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

src/java/org/apache/fop/fo/extensions/InternalElementMapping.java

@@ -25,9 +25,6 @@ import java.util.Set;
 import org.apache.xmlgraphics.util.QName;
 
 import org.apache.fop.fo.ElementMapping;
-import org.apache.fop.fo.FONode;
-import org.apache.fop.fo.UnknownXMLObj;
-import org.apache.fop.fo.extensions.destination.Destination;
 
 /**
  * Element mapping for FOP's internal extension to XSL-FO.
@@ -37,11 +34,11 @@ public class InternalElementMapping extends ElementMapping {
     /** The FOP extension namespace URI */
     public static final String URI = "http://xmlgraphics.apache.org/fop/internal";
 
-   private static final Set propertyAttributes = new java.util.HashSet();
+    private static final Set PROPERTY_ATTRIBUTES = new java.util.HashSet();
 
-   static {
+    static {
         //These are FOP's extension properties for accessibility
-        propertyAttributes.add("ptr");
+        PROPERTY_ATTRIBUTES.add("ptr");
     }
 
     /**
@@ -60,16 +57,7 @@ public class InternalElementMapping extends ElementMapping {
         }
     }
 
-    /* static class DestinationMaker extends ElementMapping.Maker {
-        public FONode make(FONode parent) {
-            return new Destination(parent);
-        }
-    } */
-
-    
-    /**
-     * used internally for accessibility
-     */
+    /** {@inheritDoc} */
     public String getStandardPrefix() {
         return "foi";
     }
@@ -79,7 +67,7 @@ public class InternalElementMapping extends ElementMapping {
         if (!URI.equals(attributeName.getNamespaceURI())) {
             throw new IllegalArgumentException("The namespace URIs don't match");
         }
-        return propertyAttributes.contains(attributeName.getLocalName());
+        return PROPERTY_ATTRIBUTES.contains(attributeName.getLocalName());
     }
 
 }

src/java/org/apache/fop/pdf/PDFFactory.java

@@ -179,7 +179,6 @@ public class PDFFactory {
      * @param cropBox the CropBox area
      * @param bleedBox the BleedBox area
      * @param trimBox the TrimBox area
-     * @param currentPageParentKey the integer key in the structural parent tree
      *
      * @return the created /Page object
      */

src/java/org/apache/fop/pdf/PDFParentTree.java

@@ -20,20 +20,14 @@
 package org.apache.fop.pdf;
 
 /**
- * Class representing a PDF /ParentTree
+ * Class representing a PDF /ParentTree.
  */
 public class PDFParentTree extends PDFNumberTreeNode {
 
     /**
-     * Create the /ParentTree NumberTreeNode
-     */
-    public PDFParentTree() {
-        super();
-    }
-
-    /**
-     * Get the parentTree.
-     * @return parentTree as PDFNumsArray
+     * Returns the number tree corresponding to this parent tree.
+     *
+     * @return the number tree
      */
     public PDFNumsArray getNums() {
         PDFNumsArray nums = super.getNums();

src/java/org/apache/fop/pdf/PDFRoot.java

@@ -66,7 +66,7 @@ public class PDFRoot extends PDFDictionary {
      */
     public PDFRoot(int objnum, PDFPages pages) {
         super();
-         setObjectNumber(objnum);
+        setObjectNumber(objnum);
         put("Type", new PDFName("Catalog"));
         setRootPages(pages);
     }

src/java/org/apache/fop/pdf/PDFStructTreeRoot.java

@@ -25,7 +25,8 @@ package org.apache.fop.pdf;
 public class PDFStructTreeRoot extends PDFDictionary {
 
     /**
-     * Create the /StructTreeRoot dictionary.
+     * Creates a new /StructTreeRoot dictionary.
+     *
      * @param parentTree the value of the ParenTree entry
      */
     PDFStructTreeRoot(PDFParentTree parentTree) {
@@ -35,16 +36,18 @@ public class PDFStructTreeRoot extends PDFDictionary {
     }
 
     /**
-     * Get the kids.
-     * @return the kids
+     * Returns the children element of this StructTreeRoot.
+     *
+     * @return the value of the K entry
      */
     public PDFArray getKids() {
         return (PDFArray)get("K");
     }
 
     /**
-     * Adds a kid.
-     * @param kid to be added
+     * Adds the given object to the array of kids.
+     *
+     * @param kid an object to be added to the K entry
      */
     public void addKid(PDFObject kid) {
         getKids().add(kid);

src/java/org/apache/fop/render/AbstractRendererConfigurator.java

@@ -30,7 +30,7 @@ import org.apache.fop.apps.FOUserAgent;
 public abstract class AbstractRendererConfigurator extends AbstractConfigurator {
 
     private static final String TYPE = "renderer";
-    
+
     /**
      * Default constructor
      * @param userAgent user agent
@@ -46,7 +46,7 @@ public abstract class AbstractRendererConfigurator extends AbstractConfigurator
      */
     protected Configuration getRendererConfig(Renderer renderer) {
         return super.getConfig(renderer.getMimeType());
-            }
+    }
 
     /**
      * Returns the configuration subtree for a specific renderer.
@@ -55,13 +55,13 @@ public abstract class AbstractRendererConfigurator extends AbstractConfigurator
      */
     protected Configuration getRendererConfig(String mimeType) {
         return super.getConfig(mimeType);
-            }
-    
+    }
+
     /**
      * {@inheritDoc}
      */
     public String getType() {
         return TYPE;
-        }
+    }
 
 }

src/java/org/apache/fop/render/intermediate/IFConstants.java

@@ -50,6 +50,6 @@ public interface IFConstants extends XMLConstants {
     String EL_BORDER_RECT = "border-rect";
     String EL_FONT = "font";
     String EL_TEXT = "text";
-    /** used for accessibility */
-    String EL_STRUCTURE_TREE = "structure-tree";  
+    /** Parent element of the logical structure tree. */
+    String EL_STRUCTURE_TREE = "structure-tree";
 }

src/java/org/apache/fop/render/intermediate/IFParser.java

@@ -551,7 +551,7 @@ public class IFParser implements IFConstants {
                 s = lastAttributes.getValue("word-spacing");
                 int wordSpacing = (s != null ? Integer.parseInt(s) : 0);
                 int[] dx = XMLUtil.getAttributeAsIntArray(lastAttributes, "dx");
-                setAccessibilityPointer(lastAttributes);
+                setStructurePointer(lastAttributes);
                 painter.drawText(x, y, letterSpacing, wordSpacing, dx, content.toString());
                 resetStructurePointer();
             }
@@ -648,7 +648,7 @@ public class IFParser implements IFConstants {
                 int height = Integer.parseInt(lastAttributes.getValue("height"));
                 Map foreignAttributes = getForeignAttributes(lastAttributes);
                 establishForeignAttributes(foreignAttributes);
-                setAccessibilityPointer(lastAttributes);
+                setStructurePointer(lastAttributes);
                 if (foreignObject != null) {
                     painter.drawImage(foreignObject,
                             new Rectangle(x, y, width, height));
@@ -716,7 +716,7 @@ public class IFParser implements IFConstants {
             return foreignAttributes;
         }
 
-        private void setAccessibilityPointer(Attributes attributes) {
+        private void setStructurePointer(Attributes attributes) {
             String ptr = attributes.getValue("ptr");
             if (ptr != null && ptr.length() > 0) {
                 establishStructurePointer(ptr);

src/java/org/apache/fop/render/intermediate/IFRenderer.java

@@ -961,7 +961,7 @@ public class IFRenderer extends AbstractPathOrientedRenderer {
 
         // warn if link trait found but not allowed, else create link
         if (linkTraitFound) {
-            action.setPtr(ptr);  // used for accessibility
+            action.setStructurePointer(ptr);  // used for accessibility
             Link link = new Link(action, ipRect);
             this.deferredLinks.add(link);
         }

src/java/org/apache/fop/render/intermediate/IFSerializer.java

@@ -411,10 +411,7 @@ public class IFSerializer extends AbstractXMLWritingIFDocumentHandler
             addAttribute(atts, "width", Integer.toString(rect.width));
             addAttribute(atts, "height", Integer.toString(rect.height));
             addForeignAttributes(atts);
-            String ptr = getContext().getStructurePointer();
-            if (ptr != null) {
-                addAttribute(atts, "ptr", ptr);  // used for accessibility
-            }
+            addStructurePointerAttribute(atts);
             handler.element(EL_IMAGE, atts);
         } catch (SAXException e) {
             throw new IFException("SAX error in startGroup()", e);
@@ -441,10 +438,7 @@ public class IFSerializer extends AbstractXMLWritingIFDocumentHandler
             addAttribute(atts, "width", Integer.toString(rect.width));
             addAttribute(atts, "height", Integer.toString(rect.height));
             addForeignAttributes(atts);
-            String ptr = getContext().getStructurePointer();
-            if (ptr != null) {
-                addAttribute(atts, "ptr", ptr);  // used for accessibility
-            }
+            addStructurePointerAttribute(atts);
             handler.startElement(EL_IMAGE, atts);
             new DOM2SAX(handler).writeDocument(doc, true);
             handler.endElement(EL_IMAGE);
@@ -558,10 +552,7 @@ public class IFSerializer extends AbstractXMLWritingIFDocumentHandler
             if (dx != null) {
                 addAttribute(atts, "dx", IFUtil.toString(dx));
             }
-            String ptr = getContext().getStructurePointer();
-            if (ptr != null) {
-                addAttribute(atts, "ptr", ptr);  // used for accessibility
-            }
+            addStructurePointerAttribute(atts);
             handler.startElement(EL_TEXT, atts);
             char[] chars = text.toCharArray();
             handler.characters(chars, 0, chars.length);
@@ -657,6 +648,13 @@ public class IFSerializer extends AbstractXMLWritingIFDocumentHandler
         XMLUtil.addAttribute(atts, localName, value);
     }
 
+    private void addStructurePointerAttribute(AttributesImpl atts) {
+        String ptr = getContext().getStructurePointer();
+        if (ptr != null) {
+            addAttribute(atts, "ptr", ptr);
+        }
+    }
+
     // ---=== IFDocumentNavigationHandler ===---
 
     private Map incompleteActions = new java.util.HashMap();
@@ -729,7 +727,7 @@ public class IFSerializer extends AbstractXMLWritingIFDocumentHandler
         atts.addAttribute(null, "rect", "rect",
                 XMLConstants.CDATA, IFUtil.toString(link.getTargetRect()));
         if (getUserAgent().isAccessibilityEnabled()) {
-            addAttribute(atts, "ptr", link.getAction().getPtr());
+            addAttribute(atts, "ptr", link.getAction().getStructurePointer());
         }
         try {
             handler.startElement(DocumentNavigationExtensionConstants.LINK, atts);

src/java/org/apache/fop/render/intermediate/extensions/AbstractAction.java

@@ -27,7 +27,7 @@ import org.apache.xmlgraphics.util.XMLizable;
 public abstract class AbstractAction implements XMLizable {
 
     private String id;
-    private String ptr; // used for accessibility
+    private String structurePointer;
 
     /**
      * Sets an ID to make the action referencable.
@@ -44,23 +44,23 @@ public abstract class AbstractAction implements XMLizable {
     public String getID() {
         return this.id;
     }
-    
+
     /**
-     * Used for accessibility   
-     * @param s representing the ptr
+     * Sets the structure element corresponding to this action.
+     * @param structurePointer a reference to the structure element
      */
-    public void setPtr(String s) {
-        this.ptr = s;
+    public void setStructurePointer(String structurePointer) {
+        this.structurePointer = structurePointer;
     }
-    
+
     /**
-     * Used for accessibility
-     * @return the ptr
+     * Returns the structure element corresponding to this action.
+     * @return the reference to the structure element
      */
-    public String getPtr() {
-        return this.ptr;
+    public String getStructurePointer() {
+        return structurePointer;
     }
-    
+
     /**
      * Indicates whether the action has an ID and is therefore referencable.
      * @return true if the action has an ID

src/java/org/apache/fop/render/intermediate/extensions/DocumentNavigationHandler.java

@@ -48,7 +48,7 @@ public class DocumentNavigationHandler extends DefaultHandler
 
     private IFDocumentNavigationHandler navHandler;
 
-    private String accessibilityPointer;
+    private String structurePointer;
 
     /**
      * Main constructor.
@@ -98,7 +98,7 @@ public class DocumentNavigationHandler extends DefaultHandler
                     throw new SAXException(localName + " must be the root element!");
                 }
                 Rectangle targetRect = XMLUtil.getAttributeAsRectangle(attributes, "rect");
-                accessibilityPointer = attributes.getValue("ptr");
+                structurePointer = attributes.getValue("ptr");
                 Link link = new Link(null, targetRect);
                 objectStack.push(link);
             } else if (GOTO_XY.getLocalName().equals(localName)) {
@@ -121,8 +121,8 @@ public class DocumentNavigationHandler extends DefaultHandler
                     }
                     action = new GoToXYAction(id, pageIndex, location);
                 }
-                if (accessibilityPointer != null) {
-                    action.setPtr(accessibilityPointer);
+                if (structurePointer != null) {
+                    action.setStructurePointer(structurePointer);
                 }
                 objectStack.push(action);
             } else if (GOTO_URI.getLocalName().equals(localName)) {
@@ -134,8 +134,8 @@ public class DocumentNavigationHandler extends DefaultHandler
                 if (id != null) {
                     action.setID(id);
                 }
-                if (accessibilityPointer != null) {
-                    action.setPtr(accessibilityPointer);
+                if (structurePointer != null) {
+                    action.setStructurePointer(structurePointer);
                 }
                 objectStack.push(action);
             } else {

src/java/org/apache/fop/render/pdf/PDFContentGenerator.java

@@ -168,13 +168,13 @@ public class PDFContentGenerator {
      * the sequenceNum is ignored and instead of a BDC with the MCID as parameter, an "Artifact"
      * and a BMC command is generated.
      * @param structElemType Structure Element Type
-     * @param sequenceNum    Sequence number
+     * @param mcid    Sequence number
      */
-    protected void beginMarkedContentSequence(String structElemType, int sequenceNum) {
+    protected void beginMarkedContentSequence(String structElemType, int mcid) {
         assert !this.inMarkedContentSequence;
         assert !this.inArtifactMode;
         if (structElemType != null) {
-            currentStream.add(structElemType + " <</MCID " + String.valueOf(sequenceNum) + ">>\n"
+            currentStream.add(structElemType + " <</MCID " + String.valueOf(mcid) + ">>\n"
                     + "BDC\n");
         } else {
             currentStream.add("/Artifact\nBMC\n");
@@ -202,12 +202,18 @@ public class PDFContentGenerator {
         }
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Same as {@link #restoreGraphicsState(boolean)}, with <code>true</code> as
+     * a parameter.
+     */
     protected void restoreGraphicsState() {
         restoreGraphicsState(true);
     }
 
-    /** used for accessibility */
+    /**
+     * Same as {@link #restoreGraphicsState()}, additionally ending the current
+     * marked content sequence if any.
+     */
     protected void restoreGraphicsStateAccess() {
         endTextObject();
         currentStream.add("Q\n");
@@ -218,9 +224,12 @@ public class PDFContentGenerator {
     }
 
     /**
-     * used for accessibility, separates 2 text elements
-     * @param structElemType of parent of new text element
-     * @param mcid of new text element
+     * Separates 2 text elements, ending the current marked content sequence and
+     * starting a new one.
+     *
+     * @param structElemType structure element type
+     * @param mcid sequence number
+     * @see #beginMarkedContentSequence(String, int)
      */
     protected void separateTextElements(String structElemType, int mcid) {
         textutil.endTextObject();
@@ -237,24 +246,20 @@ public class PDFContentGenerator {
     }
 
     /**
-     * Accessibility beginTextObject
-     * @param structElemType of parent
-     * @param mcid of text element
+     * Indicates the beginning of a marked-content text object.
+     *
+     * @param structElemType structure element type
+     * @param mcid sequence number
+     * @see #beginTextObject()
+     * @see #beginMarkedContentSequence(String, int)
      */
-    protected void beginTextObjectAccess(String structElemType, int mcid) {
+    protected void beginTextObject(String structElemType, int mcid) {
         if (!textutil.isInTextObject()) {
             beginMarkedContentSequence(structElemType, mcid);
             textutil.beginTextObject();
         }
     }
 
-    /**
-     * Accessibility begin of LeaderTextObject
-     */
-    public void beginLeaderTextObject() {
-        beginTextObjectAccess(null, 0);
-    }
-
     /** Indicates the end of a text object. */
     protected void endTextObject() {
         if (textutil.isInTextObject()) {
@@ -407,15 +412,17 @@ public class PDFContentGenerator {
     }
 
     /**
-     * Places a previously registered image at a certain place on the page.
-     * Accessibility version
+     * Places a previously registered image at a certain place on the page,
+     * bracketing it as a marked-content sequence.
+     *
      * @param x X coordinate
      * @param y Y coordinate
      * @param w width for image
      * @param h height for image
      * @param xobj the image XObject
-     * @param structElemType of this image
-     * @param mcid of this image
+     * @param structElemType structure element type
+     * @param mcid sequence number
+     * @see #beginMarkedContentSequence(String, int)
      */
     public void placeImage(float x, float y, float w, float h, PDFXObject xobj,
             String structElemType, int mcid) {

src/java/org/apache/fop/render/pdf/PDFDocumentNavigationHandler.java

@@ -25,9 +25,6 @@ import java.awt.geom.Rectangle2D;
 import java.util.Iterator;
 import java.util.Map;
 
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
-
 import org.apache.fop.pdf.PDFAction;
 import org.apache.fop.pdf.PDFDocument;
 import org.apache.fop.pdf.PDFFactory;
@@ -49,7 +46,7 @@ import org.apache.fop.render.pdf.PDFDocumentHandler.PageReference;
  * Implementation of the {@link IFDocumentNavigationHandler} interface for PDF output.
  */
 public class PDFDocumentNavigationHandler implements IFDocumentNavigationHandler {
-    private static Log log = LogFactory.getLog(PDFDocumentHandler.class);
+
     private final PDFDocumentHandler documentHandler;
 
     private final Map incompleteActions = new java.util.HashMap();
@@ -114,8 +111,7 @@ public class PDFDocumentNavigationHandler implements IFDocumentNavigationHandler
         PDFLink pdfLink = getPDFDoc().getFactory().makeLink(
                 targetRect2D, pdfAction);
         if (pdfLink != null) {
-          //accessibility: ptr has a value
-            String ptr = link.getAction().getPtr();
+            String ptr = link.getAction().getStructurePointer();
             if (ptr != null && ptr.length() > 0) {
                 documentHandler.getLogicalStructureHandler().addLinkContentItem(pdfLink, ptr);
             }

src/java/org/apache/fop/render/pdf/PDFLogicalStructureHandler.java

@@ -204,8 +204,8 @@ class PDFLogicalStructureHandler {
         parentTree.getNums().put(currentPage.getStructParents(), pageParentTreeArray);
     }
 
-    private MarkedContentInfo addToParentTree(String reference) {
-        PDFStructElem parent = (PDFStructElem) structTreeMap.get(reference);
+    private MarkedContentInfo addToParentTree(String structurePointer) {
+        PDFStructElem parent = (PDFStructElem) structTreeMap.get(structurePointer);
         if (parent == null) {
             return ARTIFACT;
         } else {
@@ -220,7 +220,7 @@ class PDFLogicalStructureHandler {
      * Adds a content item corresponding to text into the structure tree, if
      * there is a structure element associated to it.
      *
-     * @param parentReference reference to the parent structure element of the
+     * @param structurePointer reference to the parent structure element of the
      * piece of text
      * @return the necessary information for bracketing the content as a
      * marked-content sequence. If there is no element in the structure tree
@@ -228,8 +228,8 @@ class PDFLogicalStructureHandler {
      * {@link MarkedContentInfo#tag} value is <code>null</code>. The content
      * must then be treated as an artifact.
      */
-    MarkedContentInfo addTextContentItem(String parentReference) {
-        MarkedContentInfo mci = addToParentTree(parentReference);
+    MarkedContentInfo addTextContentItem(String structurePointer) {
+        MarkedContentInfo mci = addToParentTree(structurePointer);
         if (mci != ARTIFACT) {
             PDFDictionary contentItem = new PDFDictionary();
             contentItem.put("Type", MCR);
@@ -244,7 +244,7 @@ class PDFLogicalStructureHandler {
      * Adds a content item corresponding to an image into the structure tree, if
      * there is a structure element associated to it.
      *
-     * @param parentReference reference to the parent structure element of the
+     * @param structurePointer reference to the parent structure element of the
      * image
      * @return the necessary information for bracketing the content as a
      * marked-content sequence. If there is no element in the structure tree
@@ -252,8 +252,8 @@ class PDFLogicalStructureHandler {
      * {@link MarkedContentInfo#tag} value is <code>null</code>. The image
      * must then be treated as an artifact.
      */
-    MarkedContentInfo addImageContentItem(String parentReference) {
-        MarkedContentInfo mci = addToParentTree(parentReference);
+    MarkedContentInfo addImageContentItem(String structurePointer) {
+        MarkedContentInfo mci = addToParentTree(structurePointer);
         if (mci != ARTIFACT) {
             mci.parent.setMCIDKid(mci.mcid);
             mci.parent.setPage(this.currentPage);
@@ -282,9 +282,9 @@ class PDFLogicalStructureHandler {
      * tree.
      *
      * @param link a link
-     * @param reference reference to the corresponding parent structure element
+     * @param structurePointer reference to the corresponding parent structure element
      */
-    void addLinkContentItem(PDFLink link, String reference) {
+    void addLinkContentItem(PDFLink link, String structurePointer) {
         int structParent = getNextParentTreeKey();
         link.setStructParent(structParent);
         parentTree.getNums().put(structParent, link);
@@ -292,7 +292,7 @@ class PDFLogicalStructureHandler {
         contentItem.put("Type", OBJR);
         contentItem.put("Pg", this.currentPage);
         contentItem.put("Obj", link);
-        PDFStructElem parent = (PDFStructElem) structTreeMap.get(reference);
+        PDFStructElem parent = (PDFStructElem) structTreeMap.get(structurePointer);
         parent.addKid(contentItem);
     }
 

src/java/org/apache/fop/render/pdf/PDFPainter.java

@@ -302,7 +302,7 @@ public class PDFPainter extends AbstractIFPainter {
                 generator.separateTextElements(mci.tag, mci.mcid);
             }
             generator.updateColor(state.getTextColor(), true, null);
-            generator.beginTextObjectAccess(mci.tag, mci.mcid);
+            generator.beginTextObject(mci.tag, mci.mcid);
         } else {
             generator.updateColor(state.getTextColor(), true, null);
             generator.beginTextObject();

src/java/org/apache/fop/render/pdf/PDFRenderer.java

@@ -973,7 +973,7 @@ public class PDFRenderer extends AbstractPathOrientedRenderer implements PDFConf
             if (generator.getTextUtil().isInTextObject()) {
                 generator.separateTextElements(mci.tag, mci.mcid);
             }
-            generator.beginTextObjectAccess(mci.tag, mci.mcid);
+            generator.beginTextObject(mci.tag, mci.mcid);
         } else {
             beginTextObject();
         }

src/java/org/apache/fop/render/pdf/PDFRenderingUtil.java

@@ -110,7 +110,7 @@ class PDFRenderingUtil implements PDFConfigurationConstants {
 
     private void initialize() {
         PDFEncryptionParams params
-            = (PDFEncryptionParams)userAgent.getRendererOptions().get(ENCRYPTION_PARAMS);
+                = (PDFEncryptionParams)userAgent.getRendererOptions().get(ENCRYPTION_PARAMS);
         if (params != null) {
             this.encryptionParams = params; //overwrite if available
         }