Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

2.20 October 6 2007 - Major

    + Added autofilter() and filter_column() method and
      autofilter.pl example.

    + Added embed_chart() method to allow extracted chart
      templates to be embedded in a worksheet.
      Added demo4.pl and demo5.pl examples.

    + Added the insert_image() method and proper Excel 97
      style image handling for PNG and BMP.
      Images now work with Gnumeric and OpenOffice.
      insert_bitmap() is now deprecated.

    ! Made pane split optional when calling freeze_panes().
      Also renamed thaw_panes() as split_panes(). The old
      method name is still available, but deprecated.

    ! Renamed write_unicode() and write_unicode_le() methods
      to the more explicit write_utf16be_string() and
      write_utf16le_string(). The old method names are
      still available, but deprecated.
  • Loading branch information...
commit a3f19a47d00267a6077e43889c70ce7ef9e40d7b 1 parent fed4a32
@jmcnamara authored
Showing with 4,503 additions and 1,034 deletions.
  1. +31 −0 Changes
  2. +11 −3 MANIFEST
  3. +1 −1  META.yml
  4. +1 −1  Makefile.PL
  5. +69 −11 bin/chartex
  6. BIN  charts/Chart1.xls
  7. BIN  charts/Chart2.xls
  8. BIN  charts/Chart3.xls
  9. BIN  charts/Chart4.xls
  10. BIN  charts/Chart5.xls
  11. +10 −0 charts/README
  12. +68 −10 charts/chartex.pl
  13. +3 −3 charts/demo1.pl
  14. +5 −4 charts/demo2.pl
  15. +6 −6 charts/demo3.pl
  16. +109 −0 charts/demo4.pl
  17. +41 −0 charts/demo5.pl
  18. +561 −234 doc/WriteExcel.html
  19. +6 −5 examples/README
  20. +266 −0 examples/autofilter.pl
  21. +5 −2 examples/bug_report.pl
  22. +2 −2 examples/demo.pl
  23. +8 −7 examples/formats.pl
  24. +3 −3 examples/hide_sheet.pl
  25. +6 −6 examples/images.pl
  26. +6 −7 examples/panes.pl
  27. BIN  examples/republic.bmp
  28. BIN  examples/republic.png
  29. +2 −2 examples/unicode_2022_jp.pl
  30. +2 −2 examples/unicode_8859_11.pl
  31. +2 −2 examples/unicode_8859_7.pl
  32. +2 −2 examples/unicode_big5.pl
  33. +2 −2 examples/unicode_cp1251.pl
  34. +2 −2 examples/unicode_cp1256.pl
  35. +2 −2 examples/unicode_cyrillic.pl
  36. +2 −2 examples/unicode_koi8r.pl
  37. +1 −1  examples/unicode_list.pl
  38. +2 −2 examples/unicode_polish_utf8.pl
  39. +2 −2 examples/unicode_shift_jis.pl
  40. +4 −4 examples/{unicode.pl → unicode_utf16.pl}
  41. +4 −4 examples/{unicode_japan.pl → unicode_utf16_japan.pl}
  42. +338 −151 lib/Spreadsheet/WriteExcel.pm
  43. +13 −7 lib/Spreadsheet/WriteExcel/BIFFwriter.pm
  44. +2 −2 lib/Spreadsheet/WriteExcel/Big.pm
  45. +2 −2 lib/Spreadsheet/WriteExcel/Chart.pm
  46. +4 −2 lib/Spreadsheet/WriteExcel/Format.pm
  47. +2 −2 lib/Spreadsheet/WriteExcel/Formula.pm
  48. +2 −2 lib/Spreadsheet/WriteExcel/OLEwriter.pm
  49. +2 −2 lib/Spreadsheet/WriteExcel/Utility.pm
  50. +580 −31 lib/Spreadsheet/WriteExcel/Workbook.pm
  51. +2 −2 lib/Spreadsheet/WriteExcel/WorkbookBig.pm
  52. +1,581 −433 lib/Spreadsheet/WriteExcel/Worksheet.pm
  53. +42 −47 t/21_escher.t
  54. +17 −17 t/22_mso_drawing_group.t
  55. +348 −0 t/26_autofilter.t
  56. +145 −0 t/27_autofilter.t
  57. +176 −0 t/28_autofilter.t
View
31 Changes
@@ -1,5 +1,36 @@
Revision history for Perl module Spreadsheet::WriteExcel.
+
+2.20 October 6 2007 - Major
+
+
+ + Added autofilter() and filter_column() method and
+ autofilter.pl example.
+
+ + Added embed_chart() method to allow extracted chart
+ templates to be embedded in a worksheet.
+ Added demo4.pl and demo5.pl examples.
+
+ + Added the insert_image() method and proper Excel 97
+ style image handling for PNG and BMP.
+ Images now work with Gnumeric and OpenOffice.
+ insert_bitmap() is now deprecated.
+
+ ! Made pane split optional when calling freeze_panes().
+ Also renamed thaw_panes() as split_panes(). The old
+ method name is still available, but deprected..
+
+ ! Renamed write_unicode() and write_unicode_le() methods
+ to the more explicit write_utf16be_string() and
+ write_utf16le_string(). The old method names are
+ still available, but deprected.
+
+
+2.19 June 14 2007 - Major
+
+ + Beta testing only. Not release to CPAN.
+
+
2.18 January 18 2007 - Minor
! Correct invalid user set_column() calls to prevent
View
14 MANIFEST
@@ -29,6 +29,9 @@ t/21_escher.t
t/22_mso_drawing_group.t
t/23_note.t
t/24_txo.t
+t/26_autofilter.t
+t/27_autofilter.t
+t/28_autofilter.t
doc/index.html
doc/WriteExcel.html
@@ -54,6 +57,7 @@ doc/tpj0503-0004-05.gif
doc/win32ole.gif
examples/README
+examples/autofilter.pl
examples/autofit.pl
examples/bigfile.pl
examples/bug_report.pl
@@ -95,7 +99,7 @@ examples/panes.pl
examples/protection.pl
examples/regions.pl
examples/repeat.pl
-examples/republic.bmp
+examples/republic.png
examples/right_to_left.pl
examples/row_wrap.pl
examples/sales.pl
@@ -107,7 +111,6 @@ examples/stocks.pl
examples/tab2xls.pl
examples/tab_colors.pl
examples/textwrap.pl
-examples/unicode.pl
examples/unicode_2022_jp.pl
examples/unicode_2022_jp.txt
examples/unicode_8859_11.pl
@@ -121,7 +124,6 @@ examples/unicode_cp1251.txt
examples/unicode_cp1256.pl
examples/unicode_cp1256.txt
examples/unicode_cyrillic.pl
-examples/unicode_japan.pl
examples/unicode_koi8r.pl
examples/unicode_koi8r.txt
examples/unicode_list.pl
@@ -129,6 +131,8 @@ examples/unicode_polish_utf8.pl
examples/unicode_polish_utf8.txt
examples/unicode_shift_jis.pl
examples/unicode_shift_jis.txt
+examples/unicode_utf16.pl
+examples/unicode_utf16_japan.pl
examples/win32ole.pl
examples/writeA1.pl
examples/write_arrays.pl
@@ -145,8 +149,12 @@ charts/charts.txt
charts/demo1.pl
charts/demo2.pl
charts/demo3.pl
+charts/demo4.pl
+charts/demo5.pl
charts/Chart1.xls
charts/Chart2.xls
charts/Chart3.xls
+charts/Chart4.xls
+charts/Chart5.xls
bin/chartex
View
2  META.yml
@@ -1,6 +1,6 @@
name: Spreadsheet-WriteExcel
abstract: Write to a cross platform Excel binary file
-version: 2.18
+version: 2.20
version_from: lib/Spreadsheet/WriteExcel.pm
installdirs: site
requires:
View
2  Makefile.PL
@@ -13,7 +13,7 @@ WriteMakefile(
'NEEDS_LINKING' => 0,
'PREREQ_PM' => { Parse::RecDescent => 0,
File::Temp => 0,
- OLE::Storage_Lite => 0.14
+ OLE::Storage_Lite => 0.14,
},
'dist' => { COMPRESS => 'gzip --best', SUFFIX => 'gz' },
'EXE_FILES' => ['bin/chartex'],
View
80 bin/chartex
@@ -5,7 +5,7 @@
# chartex - A utility to extract charts from an Excel file for
# insertion into a Spreadsheet::WriteExcel file.
#
-# reverse('©'), September 2004, John McNamara, jmcnamara@cpan.org
+# reverse('©'), September 2007, John McNamara, jmcnamara@cpan.org
#
# Documentation after __END__
#
@@ -25,7 +25,8 @@ my $chart_index = 1;
my $sheet_index = -1;
my @sheetnames;
my @exrefs;
-
+my $depth_count = 0;
+my $max_font = 0;
#
# Do the Getopt and Pod::Usage routines.
@@ -109,29 +110,76 @@ while (read $tmpfile, $header, 4) {
my $filename = sprintf "%s%02d.bin", $chart_name, $chart_index;
open CHART, ">$filename" or die "Couldn't open $filename: $!";
binmode CHART;
- printf "\nExtracting \"%s\" to %s", $sheetnames[$sheet_index],
- $filename;
+
+ my $sheet_name = $sheetnames[$sheet_index];
+ $sheet_name .= ' embedded' if $depth_count;
+
+ printf "\nExtracting \%s\ to %s", $sheet_name, $filename;
$in_chart = 1;
$chart_index++;
}
- $sheet_index++;
+ $depth_count++;
+ }
+
+
+ # FBI, Chart fonts
+ if ($record == 0x1060) {
+
+ my $index = substr $data, 8, 2, '';
+ $index = unpack 'v', $index;
+
+ # Ignore the inbuilt fonts.
+ if ($index >= 5) {
+ $max_font = $index if $index > $max_font;
+
+ # Shift index past S::WE fonts
+ $index += 2;
+ }
+
+ $data .= pack 'v', $index;
+ }
+
+ # FONTX, Chart fonts
+ if ($record == 0x1026) {
+
+ my $index = unpack 'v', $data;
+
+ # Ignore the inbuilt fonts.
+ if ($index >= 5) {
+ $max_font = $index if $index > $max_font;
+
+ # Shift index past S::WE fonts
+ $index += 2;
+ }
+
+ $data = pack 'v', $index;
}
+
+
if ($in_chart) {
print CHART $header, $data;
}
+
# EOF
if ($record == 0x000A) {
$in_chart = 0;
+ $depth_count--;
+ $sheet_index++ if $depth_count == 0;
+;
}
}
-
-print "\n\n", ('=' x 60), "\n";
-print "Add the following near the start of your program.\n";
-print "Change variable name \$worksheet if required.\n\n";
+if ($chart_index > 1) {
+ print "\n\n";
+ print "Add the following near the start of your program\n";
+ print "and change the variable names if required.\n\n";
+}
+else {
+ print "\nNo charts found in workbook\n";
+}
for my $aref (@exrefs) {
my $sheet1 = $sheetnames[$aref->[1]];
@@ -148,9 +196,19 @@ for my $aref (@exrefs) {
$range = "'$range'" if $range =~ /[^\w:]/;
- print " \$worksheet->store_formula(\"=$range!A1\");\n";
+ print " \$worksheet->store_formula('=$range!A1');\n";
}
+print "\n";
+
+for my $i (5 .. $max_font) {
+
+ printf " my \$chart_font_%d = \$workbook->add_format(font_only => 1);\n",
+ $i -4;
+
+}
+
+
@@ -213,7 +271,7 @@ John McNamara jmcnamara@cpan.org
=head1 VERSION
-Version 0.01.
+Version 0.02.
=head1 COPYRIGHT
View
BIN  charts/Chart1.xls
Binary file not shown
View
BIN  charts/Chart2.xls
Binary file not shown
View
BIN  charts/Chart3.xls
Binary file not shown
View
BIN  charts/Chart4.xls
Binary file not shown
View
BIN  charts/Chart5.xls
Binary file not shown
View
10 charts/README
@@ -12,10 +12,14 @@ The files are as follows:
demo1.pl A demo of a line chart.
demo2.pl A demo of a pie chart.
demo3.pl A demo of a Open-High-Low-Close stock chart.
+ demo4.pl A demo of a Open-High-Low-Close stock chart (embedded).
+ demo5.pl A demo of a line chart (embedded).
Chart1.xls A template for use with demo1.pl.
Chart2.xls A template for use with demo2.pl.
Chart3.xls A template for use with demo3.pl.
+ Chart4.xls A template for use with demo4.pl.
+ Chart5.xls A template for use with demo5.pl.
* If you performed a normal installation then the chartex utility
should be installed to your 'somepath/perl/bin' directory and
@@ -33,6 +37,12 @@ You can run the examples as follows:
perl chartex.pl -c=demo3 Chart3.xls
perl demo3.pl
+ perl chartex.pl -c=demo4 Chart4.xls
+ perl demo4.pl
+
+ perl chartex.pl -c=demo5 Chart5.xls
+ perl demo5.pl
+
See charts.txt for further details of how to include externally generated charts in a Spreadsheet::WriteExcel file.
View
78 charts/chartex.pl
@@ -5,7 +5,7 @@
# chartex - A utility to extract charts from an Excel file for
# insertion into a Spreadsheet::WriteExcel file.
#
-# reverse('©'), September 2004, John McNamara, jmcnamara@cpan.org
+# reverse('©'), September 2007, John McNamara, jmcnamara@cpan.org
#
# Documentation after __END__
#
@@ -25,7 +25,8 @@
my $sheet_index = -1;
my @sheetnames;
my @exrefs;
-
+my $depth_count = 0;
+my $max_font = 0;
#
# Do the Getopt and Pod::Usage routines.
@@ -109,29 +110,76 @@
my $filename = sprintf "%s%02d.bin", $chart_name, $chart_index;
open CHART, ">$filename" or die "Couldn't open $filename: $!";
binmode CHART;
- printf "\nExtracting \"%s\" to %s", $sheetnames[$sheet_index],
- $filename;
+
+ my $sheet_name = $sheetnames[$sheet_index];
+ $sheet_name .= ' embedded' if $depth_count;
+
+ printf "\nExtracting \%s\ to %s", $sheet_name, $filename;
$in_chart = 1;
$chart_index++;
}
- $sheet_index++;
+ $depth_count++;
+ }
+
+
+ # FBI, Chart fonts
+ if ($record == 0x1060) {
+
+ my $index = substr $data, 8, 2, '';
+ $index = unpack 'v', $index;
+
+ # Ignore the inbuilt fonts.
+ if ($index >= 5) {
+ $max_font = $index if $index > $max_font;
+
+ # Shift index past S::WE fonts
+ $index += 2;
+ }
+
+ $data .= pack 'v', $index;
+ }
+
+ # FONTX, Chart fonts
+ if ($record == 0x1026) {
+
+ my $index = unpack 'v', $data;
+
+ # Ignore the inbuilt fonts.
+ if ($index >= 5) {
+ $max_font = $index if $index > $max_font;
+
+ # Shift index past S::WE fonts
+ $index += 2;
+ }
+
+ $data = pack 'v', $index;
}
+
+
if ($in_chart) {
print CHART $header, $data;
}
+
# EOF
if ($record == 0x000A) {
$in_chart = 0;
+ $depth_count--;
+ $sheet_index++ if $depth_count == 0;
+;
}
}
-
-print "\n\n", ('=' x 60), "\n";
-print "Add the following near the start of your program.\n";
-print "Change variable name \$worksheet if required.\n\n";
+if ($chart_index > 1) {
+ print "\n\n";
+ print "Add the following near the start of your program\n";
+ print "and change the variable names if required.\n\n";
+}
+else {
+ print "\nNo charts found in workbook\n";
+}
for my $aref (@exrefs) {
my $sheet1 = $sheetnames[$aref->[1]];
@@ -151,6 +199,16 @@
print " \$worksheet->store_formula('=$range!A1');\n";
}
+print "\n";
+
+for my $i (5 .. $max_font) {
+
+ printf " my \$chart_font_%d = \$workbook->add_format(font_only => 1);\n",
+ $i -4;
+
+}
+
+
@@ -213,7 +271,7 @@ =head1 AUTHOR
=head1 VERSION
-Version 0.01.
+Version 0.02.
=head1 COPYRIGHT
View
6 charts/demo1.pl
@@ -30,9 +30,9 @@
# Add some extra formats to cover formats used in the charts.
-$workbook->add_format(color => 1);
-$workbook->add_format(color => 2);
-$workbook->add_format(color => 3);
+my $chart_font_1 = $workbook->add_format(font_only => 1);
+my $chart_font_2 = $workbook->add_format(font_only => 1);
+my $chart_font_3 = $workbook->add_format(font_only => 1);
# Add all other formats (if any).
View
9 charts/demo2.pl
@@ -30,10 +30,11 @@
# Add some extra formats to cover formats used in the charts.
-$workbook->add_format(color => 1, bold => 1);
-$workbook->add_format(color => 2);
-$workbook->add_format(color => 3);
-
+my $chart_font_1 = $workbook->add_format(font_only => 1);
+my $chart_font_2 = $workbook->add_format(font_only => 1);
+my $chart_font_3 = $workbook->add_format(font_only => 1);
+my $chart_font_4 = $workbook->add_format(font_only => 1);
+my $chart_font_5 = $workbook->add_format(font_only => 1);
# Add all other formats.
my $bold = $workbook->add_format(bold => 1);
View
12 charts/demo3.pl
@@ -30,11 +30,11 @@
# Add some extra formats to cover formats used in the charts.
-$workbook->add_format(color => 1);
-$workbook->add_format(color => 2);
-$workbook->add_format(color => 3, bold => 1);
-$workbook->add_format(color => 4);
-
+my $chart_font_1 = $workbook->add_format(font_only => 1);
+my $chart_font_2 = $workbook->add_format(font_only => 1);
+my $chart_font_3 = $workbook->add_format(font_only => 1);
+my $chart_font_4 = $workbook->add_format(font_only => 1);
+my $chart_font_5 = $workbook->add_format(font_only => 1);
# Add all other formats.
my $bold = $workbook->add_format(bold => 1);
@@ -47,7 +47,7 @@
$worksheet->write('A1', 'Date', $bold);
$worksheet->write('B1', 'Open', $bold);
$worksheet->write('C1', 'High', $bold);
-$worksheet->write('D1', 'Low', $bold);
+$worksheet->write('D1', 'Low', $bold);
$worksheet->write('E1', 'Close', $bold);
View
109 charts/demo4.pl
@@ -0,0 +1,109 @@
+#!/usr/bin/perl -w
+
+###############################################################################
+#
+# Simple example of how to embed an externally created chart into a
+# Spreadsheet:: WriteExcel worksheet.
+#
+#
+# This example adds an "Open-high-low-close" stock chart extracted from the
+# file Chart3.xls as follows:
+#
+# perl chartex.pl -c=demo4 Chart4.xls
+#
+# reverse('©'), September 2007, John McNamara, jmcnamara@cpan.org
+#
+
+use strict;
+use Spreadsheet::WriteExcel;
+
+my $workbook = Spreadsheet::WriteExcel->new("demo4.xls");
+my $worksheet = $workbook->add_worksheet();
+
+
+# Add the chart extracted using the chartex utility
+$worksheet->embed_chart('G2', 'demo401.bin', 3, 3, 1.08, 1.21);
+
+
+# Add some extra formats to cover formats used in the charts.
+my $chart_font_1 = $workbook->add_format(font_only => 1);
+my $chart_font_2 = $workbook->add_format(font_only => 1, bold => 1);
+my $chart_font_3 = $workbook->add_format(font_only => 1);
+my $chart_font_4 = $workbook->add_format(font_only => 1);
+
+# Add all other formats.
+my $bold = $workbook->add_format(bold => 1);
+my $date_format = $workbook->add_format(num_format => 'dd/mm/yyyy');
+
+
+# Adjust column widths and add some headers
+$worksheet->set_column('A:A', 12);
+
+$worksheet->write('A1', 'Date', $bold);
+$worksheet->write('B1', 'Open', $bold);
+$worksheet->write('C1', 'High', $bold);
+$worksheet->write('D1', 'Low', $bold);
+$worksheet->write('E1', 'Close', $bold);
+
+
+# Add data to range that the chart refers to.
+my @dates = (
+
+ "2004-08-19T",
+ "2004-08-20T",
+ "2004-08-23T",
+ "2004-08-24T",
+ "2004-08-25T",
+ "2004-08-26T",
+ "2004-08-27T",
+ "2004-08-30T",
+ "2004-08-31T",
+ "2004-09-01T",
+ "2004-09-02T",
+ "2004-09-03T",
+ "2004-09-07T",
+ "2004-09-08T",
+ "2004-09-09T",
+ "2004-09-10T",
+ "2004-09-13T",
+ "2004-09-14T",
+ "2004-09-15T",
+ "2004-09-16T",
+ "2004-09-17T",
+ "2004-09-20T",
+ "2004-09-21T",
+);
+
+# Open-High-Low-Close prices
+my @prices = (
+
+ [100.00, 104.06, 95.96, 100.34],
+ [101.01, 109.08, 100.50, 108.31],
+ [110.75, 113.48, 109.05, 109.40],
+ [111.24, 111.60, 103.57, 104.87],
+ [104.96, 108.00, 103.88, 106.00],
+ [104.95, 107.95, 104.66, 107.91],
+ [108.10, 108.62, 105.69, 106.15],
+ [105.28, 105.49, 102.01, 102.01],
+ [102.30, 103.71, 102.16, 102.37],
+ [102.70, 102.97, 99.67, 100.25],
+ [ 99.19, 102.37, 98.94, 101.51],
+ [100.95, 101.74, 99.32, 100.01],
+ [101.01, 102.00, 99.61, 101.58],
+ [100.74, 103.03, 100.50, 102.30],
+ [102.53, 102.71, 101.00, 102.31],
+ [101.60, 106.56, 101.30, 105.33],
+ [106.63, 108.41, 106.46, 107.50],
+ [107.45, 112.00, 106.79, 111.49],
+ [110.56, 114.23, 110.20, 112.00],
+ [112.34, 115.80, 111.65, 113.97],
+ [114.42, 117.49, 113.55, 117.49],
+ [116.95, 121.60, 116.77, 119.36],
+ [119.81, 120.42, 117.51, 117.84],
+);
+
+
+
+my $row = 1;
+$worksheet->write_date_time($row++, 0, $_, $date_format) for @dates;
+$worksheet->write_col('B2', \@prices);
View
41 charts/demo5.pl
@@ -0,0 +1,41 @@
+#!/usr/bin/perl -w
+
+###############################################################################
+#
+# Simple example of how to embed an externally created chart into a
+# Spreadsheet:: WriteExcel worksheet.
+#
+#
+# This example adds a line chart extracted from the file Chart1.xls as follows:
+#
+# perl chartex.pl -c=demo5 Chart5.xls
+#
+#
+# reverse('©'), September 2007, John McNamara, jmcnamara@cpan.org
+#
+
+use strict;
+use Spreadsheet::WriteExcel;
+
+my $workbook = Spreadsheet::WriteExcel->new('demo5.xls');
+my $worksheet = $workbook->add_worksheet();
+
+
+# Embed a chart extracted using the chartex utility
+$worksheet->embed_chart('D3', 'demo501.bin');
+
+
+# Add some extra formats to cover formats used in the charts.
+my $chart_font_1 = $workbook->add_format(font_only => 1);
+my $chart_font_2 = $workbook->add_format(font_only => 1);
+
+# Add all other formats (if any).
+
+
+# Add data to range that the chart refers to.
+my @nums = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 );
+my @squares = (0, 1, 4, 9, 16, 25, 36, 49, 64, 81, 100);
+
+$worksheet->write_col('A1', \@nums );
+$worksheet->write_col('B1', \@squares);
+
View
795 doc/WriteExcel.html
@@ -63,8 +63,8 @@
<LI><A HREF="#write_row_column_token_fo">write($row, $column, $token, $format)</A></LI>
<LI><A HREF="#write_number_row_column_num">write_number($row, $column, $number, $format)</A></LI>
<LI><A HREF="#write_string_row_column_str">write_string($row, $column, $string, $format)</A></LI>
- <LI><A HREF="#write_unicode_row_column_st">write_unicode($row, $column, $string, $format)</A></LI>
- <LI><A HREF="#write_unicode_le_row_column_">write_unicode_le($row, $column, $string, $format)</A></LI>
+ <LI><A HREF="#write_utf16be_string_row_colu">write_utf16be_string($row, $column, $string, $format)</A></LI>
+ <LI><A HREF="#write_utf16le_string_row_colu">write_utf16le_string($row, $column, $string, $format)</A></LI>
<LI><A HREF="#keep_leading_zeros_">keep_leading_zeros()</A></LI>
<LI><A HREF="#write_blank_row_column_form">write_blank($row, $column, $format)</A></LI>
<LI><A HREF="#write_row_row_column_array_">write_row($row, $column, $array_ref, $format)</A></LI>
@@ -78,7 +78,8 @@
<LI><A HREF="#write_comment_row_column_st">write_comment($row, $column, $string, ...)</A></LI>
<LI><A HREF="#show_comments_">show_comments()</A></LI>
<LI><A HREF="#add_write_handler_re_code_ref">add_write_handler($re, $code_ref)</A></LI>
- <LI><A HREF="#insert_bitmap_row_col_filen">insert_bitmap($row, $col, $filename, $x, $y, $scale_x, $scale_y)</A></LI>
+ <LI><A HREF="#insert_image_row_col_filena">insert_image($row, $col, $filename, $x, $y, $scale_x, $scale_y)</A></LI>
+ <LI><A HREF="#embed_chart_row_col_filenam">embed_chart($row, $col, $filename, $x, $y, $scale_x, $scale_y)</A></LI>
<LI><A HREF="#get_name_">get_name()</A></LI>
<LI><A HREF="#activate_">activate()</A></LI>
<LI><A HREF="#select_">select()</A></LI>
@@ -90,7 +91,7 @@
<LI><A HREF="#set_column_first_col_last_col">set_column($first_col, $last_col, $width, $format, $hidden, $level)</A></LI>
<LI><A HREF="#outline_settings_visible_symb">outline_settings($visible, $symbols_below, $symbols_right, $auto_style)</A></LI>
<LI><A HREF="#freeze_panes_row_col_top_ro">freeze_panes($row, $col, $top_row, $left_col)</A></LI>
- <LI><A HREF="#thaw_panes_y_x_top_row_le">thaw_panes($y, $x, $top_row, $left_col)</A></LI>
+ <LI><A HREF="#split_panes_y_x_top_row_l">split_panes($y, $x, $top_row, $left_col)</A></LI>
<LI><A HREF="#merge_range_first_row_first_c">merge_range($first_row, $first_col, $last_row, $last_col, $token, $format, $encoding)</A></LI>
<LI><A HREF="#set_zoom_scale_">set_zoom($scale)</A></LI>
<LI><A HREF="#right_to_left_">right_to_left()</A></LI>
@@ -167,8 +168,9 @@
</code>
</UL>
+ <LI><A HREF="#UNICODE_IN_EXCEL">UNICODE IN EXCEL</A></LI>
<LI><A HREF="#COLOURS_IN_EXCEL">COLOURS IN EXCEL</A></LI>
- <LI><A HREF="#DATES_IN_EXCEL">DATES IN EXCEL</A></LI>
+ <LI><A HREF="#DATES_AND_TIME_IN_EXCEL">DATES AND TIME IN EXCEL</A></LI>
<LI><A HREF="#OUTLINES_AND_GROUPING_IN_EXCEL">OUTLINES AND GROUPING IN EXCEL</A></LI>
<LI><A HREF="#FORMULAS_AND_FUNCTIONS_IN_EXCEL">FORMULAS AND FUNCTIONS IN EXCEL</A></LI>
<UL>
@@ -200,14 +202,15 @@
<LI><A HREF="#THE_EXCEL_BINARY_FORMAT">THE EXCEL BINARY FORMAT</A></LI>
<LI><A HREF="#WRITING_EXCEL_FILES">WRITING EXCEL FILES</A></LI>
<LI><A HREF="#READING_EXCEL_FILES">READING EXCEL FILES</A></LI>
- <LI><A HREF="#Warning_about_XML_Parser_and_Pe">Warning about XML::Parser and Perl 5.6</A></LI>
+ <LI><A HREF="#Warning_about_XML_Parser_and_pe">Warning about XML::Parser and perl 5.6</A></LI>
<LI><A HREF="#BUGS">BUGS</A></LI>
<LI><A HREF="#TO_DO">TO DO</A></LI>
<LI><A HREF="#MAILING_LIST">MAILING LIST</A></LI>
- <LI><A HREF="#DONATATIONS">DONATATIONS</A></LI>
+ <LI><A HREF="#DONATIONS">DONATIONS</A></LI>
<LI><A HREF="#SEE_ALSO">SEE ALSO</A></LI>
- <LI><A HREF="#ACKNOWLEDGEMENTS">ACKNOWLEDGEMENTS</A></LI>
+ <LI><A HREF="#ACKNOWLEDGMENTS">ACKNOWLEDGMENTS</A></LI>
<LI><A HREF="#DISCLAIMER_OF_WARRANTY">DISCLAIMER OF WARRANTY</A></LI>
+ <LI><A HREF="#LICENSE">LICENSE</A></LI>
<LI><A HREF="#AUTHOR">AUTHOR</A></LI>
<LI><A HREF="#COPYRIGHT">COPYRIGHT</A></LI>
</UL>
@@ -224,8 +227,8 @@
<HR>
<H1><A NAME="VERSION">VERSION</A></H1>
<P>
-This document refers to version 2.18 of Spreadsheet::WriteExcel, released
-January 18, 2007.
+This document refers to version 2.20 of Spreadsheet::WriteExcel, released
+October 6, 2007.
</P>
<P>
@@ -344,7 +347,7 @@
</P>
<P>
This will create an Excel file called <CODE>perl.xls</CODE> with a single worksheet and the text <CODE>&quot;Hi Excel!&quot;</CODE> in the relevant cell. And that's it. Okay, so there is actually a zeroth
-step as well, but <CODE>use module</CODE> goes without saying. There are also more than 70 examples that come with
+step as well, but <CODE>use module</CODE> goes without saying. There are also more than 80 examples that come with
the distribution and which you can use to get you started. See <A HREF="#EXAMPLES">EXAMPLES</A>.
</P>
@@ -545,9 +548,8 @@
<P>
<STRONG>Note about the requirement for</STRONG> <CODE>binmode()</CODE>: An Excel file is comprised of binary data. Therefore, if you are using a
filehandle you should ensure that you <CODE>binmode()</CODE> it prior to passing it to <CODE>new()</CODE>.You should do this regardless of whether you are on a Windows platform or
-not. This applies especially to users of perl 5.8 on systems where utf8 is
-likely to be in operation such as RedHat Linux 9. If your program, either
-intentionally or not, writes UTF8 data to a filehandle that is passed to <CODE>new()</CODE> it will corrupt the Excel file that is created.
+not. This applies especially to users of perl 5.8 on systems where <CODE>UTF-8</CODE> is likely to be in operation such as RedHat Linux 9. If your program,
+either intentionally or not, writes <CODE>UTF-8</CODE> data to a filehandle that is passed to <CODE>new()</CODE> it will corrupt the Excel file that is created.
</P>
<P>
@@ -719,7 +721,7 @@
</P>
<P>
-On systems with <CODE>perl 5.8</CODE> and later the <CODE>add_worksheet()</CODE> method will also handle strings in Perl's <CODE>utf8</CODE> format.
+On systems with <CODE>perl 5.8</CODE> and later the <CODE>add_worksheet()</CODE> method will also handle strings in &lt;UTF-8&gt; format.
</P>
<P>
@@ -728,8 +730,7 @@
</PRE>
</P>
<P>
-On earlier Perl systems your can specify UTF-16BE worksheet names using an
-additional encoding parameter:
+On earlier Perl systems your can specify <CODE>UTF-16BE</CODE> worksheet names using an additional encoding parameter:
</P>
<P>
@@ -920,7 +921,7 @@
</P>
<P>
-See also <A HREF="#DATES_IN_EXCEL">DATES IN EXCEL</A> for more information about working with Excel's date system.
+See also <A HREF="#DATES_AND_TIME_IN_EXCEL">DATES AND TIME IN EXCEL</A> for more information about working with Excel's date system.
</P>
<P>
@@ -974,8 +975,8 @@
write()
write_number()
write_string()
- write_unicode()
- write_unicode_le()
+ write_utf16be_string()
+ write_utf16le_string()
keep_leading_zeros()
write_blank()
write_row()
@@ -989,7 +990,7 @@
write_comment()
show_comments()
add_write_handler()
- insert_bitmap()
+ insert_image()
get_name()
activate()
select()
@@ -1001,12 +1002,13 @@
set_column()
outline_settings()
freeze_panes()
- thaw_panes()
+ split_panes()
merge_range()
set_zoom()
right_to_left()
hide_zero()
set_tab_color()
+ autofilter()
</PRE>
</P>
<P>
@@ -1223,7 +1225,7 @@
</P>
<P>
-On systems with <CODE>perl 5.8</CODE> and later the <CODE>write()</CODE> method will also handle Unicode strings in Perl's <CODE>utf8</CODE> format.
+On systems with <CODE>perl 5.8</CODE> and later the <CODE>write()</CODE> method will also handle Unicode strings in <CODE>UTF-8</CODE> format.
</P>
<P>
@@ -1283,7 +1285,7 @@
</P>
<P>
-On systems with <CODE>perl 5.8</CODE> and later the <CODE>write()</CODE> method will also handle strings in Perl's <CODE>utf8</CODE> format. With older perls you can also write Unicode in <CODE>UTF16</CODE> format via the <CODE>write_unicode()</CODE> method. See also the <CODE>unicode_*.pl</CODE> programs in the examples directory of the distro.
+On systems with <CODE>perl 5.8</CODE> and later the <CODE>write()</CODE> method will also handle strings in <CODE>UTF-8</CODE> format. With older perls you can also write Unicode in <CODE>UTF16</CODE> format via the <CODE>write_utf16be_string()</CODE> method. See also the <CODE>unicode_*.pl</CODE> programs in the examples directory of the distro.
</P>
<P>
@@ -1315,25 +1317,15 @@
</P>
<P>
<HR>
-<H2><A NAME="write_unicode_row_column_st">write_unicode($row, $column, $string, $format)</A></H2>
+<H2><A NAME="write_utf16be_string_row_colu">write_utf16be_string($row, $column, $string, $format)</A></H2>
<P>
-This method is used to write Unicode strings to a cell in Excel. It is
-functionally the same as the <CODE>write_string()</CODE> method except that the string should be in UTF-16 Unicode format.
+This method is used to write <CODE>UTF-16BE</CODE> strings to a cell in Excel. It is functionally the same as the <CODE>write_string()</CODE> method except that the string should be in <CODE>UTF-16BE</CODE> Unicode format. It is generally easier, when using Spreadsheet::WriteExcel,
+to write unicode strings in <CODE>UTF-8</CODE> format, see <A HREF="#UNICODE_IN_EXCEL">UNICODE IN EXCEL</A>. The <CODE>write_utf16be_string()</CODE> method is mainly of use in versions of perl prior to 5.8.
</P>
<P>
-<STRONG>Note</STRONG>: on systems with <CODE>perl 5.8</CODE> and later the <CODE>write()</CODE> and <CODE>write_string()</CODE>methods will also handle strings in Perl's <CODE>utf8</CODE> format. With older perls you must use the <CODE>write_unicode()</CODE> method.
-
-</P>
-<P>
-The Unicode format required by Excel is UTF-16. Additionally <CODE>Spreadsheet::WriteExcel</CODE> requires that the 16-bit characters are in big-endian order. This is
-generally referred to as UTF-16BE. To write UTF-16 strings in little-endian
-format use the <CODE>write_unicode_le()</CODE> method.
-
-</P>
-<P>
-The following is a simple example showing how to write some Unicode
-strings:
+The following is a simple example showing how to write some Unicode strings
+in <CODE>UTF-16BE</CODE> format:
</P>
<P>
@@ -1350,7 +1342,7 @@
</P>
<P>
<PRE>
- my $workbook = Spreadsheet::WriteExcel-&gt;new('unicode.xls');
+ my $workbook = Spreadsheet::WriteExcel-&gt;new('utf_16_be.xls');
my $worksheet = $workbook-&gt;add_worksheet();
</PRE>
</P>
@@ -1375,20 +1367,20 @@
</P>
<P>
<PRE>
- $worksheet-&gt;write_unicode('A3', $smiley, $big_font);
+ $worksheet-&gt;write_utf16be_string('A3', $smiley, $big_font);
</PRE>
</P>
<P>
<PRE>
# Write a phrase in Cyrillic using a hex-encoded string
#
- my $uni_str = pack &quot;H*&quot;, &quot;042d0442043e0020044404400430043704300020043d&quot; .
- &quot;043000200440044304410441043a043e043c0021&quot;;
+ my $str = pack &quot;H*&quot;, &quot;042d0442043e0020044404400430043704300020043d&quot; .
+ &quot;043000200440044304410441043a043e043c0021&quot;;
</PRE>
</P>
<P>
<PRE>
- $worksheet-&gt;write_unicode('A5', $uni_str);
+ $worksheet-&gt;write_utf16be_string('A5', $str);
</PRE>
</P>
<P>
@@ -1401,64 +1393,11 @@
</P>
<P>
<PRE>
- $worksheet-&gt;write_unicode('A7', $utf16);
-</PRE>
-</P>
-<P>
-The following is an example of creating an Excel file with some Japanese
-text. You will need to have a Unicode font installed, such as <CODE>Arial Unicode MS</CODE>, to view the results:
-
-</P>
-<P>
-<PRE>
- #!/usr/bin/perl -w
-</PRE>
-</P>
-<P>
-<PRE>
- use strict;
- use Spreadsheet::WriteExcel;
-</PRE>
-</P>
-<P>
-<PRE>
- my $workbook = Spreadsheet::WriteExcel-&gt;new('unicode.xls');
- my $worksheet = $workbook-&gt;add_worksheet();
-</PRE>
-</P>
-<P>
-<PRE>
- # It is only required to specify a Unicode font via add_format() if
- # you are using Excel 97. For Excel 2000+ the text will display
- # with the default font (if you have Unicode fonts installed).
- #
- my $uni_font = $workbook-&gt;add_format(font =&gt; 'Arial Unicode MS');
-</PRE>
-</P>
-<P>
-<PRE>
- my $kanji = pack 'n*', 0x65e5, 0x672c;
- my $katakana = pack 'n*', 0xff86, 0xff8e, 0xff9d;
- my $hiragana = pack 'n*', 0x306b, 0x307b, 0x3093;
-</PRE>
-</P>
-<P>
-<PRE>
- $worksheet-&gt;write_unicode('A1', $kanji, $uni_font);
- $worksheet-&gt;write_unicode('A2', $katakana, $uni_font);
- $worksheet-&gt;write_unicode('A3', $hiragana, $uni_font);
-</PRE>
-</P>
-<P>
-<PRE>
- $worksheet-&gt;write('B1', 'Kanji');
- $worksheet-&gt;write('B2', 'Katakana');
- $worksheet-&gt;write('B3', 'Hiragana');
+ $worksheet-&gt;write_utf16be_string('A7', $utf16);
</PRE>
</P>
<P>
-Note: You can convert ascii encodings to the required UTF-16BE format using
-one of the many Unicode modules on CPAN. For example <CODE>Unicode::Map</CODE> and <CODE>Unicode::String</CODE>: <A
+You can convert ASCII encodings to the required <CODE>UTF-16BE</CODE> format using one of the many Unicode modules on CPAN. For example <CODE>Unicode::Map</CODE> and <CODE>Unicode::String</CODE>: <A
HREF="http://search.cpan.org/author/MSCHWARTZ/Unicode-Map/Map.pm">http://search.cpan.org/author/MSCHWARTZ/Unicode-Map/Map.pm</A>
and <A
HREF="http://search.cpan.org/author/GAAS/Unicode-String/String.pm">http://search.cpan.org/author/GAAS/Unicode-String/String.pm</A>
@@ -1472,34 +1411,36 @@
</P>
<P>
+<CODE>UTF-16BE</CODE> is the format most often returned by <CODE>Perl</CODE> modules that generate <CODE>UTF-16</CODE>. To write <CODE>UTF-16</CODE> strings in little-endian format use the <CODE>write_utf16be_string_le()</CODE> method below.
+
+</P>
+<P>
+The <CODE>write_utf16be_string()</CODE> method was previously called <CODE>write_unicode()</CODE>. That, overly general, name is still supported but deprecated.
+
+</P>
+<P>
See also the <CODE>unicode_*.pl</CODE> programs in the examples directory of the distro.
</P>
<P>
<HR>
-<H2><A NAME="write_unicode_le_row_column_">write_unicode_le($row, $column, $string, $format)</A></H2>
+<H2><A NAME="write_utf16le_string_row_colu">write_utf16le_string($row, $column, $string, $format)</A></H2>
<P>
-This method is the same as <CODE>write_unicode()</CODE> except that the string should be 16-bit characters in little-endian format.
-This is generally referred to as UTF-16LE.
+This method is the same as <CODE>write_utf16be()</CODE> except that the string should be 16-bit characters in little-endian format.
+This is generally referred to as <CODE>UTF-16LE</CODE>. See <A HREF="#UNICODE_IN_EXCEL">UNICODE IN EXCEL</A>.
</P>
<P>
-UTF-16 data can be changed from little-endian to big-endian format (and
+<CODE>UTF-16</CODE> data can be changed from little-endian to big-endian format (and
vice-versa) as follows:
</P>
<P>
<PRE>
- $utf16 = pack &quot;n*&quot;, unpack &quot;v*&quot;, $utf16;
+ $utf16be = pack &quot;n*&quot;, unpack &quot;v*&quot;, $utf16le;
</PRE>
</P>
<P>
-Note, it is slightly faster to write little-endian data via
-<CODE>write_unicode_le()</CODE> than it is to write big-endian data via
-<CODE>write_unicode().</CODE>
-
-</P>
-<P>
<HR>
<H2><A NAME="keep_leading_zeros_">keep_leading_zeros()</A></H2>
<P>
@@ -1934,7 +1875,7 @@
</P>
<P>
-A date should always have a <CODE>$format</CODE>, otherwise it will appear as a number, see <A HREF="#DATES_IN_EXCEL">DATES IN EXCEL</A> and <A HREF="#CELL_FORMATTING">CELL FORMATTING</A>. Here is a typical example:
+A date should always have a <CODE>$format</CODE>, otherwise it will appear as a number, see <A HREF="#DATES_AND_TIME_IN_EXCEL">DATES AND TIME IN EXCEL</A> and <A HREF="#CELL_FORMATTING">CELL FORMATTING</A>. Here is a typical example:
</P>
<P>
@@ -2373,11 +2314,6 @@
<HR>
<H2><A NAME="write_comment_row_column_st">write_comment($row, $column, $string, ...)</A></H2>
<P>
-<STRONG>NOTE:</STRONG> This method is currently incompatible with <CODE>insert_bitmap()</CODE>. You can use either method but not both in the same workbook. This will be
-fixed soon.
-
-</P>
-<P>
The <CODE>write_comment()</CODE> method is used to add a comment to a cell. A cell comment is indicated in
Excel by a small red triangle in the upper right-hand corner of the cell.
Moving the cursor over the red triangle will reveal the comment.
@@ -2404,7 +2340,7 @@
</PRE>
</P>
<P>
-On systems with <CODE>perl 5.8</CODE> and later the <CODE>write_comment()</CODE> method will also handle strings in Perl's <CODE>utf8</CODE> format.
+On systems with <CODE>perl 5.8</CODE> and later the <CODE>write_comment()</CODE> method will also handle strings in <CODE>UTF-8</CODE> format.
</P>
<P>
@@ -2451,8 +2387,7 @@
<DL>
<DT><A NAME="item_Option">Option: encoding</A><DD>
<P>
-This option is used to indicate that the comment string is encoded as
-UTF-16BE.
+This option is used to indicate that the comment string is encoded as <CODE>UTF-16BE</CODE>.
</P>
<P>
@@ -2467,7 +2402,7 @@
</P>
<P>
If you wish to use Unicode characters in the comment string then the
-preferred method is to use perl 5.8 and UTF-8 strings.
+preferred method is to use perl 5.8 and <CODE>UTF-8</CODE> strings, see <A HREF="#UNICODE_IN_EXCEL">UNICODE IN EXCEL</A>.
</P>
<DT>Option: author<DD>
@@ -2485,8 +2420,7 @@
</P>
<DT>Option: author_encoding<DD>
<P>
-This option is used to indicate that the author string is encoded as
-UTF-16BE.
+This option is used to indicate that the author string is encoded as <CODE>UTF-16BE</CODE>.
</P>
<DT>Option: visible<DD>
@@ -2703,9 +2637,9 @@
</P>
<P>
-The method is use as follows. say you wished to write 7 digit ID numbers as
-a string so that any leading zeros were preserved*, you could do something
-like the following:
+The method is used as follows. say you wished to write 7 digit ID numbers
+as a string so that any leading zeros were preserved*, you could do
+something like the following:
</P>
<P>
@@ -2812,45 +2746,27 @@
</P>
<P>
<HR>
-<H2><A NAME="insert_bitmap_row_col_filen">insert_bitmap($row, $col, $filename, $x, $y, $scale_x, $scale_y)</A></H2>
-<P>
-<STRONG>NOTE:</STRONG> This method is currently incompatible with <CODE>write_comment()</CODE>. You can use either method but not both in the same workbook. This will be
-fixed soon.
-
-</P>
-<P>
-<STRONG>NOTE:</STRONG> The images inserted using this method do not display in OpenOffice.org or
-Gnumeric. This is related to the previous note and will also be fixed soon.
-
-</P>
+<H2><A NAME="insert_image_row_col_filena">insert_image($row, $col, $filename, $x, $y, $scale_x, $scale_y)</A></H2>
<P>
-This method can be used to insert a bitmap into a worksheet. The bitmap
-must be a 24 bit, true colour, bitmap. No other format is supported. The <CODE>$x</CODE>, <CODE>$y</CODE>, <CODE>$scale_x</CODE> and <CODE>$scale_y</CODE> parameters are optional.
+This method can be used to insert a image into a worksheet. The image can
+be in PNG or BMP format. The <CODE>$x</CODE>, <CODE>$y</CODE>, <CODE>$scale_x</CODE> and <CODE>$scale_y</CODE> parameters are optional.
</P>
<P>
<PRE>
- $worksheet1-&gt;insert_bitmap('A1', 'perl.bmp');
- $worksheet2-&gt;insert_bitmap('A1', '../images/perl.bmp');
- $worksheet3-&gt;insert_bitmap('A1', '.c:\images\perl.bmp');
+ $worksheet1-&gt;insert_image('A1', 'perl.bmp');
+ $worksheet2-&gt;insert_image('A1', '../images/perl.bmp');
+ $worksheet3-&gt;insert_image('A1', '.c:\images\perl.bmp');
</PRE>
</P>
<P>
-Note: you must call <CODE>set_row()</CODE> or <CODE>set_column()</CODE> before <CODE>insert_bitmap()</CODE> if you wish to change the default dimensions of any of the rows or columns
-that the images occupies. The height of a row can also change if you use a
-font that is larger than the default. This in turn will affect the scaling
-of your image. To avoid this you should explicitly set the height of the
-row using <CODE>set_row()</CODE> if it contains a font size that will change the row height.
-
-</P>
-<P>
The parameters <CODE>$x</CODE> and <CODE>$y</CODE> can be used to specify an offset from the top left hand corner of the cell
specified by <CODE>$row</CODE> and <CODE>$col</CODE>. The offset values are in pixels.
</P>
<P>
<PRE>
- $worksheet1-&gt;insert_bitmap('A1', 'perl.bmp', 32, 10);
+ $worksheet1-&gt;insert_image('A1', 'perl.bmp', 32, 10);
</PRE>
</P>
<P>
@@ -2888,29 +2804,85 @@
<P>
<PRE>
# Scale the inserted image: width x 2.0, height x 0.8
- $worksheet-&gt;insert_bitmap('A1', 'perl.bmp', 0, 0, 2, 0.8);
+ $worksheet-&gt;insert_image('A1', 'perl.bmp', 0, 0, 2, 0.8);
+</PRE>
+</P>
+<P>
+See also the <CODE>images.pl</CODE> program in the <CODE>examples</CODE> directory of the distro.
+
+</P>
+<P>
+Note: you must call <CODE>set_row()</CODE> or <CODE>set_column()</CODE> before <CODE>insert_image()</CODE> if you wish to change the default dimensions of any of the rows or columns
+that the image occupies. The height of a row can also change if you use a
+font that is larger than the default. This in turn will affect the scaling
+of your image. To avoid this you should explicitly set the height of the
+row using <CODE>set_row()</CODE> if it contains a font size that will change the row height.
+
+</P>
+<P>
+BMP images must be 24 bit, true colour, bitmaps. In general it is best to
+avoid BMP images since they aren't compressed. The older <CODE>insert_bitmap()</CODE> method is still supported but deprecated.
+
+</P>
+<P>
+<HR>
+<H2><A NAME="embed_chart_row_col_filenam">embed_chart($row, $col, $filename, $x, $y, $scale_x, $scale_y)</A></H2>
+<P>
+This method can be used to insert a chart into a worksheet. The chart must
+first be extracted from an existing Excel file. See the separate <CODE>Charts</CODE> documentation.
+
+</P>
+<P>
+Here is an example:
+
+</P>
+<P>
+<PRE>
+ $worksheet-&gt;embed_chart('B2', 'sales_chart.bin');
</PRE>
</P>
<P>
-Note: although Excel allows you to import several graphics formats such as
-gif, jpeg, png and eps these are converted internally into a proprietary
-format. One of the few non-proprietary formats that Excel supports is 24
-bit, true colour, bitmaps. Therefore if you wish to use images in any other
-format you must first use an external application such as the ImageMagick <EM>convert</EM> utility to convert them to 24 bit bitmaps.
+The <CODE>$x</CODE>, <CODE>$y</CODE>, <CODE>$scale_x</CODE> and <CODE>$scale_y</CODE> parameters are optional.
+
+</P>
+<P>
+The parameters <CODE>$x</CODE> and <CODE>$y</CODE> can be used to specify an offset from the top left hand corner of the cell
+specified by <CODE>$row</CODE> and <CODE>$col</CODE>. The offset values are in pixels. See the <CODE>insert_image</CODE> method above for more information on sizes.
</P>
<P>
<PRE>
- convert test.png test.bmp
+ $worksheet1-&gt;embed_chart('B2', 'sales_chart.bin', 3, 3);
</PRE>
</P>
<P>
-A later release will support the use of file handles and pre-encoded bitmap
-strings.
+The parameters <CODE>$scale_x</CODE> and <CODE>$scale_y</CODE> can be used to scale the inserted image horizontally and vertically:
</P>
<P>
-See also the <CODE>images.pl</CODE> program in the <CODE>examples</CODE> directory of the distro.
+<PRE>
+ # Scale the width by 120% and the height by 150%
+ $worksheet-&gt;embed_chart('B2', 'sales_chart.bin', 0, 0, 1.2, 1.5);
+</PRE>
+</P>
+<P>
+The easiest way to calculate the required scaling is to create a test chart
+worksheet with Spreadsheet::WriteExcel. Then open the file, select the
+chart and drag the corner to get the required size. While holding down the
+mouse the scale of the resized chart is shown to the left of the formula
+bar.
+
+</P>
+<P>
+See also the example programs in the <CODE>charts</CODE> directory of the distro.
+
+</P>
+<P>
+Note: you must call <CODE>set_row()</CODE> or <CODE>set_column()</CODE> before <CODE>embed_chart()</CODE> if you wish to change the default dimensions of any of the rows or columns
+that the chart occupies. The height of a row can also change if you use a
+font that is larger than the default. This in turn will affect the scaling
+of your chart. To avoid this you should explicitly set the height of the
+row using <CODE>set_row()</CODE> if it contains a font size that will change the row height.
</P>
<P>
@@ -2928,6 +2900,11 @@
</PRE>
</P>
<P>
+For reasons related to the design of Spreadsheet::WriteExcel and to the
+internals of Excel there is no <CODE>set_name()</CODE> method. The only way to set the worksheet name is via the <CODE>add_worksheet()</CODE> method.
+
+</P>
+<P>
<HR>
<H2><A NAME="activate_">activate()</A></H2>
<P>
@@ -2949,8 +2926,11 @@
</P>
<P>
This is similar to the Excel VBA activate method. More than one worksheet
-can be selected via the <CODE>select()</CODE> method, however only one worksheet can be active. The default value is the
-first worksheet.
+can be selected via the <CODE>select()</CODE> method, see below, however only one worksheet can be active.
+
+</P>
+<P>
+The default active worksheet is the first worksheet.
</P>
<P>
@@ -2971,7 +2951,7 @@
<P>
A selected worksheet has its tab highlighted. Selecting worksheets is a way
of grouping them together so that, for example, several worksheets could be
-printed in one go. A worksheet that has been activated via the <CODE>activate()</CODE> method will also appear as selected. You probably won't need to use the <CODE>select()</CODE> method very often.
+printed in one go. A worksheet that has been activated via the <CODE>activate()</CODE> method will also appear as selected.
</P>
<P>
@@ -2983,7 +2963,7 @@
</P>
<P>
<PRE>
- $worksheet-&gt;hide();
+ $worksheet2-&gt;hide();
</PRE>
</P>
<P>
@@ -2993,10 +2973,18 @@
</P>
<P>
A hidden worksheet can not be activated or selected so this method is
-mutually exclusive with the <CODE>activate()</CODE> and <CODE>select()</CODE> methods.
+mutually exclusive with the <CODE>activate()</CODE> and <CODE>select()</CODE> methods. In addition, since the first worksheet will default to being the
+active worksheet, you cannot hide the first worksheet without activating
+another sheet:
</P>
<P>
+<PRE>
+ $worksheet2-&gt;activate();
+ $worksheet1-&gt;hide();
+</PRE>
+</P>
+<P>
<HR>
<H2><A NAME="set_first_sheet_">set_first_sheet()</A></H2>
<P>
@@ -3442,7 +3430,7 @@
</P>
<P>
<HR>
-<H2><A NAME="thaw_panes_y_x_top_row_le">thaw_panes($y, $x, $top_row, $left_col)</A></H2>
+<H2><A NAME="split_panes_y_x_top_row_l">split_panes($y, $x, $top_row, $left_col)</A></H2>
<P>
This method can be used to divide a worksheet into horizontal or vertical
regions known as panes. This method is different from the <CODE>freeze_panes()</CODE> method in that the splits between the panes will be visible to the user and
@@ -3469,9 +3457,9 @@
</P>
<P>
<PRE>
- $worksheet-&gt;thaw_panes(12.75, 0, 1, 0); # First row
- $worksheet-&gt;thaw_panes(0, 8.43, 0, 1); # First column
- $worksheet-&gt;thaw_panes(12.75, 8.43, 1, 1); # First row and column
+ $worksheet-&gt;split_panes(12.75, 0, 1, 0); # First row
+ $worksheet-&gt;split_panes(0, 8.43, 0, 1); # First column
+ $worksheet-&gt;split_panes(12.75, 8.43, 1, 1); # First row and column
</PRE>
</P>
<P>
@@ -3483,6 +3471,11 @@
</P>
<P>
+Note: This <CODE>split_panes()</CODE> method was called <CODE>thaw_panes()</CODE> in older versions. The older name is still available for backwards
+compatiblity.
+
+</P>
+<P>
<HR>
<H2><A NAME="merge_range_first_row_first_c">merge_range($first_row, $first_col, $last_row, $last_col, $token, $format, $encoding)</A></H2>
<P>
@@ -3531,7 +3524,7 @@
</P>
<P>
-On systems with <CODE>perl 5.8</CODE> and later the <CODE>merge_range()</CODE> method will also handle strings in Perl's <CODE>utf8</CODE> format.
+On systems with <CODE>perl 5.8</CODE> and later the <CODE>merge_range()</CODE> method will also handle strings in <CODE>UTF-8</CODE> format.
</P>
<P>
@@ -3540,8 +3533,7 @@
</PRE>
</P>
<P>
-On earlier Perl systems your can specify UTF-16BE worksheet names using an
-additional encoding parameter:
+On earlier Perl systems your can specify <CODE>UTF-16BE</CODE> worksheet names using an additional encoding parameter:
</P>
<P>
@@ -3634,6 +3626,180 @@
</P>
<P>
<HR>
+<H2><A NAME="autofilter_first_row_first_co">autofilter($first_row, $first_col, $last_row, $last_col)</A></H2>
+<P>
+This method allows an autofilter to be added to a worksheet. An autofilter
+is a way of adding drop down lists to the headers of a 2D range of
+worksheet data. This is turn allow users to filter the data based on simple
+criteria so that some data is highlighted and some is hidden.
+
+</P>
+<P>
+To add an autofilter to a worksheet:
+
+</P>
+<P>
+<PRE>
+ $worksheet-&gt;autofilter(0, 0, 10, 3);
+ $worksheet-&gt;autofilter('A1:D11'); # Same as above in A1 notation.
+</PRE>
+</P>
+<P>
+Filter conditions can be applied using the <CODE>filter_column()</CODE> method.
+
+</P>
+<P>
+See the <CODE>autofilter.pl</CODE> program in the examples directory of the distro for a more detailed
+example.
+
+</P>
+<P>
+<HR>
+<H2><A NAME="filter_column_column_expressi">filter_column($column, $expression)</A></H2>
+<P>
+The <CODE>filter_column</CODE> method can be used to filter columns in a autofilter range based on simple
+conditions.
+
+</P>
+<P>
+<STRONG>NOTE:</STRONG> It isn't sufficient to just specify the filter condition. You must also
+hide any rows that don't match the filter condition. Rows are hidden using
+the <CODE>set_row()</CODE> <CODE>visible</CODE> parameter. <CODE>Spreadsheet::WriteExcel</CODE> cannot do this automatically since it isn't part of the file format. See
+the <CODE>autofilter.pl</CODE> program in the examples directory of the distro for an example.
+
+</P>
+<P>
+The conditions for the filter are specified using simple expressions:
+
+</P>
+<P>
+<PRE>
+ $worksheet-&gt;filter_column('A', 'x &gt; 2000');
+ $worksheet-&gt;filter_column('B', 'x &gt; 2000 and x &lt; 5000');
+</PRE>
+</P>
+<P>
+The <CODE>$column</CODE> parameter can either be a zero indexed column number or a string column
+name.
+
+</P>
+<P>
+The following operators are available:
+
+</P>
+<P>
+<PRE>
+ Operator Synonyms
+ == = eq =~
+ != &lt;&gt; ne !=
+ &gt;
+ &lt;
+ &gt;=
+ &lt;=
+</PRE>
+</P>
+<P>
+<PRE>
+ and &amp;&amp;
+ or ||
+</PRE>
+</P>
+<P>
+The operator synonyms are just syntactic sugar to make you more comfortable
+using the expressions. It is important to remember that the expressions
+will be interpreted by Excel and not by perl.
+
+</P>
+<P>
+An expression can comprise a single statement or two statements separated
+by the <CODE>and</CODE> and <CODE>or</CODE> operators. For example:
+
+</P>
+<P>
+<PRE>
+ 'x &lt; 2000'
+ 'x &gt; 2000'
+ 'x == 2000'
+ 'x &gt; 2000 and x &lt; 5000'
+ 'x == 2000 or x == 5000'
+</PRE>
+</P>
+<P>
+Filtering of blank or non-blank data can be achieved by using a value of <CODE>Blanks</CODE> or <CODE>NonBlanks</CODE> in the expression:
+
+</P>
+<P>
+<PRE>
+ 'x == Blanks'
+ 'x == NonBlanks'
+</PRE>
+</P>
+<P>
+Top 10 style filters can be specified using a expression like the
+following:
+
+</P>
+<P>
+<PRE>
+ Top|Bottom 1-500 Items|%
+</PRE>
+</P>
+<P>
+For example:
+
+</P>
+<P>
+<PRE>
+ 'Top 10 Items'
+ 'Bottom 5 Items'
+ 'Top 25 %'
+ 'Bottom 50 %'
+</PRE>
+</P>
+<P>
+Excel also allows some simple string matching operations:
+
+</P>
+<P>
+<PRE>
+ 'x =~ b*' # begins with b
+ 'x !~ b*' # doesn't begin with b
+ 'x =~ *b' # ends with b
+ 'x !~ *b' # doesn't end with b
+ 'x =~ *b*' # contains b
+ 'x !~ *b*' # doesn't contains b
+</PRE>
+</P>
+<P>
+You can also use <CODE>*</CODE> to match any character or number and <CODE>?</CODE> to match any single character or number. No other regular expression
+quantifier is supported by Excel's filters. Excel's regular expression
+characters can be escaped using <CODE>~</CODE>.
+
+</P>
+<P>
+The placeholder variable <CODE>x</CODE> in the above examples can be replaced by any simple string. The actual
+placeholder name is ignored internally so the following are all equivalent:
+
+</P>
+<P>
+<PRE>
+ 'x &lt; 2000'
+ 'col &lt; 2000'
+ 'Price &lt; 2000'
+</PRE>
+</P>
+<P>
+Also, note that a filter condition can only be applied to a column in a
+range specified by the <CODE>autofilter()</CODE> Worksheet method.
+
+</P>
+<P>
+See the <CODE>autofilter.pl</CODE> program in the examples directory of the distro for a more detailed
+example.
+
+</P>
+<P>
+<HR>
<H1><A NAME="PAGE_SET_UP_METHODS">PAGE SET-UP METHODS</A></H1>
<P>
Page set-up methods affect the way that a worksheet looks when it is
@@ -4079,7 +4245,7 @@
</P>
<P>
-On systems with <CODE>perl 5.8</CODE> and later the <CODE>set_header()</CODE> method can also handle Unicode strings in Perl's <CODE>utf8</CODE> format.
+On systems with <CODE>perl 5.8</CODE> and later the <CODE>set_header()</CODE> method can also handle Unicode strings in <CODE>UTF-8</CODE> format.
</P>
<P>
@@ -5102,7 +5268,7 @@
</PRE>
</P>
<P>
-The number system used for dates is described in <A HREF="#DATES_IN_EXCEL">DATES IN EXCEL</A>.
+The number system used for dates is described in <A HREF="#DATES_AND_TIME_IN_EXCEL">DATES AND TIME IN EXCEL</A>.
</P>
<P>
@@ -5587,21 +5753,83 @@
<PRE>
Default state: Border is off
Default action: Set border type 1
- Valid args: 0 No border
- 1 Thin single border
- 2 Medium single border
- 3 Dashed border
- 4 Dotted border
- 5 Thick single border
- 6 Double line border
- 7 Hair border
+ Valid args: 0-13, See below.
</PRE>
</P>
<P>
A cell border is comprised of a border on the bottom, top, left and right.
-These can be set to the same value using <CODE>set_border()</CODE> or individually using the relevant method calls shown above. Examples of
-the available border styles are shown in the 'Borders' worksheet created by
-formats.pl.
+These can be set to the same value using <CODE>set_border()</CODE> or individually using the relevant method calls shown above.
+
+</P>
+<P>
+The following shows the border styles sorted by Spreadsheet::WriteExcel
+index number:
+
+</P>
+<P>
+<PRE>
+ Index Name Weight Style
+ ===== ============= ====== ===========
+ 0 None 0
+ 1 Continuous 1 -----------
+ 2 Continuous 2 -----------
+ 3 Dash 1 - - - - - -
+ 4 Dot 1 . . . . . .
+ 5 Continuous 3 -----------
+ 6 Double 3 ===========
+ 7 Continuous 0 -----------
+ 8 Dash 2 - - - - - -
+ 9 Dash Dot 1 - . - . - .
+ 10 Dash Dot 2 - . - . - .
+ 11 Dash Dot Dot 1 - . . - . .
+ 12 Dash Dot Dot 2 - . . - . .
+ 13 SlantDash Dot 2 / - . / - .
+</PRE>
+</P>
+<P>
+The following shows the borders sorted by style:
+
+</P>
+<P>
+<PRE>
+ Name Weight Style Index
+ ============= ====== =========== =====
+ Continuous 0 ----------- 7
+ Continuous 1 ----------- 1
+ Continuous 2 ----------- 2
+ Continuous 3 ----------- 5
+ Dash 1 - - - - - - 3
+ Dash 2 - - - - - - 8
+ Dash Dot 1 - . - . - . 9
+ Dash Dot 2 - . - . - . 10
+ Dash Dot Dot 1 - . . - . . 11
+ Dash Dot Dot 2 - . . - . . 12
+ Dot 1 . . . . . . 4
+ Double 3 =========== 6
+ None 0 0
+ SlantDash Dot 2 / - . / - . 13
+</PRE>
+</P>
+<P>
+The following shows the borders in the order shown in the Excel Dialog.
+
+</P>
+<P>
+<PRE>
+ Index Style Index Style
+ ===== ===== ===== =====
+ 0 None 12 - . . - . .
+ 7 ----------- 13 / - . / - .
+ 4 . . . . . . 10 - . - . - .
+ 11 - . . - . . 8 - - - - - -
+ 9 - . - . - . 2 -----------
+ 3 - - - - - - 5 -----------
+ 1 ----------- 6 ===========
+</PRE>
+</P>
+<P>
+Examples of the available border styles are shown in the 'Borders'
+worksheet created by formats.pl.
</P>
<P>
@@ -5666,6 +5894,105 @@
</P>
<P>
<HR>
+<H1><A NAME="UNICODE_IN_EXCEL">UNICODE IN EXCEL</A></H1>
+<P>
+<EM>For a more general introduction to Unicode handling in Perl see</EM> <EM>perlunitut</EM> and <EM>perluniintro</EM>.
+
+</P>
+<P>
+When using <CODE>Spreadsheet::WriteExcel</CODE> the best and easiest way to write unicode strings to an Excel file is to
+use <CODE>UTF-8</CODE> encoded strings and perl 5.8 (or later). The module also allows you to
+write unicode strings using older perls but it generally requires more
+work, as explained below.
+
+</P>
+<P>
+Internally, Excel encodes unicode data as <CODE>UTF-16LE</CODE> (where LE means little-endian). If you are using perl 5.8+ then
+Spreadsheet::WriteExcel will convert <CODE>UTF-8</CODE> strings to <CODE>UTF-16LE</CODE> when required. No further intervention is required from the programmer, for
+example:
+
+</P>
+<P>
+<PRE>
+ # perl 5.8+ example:
+ my $smiley = &quot;\x{263A}&quot;;
+</PRE>
+</P>
+<P>
+<PRE>
+ $worksheet-&gt;write('A1', 'Hello world');
+ $worksheet-&gt;write('A2', $smiley);
+</PRE>
+</P>
+<P>
+Spreadsheet::WriteExcel also lets you write unicode data as <CODE>UTF-16</CODE>. Since the majority of CPAN modules default to <CODE>UTF-16BE</CODE> (big-endian) Spreadsheet::WriteExcel also uses <CODE>UTF-16BE</CODE> and converts it internally to <CODE>UTF-16LE</CODE>:
+
+</P>
+<P>
+<PRE>
+ # perl 5.005 example:
+ my $smiley = pack &quot;n&quot;, 0x263A;
+</PRE>
+</P>
+<P>
+<PRE>
+ $worksheet-&gt;write ('A3', 'Hello world');
+ $worksheet-&gt;write_utf16be_string('A4', $smiley);
+</PRE>
+</P>
+<P>
+Although the above examples look similar there is an important difference.
+With <CODE>uft8</CODE> and perl 5.8+ Spreadsheet::WriteExcel treats <CODE>UTF-8</CODE> strings in exactly the same way as any other string. However, with <CODE>UTF16</CODE> data we need to distinguish it from other strings either by calling a
+separate function or by passing an additional flag to indicate the data
+type.
+
+</P>
+<P>
+If you are dealing with non-ASCII character sets then your data probably
+won't be in <CODE>UTF-8</CODE> to begin with. However, perl 5.8+ provides useful tools in the guise of the <CODE>Encode</CODE> module to help you to convert to the required <CODE>UTF-8</CODE> format. For example:
+
+</P>
+<P>
+<PRE>
+ use Encode 'decode';
+</PRE>
+</P>
+<P>
+<PRE>
+ my $string = 'some string with koi8-r characters';
+ $string = decode('koi8-r', $string); # koi8-r to utf8
+</PRE>
+</P>
+<P>
+Alternatively you can read data from an encoded file and convert it to <CODE>UTF-8</CODE> as you read it in:
+
+</P>
+<P>
+<PRE>
+ my $file = 'unicode_koi8r.txt';
+ open FH, '&lt;:encoding(koi8-r)', $file or die &quot;Couldn't open $file: $!\n&quot;;
+</PRE>
+</P>
+<P>
+<PRE>
+ my $row = 0;
+ while (&lt;FH&gt;) {
+ # Data read in is now in utf8 format.
+ chomp;
+ $worksheet-&gt;write($row++, 0, $_);
+ }
+</PRE>
+</P>
+<P>
+These methodologies are explained in more detail in <EM>perlunitut</EM>, <EM>perluniintro</EM> and <EM>perlunicode</EM>.
+
+</P>
+<P>
+See also the <CODE>unicode_*.pl</CODE> programs in the examples directory of the distro.
+
+</P>
+<P>
+<HR>
<H1><A NAME="COLOURS_IN_EXCEL">COLOURS IN EXCEL</A></H1>
<P>
Excel provides a colour palette of 56 colours. In Spreadsheet::WriteExcel
@@ -5782,7 +6109,7 @@
</P>
<P>
<HR>
-<H1><A NAME="DATES_IN_EXCEL">DATES IN EXCEL</A></H1>
+<H1><A NAME="DATES_AND_TIME_IN_EXCEL">DATES AND TIME IN EXCEL</A></H1>
<P>
Dates and times in Excel are represented by real numbers, for example "Jan
1 2001 12:30 AM&quot; is represented by the number 36892.521.
@@ -6743,7 +7070,8 @@
<PRE>
Advanced
========
- autofit.pl Simuluate Excel's autofit for colums widths.
+ autofilter.pl Examples of worksheet autofilters.
+ autofit.pl Simulate Excel's autofit for column widths.
bigfile.pl Write past the 7MB limit with OLE::Storage_Lite.
cgi.pl A simple CGI program.
chess.pl An example of formatting using properties.
@@ -6794,9 +7122,9 @@
<PRE>
Unicode
=======
- unicode.pl Simple example of using Unicode UTF16 strings.
- unicode_japan.pl Write Japanese Unicode strings using UTF16.
- unicode_cyrillic.pl Write Russian cyrillic strings using UTF8.
+ unicode_utf16.pl Simple example of using Unicode UTF16 strings.
+ unicode_utf16_japan.pl Write Japanese Unicode strings using UTF-16.
+ unicode_cyrillic.pl Write Russian cyrillic strings using UTF-8.
unicode_list.pl List the chars in a Unicode font.
unicode_2022_jp.pl Japanese: ISO-2022-JP to utf8 in perl 5.8.
unicode_8859_11.pl Thai: ISO-8859_11 to utf8 in perl 5.8.
@@ -6994,8 +7322,7 @@
<P>
This error generally means that the Excel file has been corrupted. There
are two likely causes of this: the file was FTPed in ASCII mode instead of
-binary mode or else the file was created with UTF8 data returned by an XML
-parser. See <A HREF="#Warning_about_XML_Parser_and_Pe">Warning about XML::Parser and Perl 5.6</A> for further details.
+binary mode or else the file was created with <CODE>UTF-8</CODE> data returned by an XML parser. See <A HREF="#Warning_about_XML_Parser_and_pe">Warning about XML::Parser and perl 5.6</A> for further details.
</P>
</DL>
@@ -7150,8 +7477,8 @@
<LI><A NAME="item_Spreadsheet">Spreadsheet::WriteExcel::FromXML</A>
<P>
This module allows you to turn a simple XML file into an Excel file using
-Spreadsheet::WriteExcel as a backend. The format of the XML file is defined
-by a supplied DTD: <A
+Spreadsheet::WriteExcel as a back-end. The format of the XML file is
+defined by a supplied DTD: <A
HREF="http://search.cpan.org/dist/Spreadsheet-WriteExcel-FromXML">http://search.cpan.org/dist/Spreadsheet-WriteExcel-FromXML</A>
@@ -7286,25 +7613,24 @@
</P>
<P>
<HR>
-<H1><A NAME="Warning_about_XML_Parser_and_Pe">Warning about XML::Parser and Perl 5.6</A></H1>
+<H1><A NAME="Warning_about_XML_Parser_and_pe">Warning about XML::Parser and perl 5.6</A></H1>
<P>
You must be careful when using Spreadsheet::WriteExcel in conjunction with
-Perl 5.6 and XML::Parser (and other XML parsers) due to the fact that the
-data returned by the parser is generally in UTF8 format.
+perl 5.6 and XML::Parser (and other XML parsers) due to the fact that the
+data returned by the parser is generally in <CODE>UTF-8</CODE> format.
</P>
<P>
-When UTF8 strings are added to Spreadsheet::WriteExcel's internal data it
-causes the generated Excel file to become corrupt.
+When <CODE>UTF-8</CODE> strings are added to Spreadsheet::WriteExcel's internal data it causes the
+generated Excel file to become corrupt.
</P>
<P>
-Note, this doesn't affect Perl 5.005 (which doesn't try to handle UTF8) or
-5.8 (which handles it correctly).
+Note, this doesn't affect perl 5.005 (which doesn't try to handle <CODE>UTF-8</CODE>) or 5.8 (which handles it correctly).
</P>
<P>
-To avoid this problem you should upgrade to Perl 5.8, if possible, or else
+To avoid this problem you should upgrade to perl 5.8, if possible, or else
you should convert the output data from XML::Parser to ASCII or ISO-8859-1
using one of the following methods:
@@ -7328,8 +7654,8 @@
</P>
<P>
-XML and UTF8 data on Perl 5.6 can cause Excel files created by
-Spreadsheet::WriteExcel to become corrupt. See <A HREF="#Warning_about_XML_Parser_and_Pe">Warning about XML::Parser and Perl 5.6</A> for further details.
+XML and <CODE>UTF-8</CODE> data on perl 5.6 can cause Excel files created by Spreadsheet::WriteExcel
+to become corrupt. See <A HREF="#Warning_about_XML_Parser_and_pe">Warning about XML::Parser and perl 5.6</A> for further details.
</P>
<P>
@@ -7352,20 +7678,11 @@
</P>
<P>
-OpenOffice.org: Images are not displayed. Some formatting is not displayed
-correctly.
-
-</P>
-<P>
-Gnumeric: Images are not displayed. Some formatting is not displayed
-correctly. URLs are not displayed as links. Page setup may cause Gnumeric
-to crash.
+OpenOffice.org: No known issues in this release.
</P>
<P>
-The lack of a portable way of writing a little-endian 64 bit IEEE float.
-There is beta code available to fix this. Let me know if you wish to test
-it on your platform.
+Gnumeric: No known issues in this release.
</P>
<P>
@@ -7380,8 +7697,7 @@
</P>
<UL>
-<LI><A NAME="item_Fix">Fix insert_bitmap to work with write_comment(), OpenOffice.org and Gnumeric.</A>
-<LI><A NAME="item_Add">Add AutoFilters.</A>
+<LI><A NAME="item_Add">Add JPEG support to insert_image().</A>
</UL>
<P>
Also, here are some of the most requested features that probably won't get
@@ -7450,7 +7766,7 @@
</P>
<P>
<HR>
-<H1><A NAME="DONATATIONS">DONATATIONS</A></H1>
+<H1><A NAME="DONATIONS">DONATIONS</A></H1>
<P>
If you'd care to donate to the Spreadsheet::WriteExcel project, you can do
so via PayPal:
@@ -7503,7 +7819,7 @@
</P>
<P>
-"Reading and writing Excel files with Perl" by Teodor Zlatanov, atIBM
+"Reading and writing Excel files with Perl" by Teodor Zlatanov, at IBM
developerWorks: <A
HREF="http://www-106.ibm.com/developerworks/library/l-pexcel/">http://www-106.ibm.com/developerworks/library/l-pexcel/</A>
@@ -7530,7 +7846,7 @@
</P>
<P>
<HR>
-<H1><A NAME="ACKNOWLEDGEMENTS">ACKNOWLEDGEMENTS</A></H1>
+<H1><A NAME="ACKNOWLEDGMENTS">ACKNOWLEDGMENTS</A></H1>
<P>
The following people contributed to the debugging and testing of
Spreadsheet::WriteExcel:
@@ -7568,6 +7884,11 @@
</P>
<P>
+Many thanks to Cassens Transport who sponsored the development of the
+embedded charts and autofilters.
+
+</P>
+<P>
Additional thanks to Takanori Kawai for translating the documentation into
Japanese.
@@ -7617,31 +7938,37 @@
</P>
<P>
<HR>
-<H1><A NAME="AUTHOR">AUTHOR</A></H1>
+<H1><A NAME="LICENSE">LICENSE</A></H1>
<P>
-John McNamara <A HREF="mailto:jmcnamara@cpan.org">jmcnamara@cpan.org</A>
+Either the Perl Artistic Licence <A
+HREF="http://dev.perl.org/licenses/artistic.html">http://dev.perl.org/licenses/artistic.html</A>
+or the GPL <A
+HREF="http://www.opensource.org/licenses/gpl-license.php">http://www.opensource.org/licenses/gpl-license.php</A>
+
</P>
<P>
-<PRE>
- I was nineteen when I came to town, they called it the Summer of Love
- They were burning babies, burning flags. The hawks against the doves
- I took a job in the steamie down on Cauldrum Street
- And I fell in love with a laundry girl who was working next to me
-</PRE>
+<HR>
+<H1><A NAME="AUTHOR">AUTHOR</A></H1>
+<P>
+John McNamara <A HREF="mailto:jmcnamara@cpan.org">jmcnamara@cpan.org</A>
+
</P>
<P>
<PRE>
- Oh she was a rare thing, fine as a bee's wing
- So fine a breath of wind might blow her away
- She was a lost child, oh she was running wild
- She said &quot;As long as there's no price on love, I'll stay.
- And you wouldn't want me any other way&quot;
+ This, no song of an ingenue,
+ This, no ballad of innocence;
+ This, the rhyme of a lady who
+ Followed ever her natural bents.
+ This, a solo of sapience,
+ This, a chantey of sophistry,
+ This, the sum of experiments,
+ I loved them until they loved me.
</PRE>
</P>
<P>
<PRE>
- -- Richard Thompson
+ -- Dorothy Parker
</PRE>
</P>
<P>
View
11 examples/README
@@ -14,7 +14,8 @@ stats.pl Basic formulas and functions.
Advanced
========
-autofit.pl Simuluate Excel's autofit for colums widths.
+autofilter.pl Examples of worksheet autofilters.
+autofit.pl Simulate Excel's autofit for column widths.
bigfile.pl Write past the 7MB limit with OLE::Storage_Lite.
cgi.pl A simple CGI program.
chess.pl An example of formatting using properties.
@@ -63,9 +64,9 @@ write_to_scalar.pl Example of writing an Excel file to a Perl scalar.
Unicode
=======
-unicode.pl Simple example of using Unicode UTF16 strings.
-unicode_japan.pl Write Japanese Unicode strings using UTF16.
-unicode_cyrillic.pl Write Russian cyrillic strings using UTF8.
+unicode_utf16.pl Simple example of using Unicode UTF16 strings.
+unicode_utf16_japan.pl Write Japanese Unicode strings using UTF-16.
+unicode_cyrillic.pl Write Russian cyrillic strings using UTF-8.
unicode_list.pl List the chars in a Unicode font.
unicode_2022_jp.pl Japanese: ISO-2022-JP to utf8 in perl 5.8.
unicode_8859_11.pl Thai: ISO-8859_11 to utf8 in perl 5.8.
@@ -91,4 +92,4 @@ Developer
=========
convertA1.pl Helper functions for dealing with A1 notation.
function_locale.pl Add non-English function names to Formula.pm.
-writeA1.pl Example of how to extend the module.
+writeA1.pl Example of how to extend the module.
View
266 examples/autofilter.pl
@@ -0,0 +1,266 @@
+#!/usr/bin/perl -w
+
+#######################################################################
+#
+# Example of how to create autofilters with Spreadsheet::WriteExcel.
+#
+# reverse('©'), September 2007, John McNamara, jmcnamara@cpan.org
+#
+
+use strict;
+use Spreadsheet::WriteExcel;
+
+my $workbook = Spreadsheet::WriteExcel->new('autofilter.xls');
+
+die "Couldn't create new Excel file: $!.\n" unless defined $workbook;
+
+my $worksheet1 = $workbook->add_worksheet();
+my $worksheet2 = $workbook->add_worksheet();
+my $worksheet3 = $workbook->add_worksheet();
+my $worksheet4 = $workbook->add_worksheet();
+my $worksheet5 = $workbook->add_worksheet();
+my $worksheet6 = $workbook->add_worksheet();
+
+my $bold = $workbook->add_format(bold => 1);
+
+
+# Extract the data embedded at the end of this file.
+my @headings = split ' ', <DATA>;
+my @data;
+push @data, [split] while <DATA>;
+
+
+# Set up several sheets with the same data.
+for my $worksheet ($workbook->sheets()) {
+ $worksheet->set_column('A:D', 12);
+ $worksheet->set_row(0, 20, $bold);
+ $worksheet->write('A1', \@headings);
+}
+
+
+###############################################################################
+#
+# Example 1. Autofilter without conditions.
+#
+
+$worksheet1->autofilter('A1:D51');
+$worksheet1->write('A2', [[@data]]);
+
+
+###############################################################################
+#
+#
+# Example 2. Autofilter with a filter condition in the first column.
+#
+
+# The range in this example is the same as above but in row-column notation.
+$worksheet2->autofilter(0, 0, 50, 3);
+
+# The placeholder "Region" in the filter is ignored and can be any string
+# that adds clarity to the expression.
+#
+$worksheet2->filter_column(0, 'Region eq East');
+
+#
+# Hide the rows that don't match the filter criteria.
+#
+my $row = 1;
+
+for my $row_data (@data) {
+ my $region = $row_data->[0];
+
+ if ($region eq 'East') {
+ # Row is visible.
+ }
+ else {
+ # Hide row.
+ $worksheet2->set_row($row, undef, undef, 1);
+ }
+
+ $worksheet2->write($row++, 0, $row_data);
+}
+
+
+###############################################################################
+#
+#
+# Example 3. Autofilter with a dual filter condition in one of the columns.
+#
+
+$worksheet3->autofilter('A1:D51');
+
+$worksheet3->filter_column('A', 'x eq East or x eq South');
+
+#
+# Hide the rows that don't match the filter criteria.
+#