worksheet: add embed_image()

Add support for embedded worksheet images from newer
versions of Excel.

Author: jmcnamara

.gitignore

@@ -12,4 +12,5 @@ TAGS
 *#
 ~*xlsx
 *.bak
+.vscode
 

lib/Excel/Writer/XLSX.pm

@@ -724,6 +724,7 @@ The following methods are available through a new worksheet:
     set_comments_author()
     add_write_handler()
     insert_image()
+    embed_image()
     insert_chart()
     insert_shape()
     insert_button()
@@ -1711,6 +1712,8 @@ This method can be used to insert a image into a worksheet. The image can be in
     $worksheet2->insert_image( 'A1', '../images/perl.bmp' );
     $worksheet3->insert_image( 'A1', '.c:\images\perl.bmp' );
 
+This is the equivalent of Excel's menu option to insert an image using the option to "Place over Cells". See C<embed_image()> below for the equivalent method to "Place in Cell".
+
 The optional C<options> hash/hashref parameter can be used to set various options for the image. The defaults are:
 
     %options = (
@@ -1780,6 +1783,66 @@ BMP images must be 24 bit, true colour, bitmaps. In general it is best to avoid
 
 
 
+=head2 embed_image( $row, $col, $filename, { %options } )
+
+This method can be used to embed an image into a worksheet. The image can be in PNG, JPEG, GIF or BMP format.
+
+    $worksheet1->embed_image( 'A1', 'perl.bmp' );
+    $worksheet2->embed_image( 'A1', '../images/perl.bmp' );
+    $worksheet3->embed_image( 'A1', '.c:\images\perl.bmp' );
+
+This method can be used to embed a image into a worksheet cell and have the
+image automatically scale to the width and height of the cell. The X/Y scaling
+of the image is preserved but the size of the image is adjusted to fit the
+largest possible width or height depending on the cell dimensions.
+
+This is the equivalent of Excel's menu option to insert an image using the
+option to "Place in Cell". See C<insert_image()> for the equivalent method to
+"Place over Cells".
+
+The optional C<options> hash/hashref parameter can be used to set various options for the image. The defaults are:
+
+    %options = (
+        cell_format     => format,
+        url             => undef,
+        tip             => undef,
+        description     => $filename,
+        decorative      => 0,
+    );
+
+The C<cell_format> parameters can be an standard Format to set the formatting of the cell behind the image.
+
+The C<url> option can be use to used to add a hyperlink to an image:
+
+    $worksheet->insert_image( 'A1', 'logo.png',
+        { url => 'https://github.com/jmcnamara' } );
+
+The supported url formats are the same as those supported by the C<write_url()> method and the same rules/limits apply.
+
+The C<tip> option can be use to used to add a mouseover tip to the hyperlink:
+
+    $worksheet->insert_image( 'A1', 'logo.png',
+        {
+            url => 'https://github.com/jmcnamara',
+            tip => 'GitHub'
+        }
+    );
+
+The C<description> parameter can be used to specify a description or "alt text" string for the image. In general this would be used to provide a text description of the image to help accessibility. It is an optional parameter and defaults to the filename of the image. It can be used as follows:
+
+    $worksheet->insert_image( 'E9', 'logo.png',
+                              {description => "This is some alternative text"} );
+
+The optional C<decorative> parameter is also used to help accessibility. It is used to mark the image as decorative, and thus uninformative, for automated screen readers. As in Excel, if this parameter is in use the C<description> field isn't written. It is used as follows:
+
+    $worksheet->insert_image( 'E9', 'logo.png', {decorative => 1} );
+
+Note: you must call C<set_row()> or C<set_column()> before C<insert_image()> 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 C<set_row()> if it contains a font size that will change the row height.
+
+BMP images must be 24 bit, true colour, bitmaps. In general it is best to avoid BMP images since they aren't compressed.
+
+
+
 
 =head2 insert_chart( $row, $col, $chart, { %options } )
 

lib/Excel/Writer/XLSX/Package/ContentTypes.pm

@@ -350,6 +350,38 @@ sub _add_metadata {
 }
 
 
+###############################################################################
+#
+# _add_richvalue()
+#
+# Add the RichValue files to the ContentTypes overrides.
+#
+sub _add_richvalue {
+
+    my $self = shift;
+
+    $self->_add_override(
+        '/xl/richData/rdRichValueTypes.xml',
+        'application/vnd.ms-excel.rdrichvaluetypes+xml'
+    );
+
+    $self->_add_override(
+        '/xl/richData/rdrichvalue.xml',
+        'application/vnd.ms-excel.rdrichvalue+xml'
+    );
+
+    $self->_add_override(
+        '/xl/richData/rdrichvaluestructure.xml',
+        'application/vnd.ms-excel.rdrichvaluestructure+xml'
+    );
+
+    $self->_add_override(
+        '/xl/richData/richValueRel.xml',
+        'application/vnd.ms-excel.richvaluerel+xml'
+    );
+}
+
+
 ###############################################################################
 #
 # Internal methods.