Added docs for chart data table.

dev/release/fix_example_docs.pl

@@ -47,6 +47,7 @@ my @examples = (
     [ 'chart_radar.c',          'Examples of radar charts' ],
     [ 'chart_pie.c',            'Examples of pie charts' ],
     [ 'chart_doughnut.c',       'Examples of doughnut charts' ],
+    [ 'chart_data_table.c',     'Examples of charts with data tables' ],
     [ 'chart_data_tools.c',     'Examples of charts data tools' ],
     [ 'chart_fonts.c',          'Examples of using charts fonts' ],
     [ 'chart_pattern.c',        'Examples of using charts patterns' ],

docs/src/examples.dox

@@ -636,7 +636,7 @@ A pie chart with rotated segments:
 <table  width="600">
 <tr>
   <td>@ref chart_pie.c "&lt;&lt; chart_pie.c"</td>
-  <td align="right">@ref chart_data_tools.c "chart_data_tools.c &gt;&gt;"</td>
+  <td align="right">@ref chart_data_table.c "chart_data_table.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -657,11 +657,33 @@ Chart 4 shows how to set segment colors and other options.
 
 
 
-@example chart_data_tools.c
+@example chart_data_table.c
 
 <table  width="600">
 <tr>
   <td>@ref chart_doughnut.c "&lt;&lt; chart_doughnut.c"</td>
+  <td align="right">@ref chart_data_tools.c "chart_data_tools.c &gt;&gt;"</td>
+</tr>
+</table>
+
+Example of creating charts with data tables.
+
+Chart 1 in the following example is a column chart with default data table:
+@image html chart_data_table1.png
+
+
+Chart 2 is a column chart with default data table with legend keys:
+@image html chart_data_table2.png
+
+
+
+
+
+@example chart_data_tools.c
+
+<table  width="600">
+<tr>
+  <td>@ref chart_data_table.c "&lt;&lt; chart_data_table.c"</td>
   <td align="right">@ref chart_fonts.c "chart_fonts.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -330,6 +330,19 @@ Chart 4 shows how to set segment colors and other options.
 @image html chart_doughnut2.png
 
 
+##############################################################
+@example chart_data_table.c
+
+Example of creating charts with data tables.
+
+Chart 1 in the following example is a column chart with default data table:
+@image html chart_data_table1.png
+
+
+Chart 2 is a column chart with default data table with legend keys:
+@image html chart_data_table2.png
+
+
 ##############################################################
 @example chart_data_tools.c
 

examples/chart_data_table.c

@@ -0,0 +1,120 @@
+/*
+ * An example of creating Excel column charts with data tables using the
+ * libxlsxwriter library.
+ *
+ * Copyright 2014-2017, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+/*
+ * Write some data to the worksheet.
+ */
+void write_worksheet_data(lxw_worksheet *worksheet, lxw_format *bold) {
+
+    int row, col;
+    uint8_t data[6][3] = {
+        /* Three columns of data. */
+        {2, 10, 30},
+        {3, 40, 60},
+        {4, 50, 70},
+        {5, 20, 50},
+        {6, 10, 40},
+        {7, 50, 30}
+    };
+
+    worksheet_write_string(worksheet, CELL("A1"), "Number",  bold);
+    worksheet_write_string(worksheet, CELL("B1"), "Batch 1", bold);
+    worksheet_write_string(worksheet, CELL("C1"), "Batch 2", bold);
+
+    for (row = 0; row < 6; row++)
+        for (col = 0; col < 3; col++)
+            worksheet_write_number(worksheet, row + 1, col, data[row][col] , NULL);
+}
+
+/*
+ * Create a worksheet with examples charts.
+ */
+int main() {
+
+    lxw_workbook     *workbook  = new_workbook("chart_data_table.xlsx");
+    lxw_worksheet    *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart_series *series;
+
+    /* Add a bold format to use to highlight the header cells. */
+    lxw_format *bold = workbook_add_format(workbook);
+    format_set_bold(bold);
+
+    /* Write some data for the chart. */
+    write_worksheet_data(worksheet, bold);
+
+
+    /*
+     * Chart 1. Create a column chart with a data table.
+     */
+    lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_COLUMN);
+
+    /* Add the first series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7");
+
+    /* Set the name for the series instead of the default "Series 1". */
+    chart_series_set_name(series, "=Sheet1!$B1$1");
+
+    /* Add a second series but leave the categories and values undefined. They
+     * can be defined later using the alternative syntax shown below.  */
+    series = chart_add_series(chart, NULL, NULL);
+
+    /* Configure the series using a syntax that is easier to define programmatically. */
+    chart_series_set_categories(series, "Sheet1", 1, 0, 6, 0); /* "=Sheet1!$A$2:$A$7" */
+    chart_series_set_values(series,     "Sheet1", 1, 2, 6, 2); /* "=Sheet1!$C$2:$C$7" */
+    chart_series_set_name_range(series, "Sheet1", 0, 2);       /* "=Sheet1!$C$1"      */
+
+    /* Add a chart title and some axis labels. */
+    chart_title_set_name(chart,        "Chart with Data Table");
+    chart_axis_set_name(chart->x_axis, "Test number");
+    chart_axis_set_name(chart->y_axis, "Sample length (mm)");
+
+    /* Set a default data table on the X-axis. */
+    chart_set_table(chart);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("E2"), chart);
+
+
+    /*
+     * Chart 2. Create a column chart with a data table and legend keys.
+     */
+    chart = workbook_add_chart(workbook, LXW_CHART_COLUMN);
+
+    /* Add the first series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7");
+
+    /* Set the name for the series instead of the default "Series 1". */
+    chart_series_set_name(series, "=Sheet1!$B1$1");
+
+    /* Add the second series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7");
+
+    /* Set the name for the series instead of the default "Series 2". */
+    chart_series_set_name(series, "=Sheet1!$C1$1");
+
+    /* Add a chart title and some axis labels. */
+    chart_title_set_name(chart,        "Data Table with legend keys");
+    chart_axis_set_name(chart->x_axis, "Test number");
+    chart_axis_set_name(chart->y_axis, "Sample length (mm)");
+
+    /* Set a data table on the X-axis with the legend keys shown. */
+    chart_set_table(chart);
+    chart_set_table_grid(chart, LXW_TRUE, LXW_TRUE, LXW_TRUE, LXW_TRUE);
+
+    /* Turn off the legend. */
+    chart_legend_set_position(chart, LXW_CHART_LEGEND_NONE);
+
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("E18"), chart);
+
+
+    return workbook_close(workbook);
+}

include/xlsxwriter/chart.h

@@ -2371,8 +2371,68 @@ void chart_plotarea_set_pattern(lxw_chart *chart, lxw_chart_pattern *pattern);
  */
 void chart_set_style(lxw_chart *chart, uint8_t style_id);
 
+/**
+ * @brief Turn on a data table below the horizontal axis.
+ *
+ * @param chart Pointer to a lxw_chart instance to be configured.
+ *
+ * The `%chart_set_table()` function adds a data table below the horizontal
+ * axis with the data used to plot the chart:
+ *
+ * @code
+ *     // Turn on the data table with default options.
+ *     chart_set_table(chart);
+ * @endcode
+ *
+ * @image html chart_data_table1.png
+ *
+ * The data table can only be shown with Bar, Column, Line and Area charts.
+ *
+ */
 void chart_set_table(lxw_chart *chart);
 
+/**
+ * @brief Turn on/off grid options for a chart data table.
+ *
+ * @param chart       Pointer to a lxw_chart instance to be configured.
+ * @param horizontal  Turn on/off the horizontal grid lines in the table.
+ * @param vertical    Turn on/off the vertical grid lines in the table.
+ * @param outline     Turn on/off the outline lines in the table.
+ * @param legend_keys Turn on/off the legend keys in the table.
+ *
+ * The `%chart_set_table_grid()` function turns on/off grid options for a
+ * chart data table. The data table grid options in Excel are shown in the
+ * dialog below:
+ *
+ * @image html chart_data_table3.png
+ *
+ * These options can be passed to the `%chart_set_table_grid()` function.
+ * The values for a default chart are:
+ *
+ * - `horizontal`: On.
+ * - `vertical`: On.
+ * - `outline`:  On.
+ * - `legend_keys`: Off.
+ *
+ * Example:
+ *
+ * @code
+ *     // Turn on the data table with default options.
+ *     chart_set_table(chart);
+ *
+ *     // Turn on all grid lines and the grid legend.
+ *     chart_set_table_grid(chart, LXW_TRUE, LXW_TRUE, LXW_TRUE, LXW_TRUE);
+ *
+ *     // Turn off the legend since it is show in the table.
+ *     chart_legend_set_position(chart, LXW_CHART_LEGEND_NONE);
+ *
+ * @endcode
+ *
+ * @image html chart_data_table2.png
+ *
+ * The data table can only be shown with Bar, Column, Line and Area charts.
+ *
+ */
 void chart_set_table_grid(lxw_chart *chart, uint8_t horizontal,
                           uint8_t vertical, uint8_t outline,
                           uint8_t legend_keys);