docs: add autofit documentation

Author: jmcnamara

Changelog.md

@@ -15,6 +15,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Add border, fill, gradient and pattern formatting options for
   chart titles and also chart axis titles.
 
+- Added documentation for the Worksheet `autofit()` method and the Utility
+  `xl_cell_autofit_width()` function.
+
 
 ### Fixed
 

MANIFEST

@@ -2188,7 +2188,7 @@ t/utility/xl_parse_time.t
 t/utility/xl_range.t
 t/utility/xl_range_formula.t
 t/utility/xl_rowcol_to_cell.t
-t/utility/xl_string_pixel_width.t
+t/utility/xl_cell_autofit_width.t
 t/workbook/sub_close.t
 t/workbook/sub_get_chart_range.t
 t/workbook/sub_sort_defined_names.t

lib/Excel/Writer/XLSX.pm

@@ -2389,7 +2389,7 @@ Examples:
 
 The width corresponds to the column width value that is specified in Excel. It is approximately equal to the length of a string in the default font of Calibri 11. To set the width in pixels use the C<set_column_pixels()> method, see below.
 
-Unfortunately, there is no way to specify "AutoFit" for a column in the Excel file format. This feature is only available at runtime from within Excel.
+See also the C<autofit()> method to set the column widths based on the data in the column, approximately.
 
 As usual the C<$format> parameter is optional, for additional information, see L</CELL FORMATTING>. If you wish to set the format without changing the width you can pass C<undef> as the width parameter:
 
@@ -2459,6 +2459,33 @@ The option to hide unused rows is used by Excel as an optimisation so that the u
 See the C<hide_row_col.pl> example program.
 
 
+=head2 autofit($max_width)
+
+Autofit the worksheet column widths to the widest data in the column, approximately.
+
+    $worksheet->autofit();
+
+Excel autofits columns at runtime when it has access to all of the required worksheet information as well as the Windows functions for calculating display areas based on fonts and formatting. Excel::Writer::XLSX doesn't have access to these Windows functions so it simulates autofit by calculating string widths based on metrics taken from Excel. This isn't perfect but for most cases it should be sufficient and indistinguishable from the output of Excel. However there are some limitations to be aware of when using this method:
+
+=over 4
+
+=item * It is based on the default Excel font type and size of Calibri 11. It will not give accurate results for other fonts or font sizes.
+
+=item * It doesn't take formatting of numbers or dates account, although this may be addressed in a later version.
+
+=item * Autofit is a relatively expensive operation since it performs a calculation for all the populated cells in a worksheet. See the note on performance below.
+
+=back
+
+For cases that don't match your desired output you can set explicit column widths via C<set_column()> or C<set_column_pixels()> method ignores columns that have already been explicitly set if the width is greater than the calculated autofit width. Alternatively, setting the column width explicitly after calling C<autofit()> will override the autofit value. You can also set an upper limit using the optional C<$max_width> parameter as explained below.
+
+Excel autofits very long strings up to limit of 1790 pixels/255 characters. This is often too wide to display on a single screen at normal zoom. As such the optional C<$max_width> parameter is provided to enable a smaller upper pixel limit for autofitting long strings. A value of 300 pixels is recommended as a good compromise between column width and readability:
+
+    $worksheet->autofit(300);
+
+If you need more control over the autofit effect you can use the L<Excel::Writer::XLSX::Utility> C<xl_cell_autofit_width()> function to calculate the autofit width for a cell value. This is the same calculation used internally by C<autofit()>.
+
+
 
 
 =head2 outline_settings( $visible, $symbols_below, $symbols_right, $auto_style )

lib/Excel/Writer/XLSX/Utility.pm

@@ -40,7 +40,7 @@ my @rowcol = qw(
   xl_dec_row
   xl_inc_col
   xl_dec_col
-  xl_string_pixel_width
+  xl_cell_autofit_width
 );
 
 # Date and Time functions
@@ -529,14 +529,14 @@ sub xl_date_1904 {
 
 ###############################################################################
 #
-# xl_string_pixel_width($string)
+# xl_cell_autofit_width($string)
 #
 # Get the pixel width of a string based on individual character widths taken
 # from Excel. UTF8 characters are given a default width of 8.
 #
 # Note, Excel adds an additional 7 pixels padding to a cell.
 #
-sub xl_string_pixel_width {
+sub xl_cell_autofit_width {
     my $length = 0;
 
     for my $char (split //, shift) {
@@ -1092,6 +1092,24 @@ This functions takes a cell reference string in A1 notation and decrements the c
     my $str = xl_dec_col( '$C1' );     # $B1
     my $str = xl_dec_col( '$E$5' );    # $D$5
 
+
+=head2 xl_cell_autofit_width($string)
+
+    Parameters: $string, The string to calculate the cell width for.
+
+    Returns:    The string autofit width in pixels. Returns 0 if the string is empty.
+
+This function calculates the width required to auto-fit a string in a cell:
+
+    my $width = xl_cell_autofit_width($string);
+
+The Worksheet C<autofit()> method can be used to auto-fit cell data to the optimal column width. However, in some cases you may wish to handle auto-fitting yourself and apply additional logic to limit the maximum and minimum ranges.
+
+The C<xl_cell_autofit_width()> function can be used to perform the required calculation. It works by estimating the pixel width of a string based on the width of each character. It also adds a 7 pixel padding for the cell boundary in the same way that Excel does.
+
+You can use the calculated width in conjunction with Worksheet C<set_column_pixels()> method.
+
+
 =head1 TIME AND DATE FUNCTIONS
 
 Dates and times in Excel are represented by real numbers, for example "Jan 1 2001 12:30:14 PM" is represented by the number 36892.521.

lib/Excel/Writer/XLSX/Worksheet.pm

@@ -29,7 +29,7 @@ use Excel::Writer::XLSX::Utility qw(xl_cell_to_rowcol
                                     xl_rowcol_to_cell
                                     xl_col_to_name
                                     xl_range
-                                    xl_string_pixel_width
+                                    xl_cell_autofit_width
                                     quote_sheetname
                                     get_image_properties);
 
@@ -832,14 +832,14 @@ sub autofit {
                         }
 
                         if ( $string !~ /\n/ ) {
-                            $length = xl_string_pixel_width( $string );
+                            $length = xl_cell_autofit_width( $string );
                         }
                         else {
                             # Handle multiline strings.
                             my @segments = split "\n", $string;
                             for my $string ( @segments ) {
                                 my $seg_length =
-                                  xl_string_pixel_width( $string );
+                                  xl_cell_autofit_width( $string );
 
                                 if ( $seg_length > $length ) {
                                     $length = $seg_length;
@@ -887,15 +887,15 @@ sub autofit {
                         # non-zero value.
                         my $value = $cell->[3];
                         if ( $value ) {
-                            $length = xl_string_pixel_width( $value );
+                            $length = xl_cell_autofit_width( $value );
                         }
                     }
                     elsif ( $type eq 'a' || $type eq 'd' ) {
 
                         # Handle array and dynamic formulas.
                         my $value = $cell->[4];
                         if ( $value ) {
-                            $length = xl_string_pixel_width( $value );
+                            $length = xl_cell_autofit_width( $value );
                         }
                     }
 

t/utility/xl_string_pixel_width.t

@@ -9,15 +9,15 @@
 
 use strict;
 use warnings;
-use Excel::Writer::XLSX::Utility qw(xl_string_pixel_width);
+use Excel::Writer::XLSX::Utility qw(xl_cell_autofit_width);
 
 use utf8;
 use Test::More tests => 100;
 
 
 ###############################################################################
 #
-# Test the xl_string_pixel_width() function.
+# Test the xl_cell_autofit_width() function.
 #
 my @tests = (
 
@@ -129,7 +129,7 @@ my @tests = (
 for my $test ( @tests ) {
     my $string   = $test->[0];
     my $expected = $test->[1];
-    my $got      = xl_string_pixel_width( $string );
+    my $got      = xl_cell_autofit_width( $string );
     is( $got, $expected, "String = " . $string );
 }