Added docs and examples for insert_image().

Closes #28.

dev/release/fix_example_docs.pl

@@ -28,6 +28,7 @@ my @examples = (
     [ 'constant_memory.c',      'Write a large file with constant memory usage' ],
     [ 'merge_range.c',          'Create a merged range of cells' ],
     [ 'autofilter.c',           'An example of a worksheet autofilter' ],
+    [ 'images.c',               'Example of adding images to a worksheet.' ],
     [ 'headers_footers.c',      'Example of adding worksheet headers/footers' ],
     [ 'defined_name.c',         'Example of how to create defined names' ],
     [ 'tab_colors.c',           'Example of how to set worksheet tab colors' ],

docs/src/examples.dox

@@ -126,10 +126,17 @@ Next example: @ref autofilter.c
 @example autofilter.c
 Example of adding an autofilter to a worksheet.
 
-Next example: @ref headers_footers.c
+Next example: @ref images.c
 @image html autofilter.png
 
 
+@example images.c
+Example of adding images to a worksheet.
+
+Next example: @ref headers_footers.c
+@image html images.png
+
+
 @example headers_footers.c
 Example of adding worksheet headers and footers to worksheets.
 

examples/demo.c

@@ -3,10 +3,6 @@
  *
  * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org
  *
- * Logo image is from Wikimedia Commons:
- *
- * http://en.wikipedia.org/wiki/File:The_C_Programming_Language_logo.svg
- *
  */
 
 #include "xlsxwriter.h"
@@ -23,8 +19,9 @@ int main() {
     /* Set the bold property for the format */
     format_set_bold(format);
 
-    /* Widen the first column to make the text clearer. */
+    /* Widen the columns to make the text clearer. */
     worksheet_set_column(worksheet, 0, 0, 20, NULL, NULL);
+    worksheet_set_column(worksheet, 1, 1,  2, NULL, NULL);
 
     /* Write some simple text. */
     worksheet_write_string(worksheet, 0, 0, "Hello", NULL);
@@ -37,7 +34,7 @@ int main() {
     worksheet_write_number(worksheet, 3, 0, 123.456, NULL);
 
     /* Insert an image. */
-    worksheet_insert_image(worksheet, 0, 1, "logo.png");
+    worksheet_insert_image(worksheet, 1, 2, "logo.png");
 
     workbook_close(workbook);
 

examples/images.c

@@ -0,0 +1,40 @@
+/*
+ * An example of inserting images into a worksheet using the libxlsxwriter
+ * library.
+ *
+ * Copyright 2014-2015, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    /* Create a new workbook and add a worksheet. */
+    lxw_workbook  *workbook  = new_workbook("images.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+
+    /* Change some of the column widths for clarity. */
+    worksheet_set_column(worksheet, COLS("A:A"), 30, NULL, NULL);
+
+    /* Insert an image. */
+    worksheet_write_string(worksheet, CELL("A2"), "Insert an image in a cell:", NULL);
+
+    worksheet_insert_image(worksheet, CELL("B2"), "logo.png");
+
+    /* Insert an image offset in the cell. */
+    worksheet_write_string(worksheet, CELL("A12"), "Insert an offset image:", NULL);
+
+    lxw_image_options options1 = {.x_offset = 15, .y_offset = 10};
+    worksheet_insert_image_opt(worksheet, CELL("B12"), "logo.png", &options1);
+
+    /* Insert an image with scaling. */
+    worksheet_write_string(worksheet, CELL("A23"), "Insert a scaled image:", NULL);
+
+    lxw_image_options options2 = {.x_scale  = 0.5, .y_scale  = 0.5};
+    worksheet_insert_image_opt(worksheet, CELL("B23"), "logo.png", &options2);
+
+    workbook_close(workbook);
+
+    return 0;
+}

include/xlsxwriter/worksheet.h

@@ -262,13 +262,28 @@ typedef struct lxw_selection {
 
 } lxw_selection;
 
+/**
+ * @brief Options for inserted images
+ *
+ * Options for modifying images inserted via `worksheet_insert_image_opt()`.
+ *
+ */
 typedef struct lxw_image_options {
+
+    /** Offset from the left of the cell in pixels. */
+    int32_t x_offset;
+
+    /** Offset from the top of the cell in pixels. */
+    int32_t y_offset;
+
+    /** X scale of the image as a decimal. */
+    double x_scale;
+
+    /** Y scale of the image as a decimal. */
+    double y_scale;
+
     lxw_row_t row;
     lxw_col_t col;
-    int32_t x_offset;
-    int32_t y_offset;
-    double x_scale;
-    double y_scale;
     char *filename;
     char *url;
     char *tip;
@@ -1171,13 +1186,73 @@ int8_t worksheet_set_column(lxw_worksheet *worksheet, lxw_col_t first_col,
                             lxw_col_t last_col, double width,
                             lxw_format *format, lxw_row_col_options *options);
 
-/* TODO */
+/**
+ * @brief Insert an image in a worksheet cell.
+ *
+ * @param worksheet Pointer to a lxw_worksheet instance to be updated.
+ * @param row       The zero indexed row number.
+ * @param col       The zero indexed column number.
+ * @param filename  The image filename, with path if required.
+ *
+ * @return 0 for success, non-zero on error.
+ *
+ * This function can be used to insert a image into a worksheet. The image can
+ * be in PNG, JPEG or BMP format:
+ *
+ * @code
+ *     worksheet_insert_image(worksheet, 2, 1, "logo.png");
+ * @endcode
+ *
+ * @image html insert_image.png
+ *
+ * The `worksheet_insert_image_opt()` function takes additional optional
+ * parameters to position and scale the image, see below.
+ *
+ * **Note**:
+ * The scaling of a image may be affected if is crosses a row that has its
+ * default height changed due to a font that is larger than the default font
+ * size or that has text wrapping turned on. To avoid this you should
+ * explicitly set the height of the row using `worksheet_set_row()` if it
+ * crosses an inserted image.
+ *
+ * BMP images are only supported for backward compatibility. In general it is
+ * best to avoid BMP images since they aren't compressed. If used, BMP images
+ * must be 24 bit, true color, bitmaps.
+ */
 int worksheet_insert_image(lxw_worksheet *worksheet,
-                           lxw_row_t row_num, lxw_col_t col_num,
+                           lxw_row_t row, lxw_col_t col,
                            const char *filename);
 
+/**
+ * @brief Insert an image in a worksheet cell, with options.
+ *
+ * @param worksheet Pointer to a lxw_worksheet instance to be updated.
+ * @param row       The zero indexed row number.
+ * @param col       The zero indexed column number.
+ * @param filename  The image filename, with path if required.
+ * @param options   Optional image parameters.
+ *
+ * @return 0 for success, non-zero on error.
+ *
+ * The `%worksheet_insert_image_opt()` function is like
+ * `worksheet_insert_image()` function except that it takes an optional
+ * #lxw_image_options struct to scale and position the image:
+ *
+ * @code
+ *    lxw_image_options options = {.x_offset = 30,   .y_offset = 10,
+ *                                 .x_scale  = 0.5, .y_scale  = 0.5};
+ *
+ *    worksheet_insert_image_opt(worksheet, 2, 1, "logo.png", &options);
+ *
+ * @endcode
+ *
+ * @image html insert_image_opt.png
+ *
+ * **Note**: See the notes about row scaling and BMP images in
+ * `worksheet_insert_image()` above.
+ */
 int worksheet_insert_image_opt(lxw_worksheet *worksheet,
-                               lxw_row_t row_num, lxw_col_t col_num,
+                               lxw_row_t row, lxw_col_t col,
                                const char *filename,
                                lxw_image_options *options);