[FOray-commit] SF.net SVN: foray:[11807] trunk/foray/foray-pdf/src/main/java/org/foray/ pdf/object

[<vic...@us...>]

Revision: 11807
          http://sourceforge.net/p/foray/code/11807
Author:   victormote
Date:     2021-01-17 15:25:28 +0000 (Sun, 17 Jan 2021)
Log Message:
-----------
Doc changes only.

Modified Paths:
--------------
    trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXform.java
    trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXimage.java
    trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXobject.java

Modified: trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXform.java
===================================================================
--- trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXform.java	2021-01-17 00:33:06 UTC (rev 11806)
+++ trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXform.java	2021-01-17 15:25:28 UTC (rev 11807)
@@ -36,7 +36,32 @@
 import java.awt.geom.AffineTransform;
 
 /**
- * Represents a "Form" XObject.
+ * <p>Represents a Form XObject.
+ * The use of the term "form" here is a bit confusing, and appears to be retained for historical reasons related to
+ * PDF's roots in the PostScript language.
+ * It has nothing to do with interactive forms in general, nor AcroForm in particular.
+ * Instead a Form XObject allows content that could be written into a {@link org.axsl.pdf.PdfContentStream} directly to
+ * be handled as an independent, self-contained object that is simply called as needed when creating the content stream.
+ * Using this approach has several benefits, including:</p>
+ * <ul>
+ *   <li>Reusability. The object can be called from multiple pages or all pages.
+ *   In a 100 page document that used the content on each page, it is defined only once, but used 100 times, resulting
+ *   in a much more compact PDF document.</li>
+ *   <li>Independence. The process of writing the content is separate from its placement, scaling, rotation, etc. in the
+ *   stream.
+ *   This has implicatons for reusability, but also provides a separation of concerns for development, as it allows the
+ *   creation of the content to be separated from how it is used in the document.</li>
+ *   <li></li>
+ * </ul>
+ *
+ * <p>For content that is only to be used one time in a document, there is some overhead associated with creating and
+ * using the content as an object instead of writing it directly in a content stream.
+ * In this case, the benefit of reusability does not exist.
+ * However, the benefit of independence may well outweigh the small cost of creating the content as a Form XObject.
+ * <p>
+ *
+ * @see "PDF Reference, Sixth Edition (PDF Version 1.7), Section 4.9, for Form XObjects, including a Note that explains
+ * the meaning of the term \"form\" in this context."
  */
 public abstract class PdfXform extends PdfXobject {
 

Modified: trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXimage.java
===================================================================
--- trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXimage.java	2021-01-17 00:33:06 UTC (rev 11806)
+++ trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXimage.java	2021-01-17 15:25:28 UTC (rev 11807)
@@ -44,10 +44,11 @@
 import java.awt.geom.Rectangle2D;
 
 /**
- * A sampled image that is to be embedded in a PDF File. Images in PDF are
- * XObjects (external objects).
+ * A sampled image that is to be embedded in a PDF File.
+ * Images in PDF can either be written directly into the content stream or handled as XObjects (external objects).
  *
  * @see PdfXobject
+ * @see "PDF Reference, Sixth Edition (PDF Version 1.7), Section 4.8.4."
  */
 public class PdfXimage extends PdfXobject {
 

Modified: trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXobject.java
===================================================================
--- trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXobject.java	2021-01-17 00:33:06 UTC (rev 11806)
+++ trunk/foray/foray-pdf/src/main/java/org/foray/pdf/object/PdfXobject.java	2021-01-17 15:25:28 UTC (rev 11807)
@@ -49,12 +49,15 @@
 import java.io.OutputStream;
 
 /**
- * PDF XObject (external object), aka a "named resource". Used to represent
- * 1) bitmap images, 2) form XObjects (reusable sequences of other graphical
- * objects, not to be confused with an interactive form), and 3) PostScript
- * XObjects (whose use is unnecessary and deprecated).
+ * <p>Abstract superclass for PDF XObject or external object. There are three types:</p>
+ * <ul>
+ *   <li>An image XObject. See {@link PdfXimage} for a concrete implementation.</li>
+ *   <li>A form XObject. See {@link PdfXform} for a concrete implementation.</li>
+ *   <li>A PostScript XObject. The use of these is unnecessary and deprecated, and there is no concrete implementation
+ *   for it.</li>
+ * </ul>
  *
- * An XObject has not only a dictionary but a stream of image data.
+ * @see "PDF Reference, Sixth Edition (PDF Version 1.7), Section 4.7, for a general description of External Objects."
  */
 public abstract class PdfXobject extends PdfStream {
 

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.