svn commit: r1750876 - /pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/text/TextPosition.java

[ti...@apache.org]

Author: tilman
Date: Fri Jul  1 05:14:42 2016
New Revision: 1750876

URL: http://svn.apache.org/viewvc?rev=1750876&view=rev
Log:
PDFBOX-3405: clarify javadoc

Modified:
    pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/text/TextPosition.java

Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/text/TextPosition.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/text/TextPosition.java?rev=1750876&r1=1750875&r2=1750876&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/text/TextPosition.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/text/TextPosition.java Fri Jul  1 05:14:42 2016
@@ -110,7 +110,7 @@ public final class TextPosition
      * @param pageRotation rotation of the page that the text is located in
      * @param pageWidth rotation of the page that the text is located in
      * @param pageHeight rotation of the page that the text is located in
-     * @param textMatrix TextMatrix for start of text (in display units)
+     * @param textMatrix text rendering matrix for start of text (in display units)
      * @param endX x coordinate of the end position
      * @param endY y coordinate of the end position
      * @param maxHeight Maximum height of text (in display units)
@@ -179,7 +179,10 @@ public final class TextPosition
     }
 
     /**
-     * Return the text matrix stored in this object.
+     * The matrix containing the starting text position and scaling. Despite the name, it is not the
+     * text matrix set by the "Tm" operator, it is really the effective text rendering matrix (which
+     * is dependent on the current transformation matrix, the text matrix, the font size and the
+     * page cropbox).
      *
      * @return The Matrix containing the starting text position
      */
@@ -403,7 +406,9 @@ public final class TextPosition
     }
 
     /**
-     * This will get the font size that this object is suppose to be drawn at.
+     * This will get the font size that has been set with the "Tf" operator (Set text font and
+     * size). When the text is rendered, it may appear bigger or smaller depending on the current
+     * transformation matrix and the text matrix.
      *
      * @return The font size.
      */
@@ -413,8 +418,12 @@ public final class TextPosition
     }
 
     /**
-     * This will get the font size in pt. To get this size we have to multiply the pdf-fontsize
-     * and the scaling from the textmatrix
+     * This will get the font size in pt. To get this size we have to multiply the font size from
+     * {@link #getFontSize() getFontSize()} with the text matrix (set by the "Tm" operator)
+     * horizontal scaling factor and truncate the result to integer. The actual rendering may appear
+     * bigger or smaller depending on the current transformation matrix (set by the "cm" operator).
+     * To get the size in rendering, use
+     * {@link #getTextMatrix() getTextMatrix()}.{@link Matrix#getScalingFactorX() getScalingFactorX()}.
      *
      * @return The font size in pt.
      */