poi-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ye...@apache.org
Subject svn commit: r1137656 - in /poi/trunk/src: documentation/content/xdocs/status.xml java/org/apache/poi/hssf/usermodel/HSSFSheet.java java/org/apache/poi/ss/usermodel/Sheet.java ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java
Date Mon, 20 Jun 2011 15:16:46 GMT
Author: yegor
Date: Mon Jun 20 15:16:46 2011
New Revision: 1137656

URL: http://svn.apache.org/viewvc?rev=1137656&view=rev
Log:
Bug 48408: Improved documentation for Sheet.setColumnWidth

Modified:
    poi/trunk/src/documentation/content/xdocs/status.xml
    poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java
    poi/trunk/src/java/org/apache/poi/ss/usermodel/Sheet.java
    poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java

Modified: poi/trunk/src/documentation/content/xdocs/status.xml
URL: http://svn.apache.org/viewvc/poi/trunk/src/documentation/content/xdocs/status.xml?rev=1137656&r1=1137655&r2=1137656&view=diff
==============================================================================
--- poi/trunk/src/documentation/content/xdocs/status.xml (original)
+++ poi/trunk/src/documentation/content/xdocs/status.xml Mon Jun 20 15:16:46 2011
@@ -34,6 +34,7 @@
 
     <changes>
         <release version="3.8-beta4" date="2011-??-??">
+           <action dev="poi-developers" type="fix">48408 - Improved documentation for
Sheet.setColumnWidth </action>
            <action dev="poi-developers" type="add">51390 - Added handling of additional
properties to HWPF ParagraphSprmCompressor</action>
            <action dev="poi-developers" type="add">51389 - Support for sprmPJc paragraph
SPRM in HWPF</action>
            <action dev="poi-developers" type="fix">48469 - New Case Study for PI web
site  </action>

Modified: poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java?rev=1137656&r1=1137655&r2=1137656&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java (original)
+++ poi/trunk/src/java/org/apache/poi/hssf/usermodel/HSSFSheet.java Mon Jun 20 15:16:46 2011
@@ -429,15 +429,47 @@ public final class HSSFSheet implements 
 
     /**
      * Set the width (in units of 1/256th of a character width)
+     *
      * <p>
      * The maximum column width for an individual cell is 255 characters.
      * This value represents the number of characters that can be displayed
-     * in a cell that is formatted with the standard font.
+     * in a cell that is formatted with the standard font (first font in the workbook).
+     * </p>
+     *
+     * <p>
+     * Character width is defined as the maximum digit width
+     * of the numbers <code>0, 1, 2, … 9</code> as rendered
+     * using the default font (first font in the workbook).
+     * <br/>
+     * Unless you are using a very special font, the default character is '0' (zero),
+     * this is true for Arial (default font font in HSSF) and Calibri (default font in XSSF)
+     * </p>
+     *
+     * <p>
+     * Please note, that the width set by this method includes 4 pixels of margin padding
(two on each side),
+     * plus 1 pixel padding for the gridlines (Section 3.3.1.12 of the OOXML spec).
+     * This results is a slightly less value of visible characters than passed to this method
(approx. 1/2 of a character).
      * </p>
+     * <p>
+     * To compute the actual number of visible characters,
+     *  Excel uses the following formula (Section 3.3.1.12 of the OOXML spec):
+     * </p>
+     * <code>
+     *     width = Truncate([{Number of Visible Characters} *
+     *      {Maximum Digit Width} + {5 pixel padding}]/{Maximum Digit Width}*256)/256
+     * </code>
+     * <p>Using the Calibri font as an example, the maximum digit width of 11 point
font size is 7 pixels (at 96 dpi).
+     *  If you set a column width to be eight characters wide, e.g. <code>setColumnWidth(columnIndex,
8*256)</code>,
+     *  then the actual value of visible characters (the value shown in Excel) is derived
from the following equation:
+     *  <code>
+            Truncate([numChars*7+5]/7*256)/256 = 8;
+     *  </code>
+     *
+     *  which gives <code>7.29</code>.
      *
      * @param columnIndex - the column to set (0-based)
      * @param width - the width in units of 1/256th of a character width
-     * @throws IllegalArgumentException if width > 65280 (the maximum column width in
Excel)
+     * @throws IllegalArgumentException if width > 255*256 (the maximum column width in
Excel is 255 characters)
      */
     public void setColumnWidth(int columnIndex, int width) {
         _sheet.setColumnWidth(columnIndex, width);

Modified: poi/trunk/src/java/org/apache/poi/ss/usermodel/Sheet.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/java/org/apache/poi/ss/usermodel/Sheet.java?rev=1137656&r1=1137655&r2=1137656&view=diff
==============================================================================
--- poi/trunk/src/java/org/apache/poi/ss/usermodel/Sheet.java (original)
+++ poi/trunk/src/java/org/apache/poi/ss/usermodel/Sheet.java Mon Jun 20 15:16:46 2011
@@ -118,19 +118,59 @@ public interface Sheet extends Iterable<
 
     /**
      * Set the width (in units of 1/256th of a character width)
+     *
      * <p>
      * The maximum column width for an individual cell is 255 characters.
      * This value represents the number of characters that can be displayed
-     * in a cell that is formatted with the standard font.
+     * in a cell that is formatted with the standard font (first font in the workbook).
+     * </p>
+     *
+     * <p>
+     * Character width is defined as the maximum digit width
+     * of the numbers <code>0, 1, 2, … 9</code> as rendered
+     * using the default font (first font in the workbook).
+     * <br/>
+     * Unless you are using a very special font, the default character is '0' (zero),
+     * this is true for Arial (default font font in HSSF) and Calibri (default font in XSSF)
+     * </p>
+     *
+     * <p>
+     * Please note, that the width set by this method includes 4 pixels of margin padding
(two on each side),
+     * plus 1 pixel padding for the gridlines (Section 3.3.1.12 of the OOXML spec).
+     * This results is a slightly less value of visible characters than passed to this method
(approx. 1/2 of a character).
      * </p>
+     * <p>
+     * To compute the actual number of visible characters,
+     *  Excel uses the following formula (Section 3.3.1.12 of the OOXML spec):
+     * </p>
+     * <code>
+     *     width = Truncate([{Number of Visible Characters} *
+     *      {Maximum Digit Width} + {5 pixel padding}]/{Maximum Digit Width}*256)/256
+     * </code>
+     * <p>Using the Calibri font as an example, the maximum digit width of 11 point
font size is 7 pixels (at 96 dpi).
+     *  If you set a column width to be eight characters wide, e.g. <code>setColumnWidth(columnIndex,
8*256)</code>,
+     *  then the actual value of visible characters (the value shown in Excel) is derived
from the following equation:
+     *  <code>
+            Truncate([numChars*7+5]/7*256)/256 = 8;
+     *  </code>
+     *
+     *  which gives <code>7.29</code>.
      *
      * @param columnIndex - the column to set (0-based)
      * @param width - the width in units of 1/256th of a character width
+     * @throws IllegalArgumentException if width > 255*256 (the maximum column width in
Excel is 255 characters)
      */
     void setColumnWidth(int columnIndex, int width);
 
     /**
      * get the width (in units of 1/256th of a character width )
+     *
+     * <p>
+     * Character width is defined as the maximum digit width
+     * of the numbers <code>0, 1, 2, … 9</code> as rendered
+     * using the default font (first font in the workbook)
+     * </p>
+     *
      * @param columnIndex - the column to set (0-based)
      * @return width - the width in units of 1/256th of a character width
      */

Modified: poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java
URL: http://svn.apache.org/viewvc/poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java?rev=1137656&r1=1137655&r2=1137656&view=diff
==============================================================================
--- poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java (original)
+++ poi/trunk/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFSheet.java Mon Jun 20 15:16:46
2011
@@ -1899,15 +1899,47 @@ public class XSSFSheet extends POIXMLDoc
 
     /**
      * Set the width (in units of 1/256th of a character width)
+     *
      * <p>
      * The maximum column width for an individual cell is 255 characters.
      * This value represents the number of characters that can be displayed
-     * in a cell that is formatted with the standard font.
+     * in a cell that is formatted with the standard font (first font in the workbook).
+     * </p>
+     *
+     * <p>
+     * Character width is defined as the maximum digit width
+     * of the numbers <code>0, 1, 2, … 9</code> as rendered
+     * using the default font (first font in the workbook).
+     * <br/>
+     * Unless you are using a very special font, the default character is '0' (zero),
+     * this is true for Arial (default font font in HSSF) and Calibri (default font in XSSF)
+     * </p>
+     *
+     * <p>
+     * Please note, that the width set by this method includes 4 pixels of margin padding
(two on each side),
+     * plus 1 pixel padding for the gridlines (Section 3.3.1.12 of the OOXML spec).
+     * This results is a slightly less value of visible characters than passed to this method
(approx. 1/2 of a character).
      * </p>
+     * <p>
+     * To compute the actual number of visible characters,
+     *  Excel uses the following formula (Section 3.3.1.12 of the OOXML spec):
+     * </p>
+     * <code>
+     *     width = Truncate([{Number of Visible Characters} *
+     *      {Maximum Digit Width} + {5 pixel padding}]/{Maximum Digit Width}*256)/256
+     * </code>
+     * <p>Using the Calibri font as an example, the maximum digit width of 11 point
font size is 7 pixels (at 96 dpi).
+     *  If you set a column width to be eight characters wide, e.g. <code>setColumnWidth(columnIndex,
8*256)</code>,
+     *  then the actual value of visible characters (the value shown in Excel) is derived
from the following equation:
+     *  <code>
+            Truncate([numChars*7+5]/7*256)/256 = 8;
+     *  </code>
+     *
+     *  which gives <code>7.29</code>.
      *
      * @param columnIndex - the column to set (0-based)
      * @param width - the width in units of 1/256th of a character width
-     * @throws IllegalArgumentException if width > 65280 (the maximum column width in
Excel)
+     * @throws IllegalArgumentException if width > 255*256 (the maximum column width in
Excel is 255 characters)
      */
     public void setColumnWidth(int columnIndex, int width) {
         if(width > 255*256) throw new IllegalArgumentException("The maximum column width
for an individual cell is 255 characters.");



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org


Mime
View raw message