svn commit: r1602321 - /pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/rendering/PDFPrinter.java

[ja...@apache.org]

Author: jahewson
Date: Fri Jun 13 01:35:24 2014
New Revision: 1602321

URL: http://svn.apache.org/r1602321
Log:
PDFBOX-2119: update JavaDoc for clarification

Modified:
    pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/rendering/PDFPrinter.java

Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/rendering/PDFPrinter.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/rendering/PDFPrinter.java?rev=1602321&r1=1602320&r2=1602321&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/rendering/PDFPrinter.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/rendering/PDFPrinter.java Fri Jun 13 01:35:24 2014
@@ -42,7 +42,7 @@ import java.io.IOException;
  * Prints a PDF document using AWT.
  * This class may be overridden in order to perform custom printing.
  *
- * @author Andreas Lehmk�hler
+ * @author Andreas Lehmkühler
  * @author John Hewson
  */
 public class PDFPrinter
@@ -57,7 +57,7 @@ public class PDFPrinter
     protected final float dpi;
 
     /**
-     * Creates a new PDFPrinter.
+     * Creates a new PDFPrinter using the system's default printer.
      * @param document the document to print
      */
     public PDFPrinter(PDDocument document) throws PrinterException
@@ -66,7 +66,7 @@ public class PDFPrinter
     }
 
     /**
-     * Creates a new PDFPrinter for a given printer job.
+     * Creates a new PDFPrinter using the given printer.
      * @param document the document to print
      * @param printerJob the printer job to use
      */
@@ -76,7 +76,9 @@ public class PDFPrinter
     }
 
     /**
-     * Creates a new PDFPrinter with the given page scaling and orientation.
+     * Creates a new PDFPrinter using the system's default printer,
+     * with the given page scaling and orientation.
+     *
      * @param document the document to print
      * @param scaling page scaling policy
      * @param orientation page orientation policy
@@ -88,7 +90,9 @@ public class PDFPrinter
     }
 
     /**
-     * Creates a new PDFPrinter with the given page scaling and orientation.
+     * Creates a new PDFPrinter using the system's default printer,
+     * with the given page scaling and orientation.
+     *
      * @param document the document to print
      * @param scaling page scaling policy
      * @param orientation page orientation policy
@@ -100,7 +104,9 @@ public class PDFPrinter
     }
 
     /**
-     * Creates a new PDFPrinter with the given page scaling and orientation.
+     * Creates a new PDFPrinter using the system's default printer,
+     * with the given page scaling and orientation.
+     *
      * @param document the document to print
      * @param scaling page scaling policy
      * @param orientation page orientation policy
@@ -113,8 +119,9 @@ public class PDFPrinter
     }
 
     /**
-     * Creates a new PDFPrinter for a given printer job, the given page scaling and orientation,
+     * Creates a new PDFPrinter using the given printer, the given page scaling and orientation,
      * and with optional page borders shown.
+     *
      * @param document the document to print
      * @param printerJob the printer job to use
      * @param scaling page scaling policy
@@ -173,6 +180,7 @@ public class PDFPrinter
      * The image is generated using {@link PageDrawer}.
      * This is a convenience method to create the java.awt.print.PrinterJob.
      * Advanced printing tasks can be performed using {@link #getPageable()} instead.
+     *
      * @throws PrinterException if the document cannot be printed
      */
     public void print() throws PrinterException
@@ -190,7 +198,9 @@ public class PDFPrinter
         print(printerJob, false);
     }
 
-    // todo: new
+    /**
+     * Returns the Pageable instance used in this class. Can be overridden by subclasses.
+     */
     public PDFPageable getPageable()
     {
         return new PDFPageable();
@@ -224,6 +234,10 @@ public class PDFPrinter
         @Override
         public PageFormat getPageFormat(int pageIndex) throws IndexOutOfBoundsException
         {
+            // note: PDFPrintable#print() is responsible for fitting the current page to
+            //       the printer's actual paper size, so this method must return the full
+            //       physical, printable size of the actual paper in the printer.
+
             PageFormat format = printerJob.defaultPage();
             PDPage page = document.getPage(pageIndex);