Added docs for high-low and drop lines.

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_tools.c',     'Examples of charts data tools' ],
     [ 'chart_fonts.c',          'Examples of using charts fonts' ],
     [ 'chart_pattern.c',        'Examples of using charts patterns' ],
     [ 'chart_styles.c',         'Examples of built-in charts styles' ],

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_fonts.c "chart_fonts.c &gt;&gt;"</td>
+  <td align="right">@ref chart_data_tools.c "chart_data_tools.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -657,11 +657,36 @@ Chart 4 shows how to set segment colors and other options.
 
 
 
-@example chart_fonts.c
+@example chart_data_tools.c
 
 <table  width="600">
 <tr>
   <td>@ref chart_doughnut.c "&lt;&lt; chart_doughnut.c"</td>
+  <td align="right">@ref chart_fonts.c "chart_fonts.c &gt;&gt;"</td>
+</tr>
+</table>
+
+A demo of an various Excel chart data tools that are available via a
+libxlsxwriter chart. These include Drop Lines and High-Low Lines.
+
+
+Chart with high-low lines.
+
+@image html chart_data_tools5.png
+
+Chart with drop lines.
+
+@image html chart_data_tools6.png
+
+
+
+
+
+@example chart_fonts.c
+
+<table  width="600">
+<tr>
+  <td>@ref chart_data_tools.c "&lt;&lt; chart_data_tools.c"</td>
   <td align="right">@ref chart_pattern.c "chart_pattern.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -330,6 +330,22 @@ Chart 4 shows how to set segment colors and other options.
 @image html chart_doughnut2.png
 
 
+##############################################################
+@example chart_data_tools.c
+
+A demo of an various Excel chart data tools that are available via a
+libxlsxwriter chart. These include Drop Lines and High-Low Lines.
+
+
+Chart with high-low lines.
+
+@image html chart_data_tools5.png
+
+Chart with drop lines.
+
+@image html chart_data_tools6.png
+
+
 ##############################################################
 @example chart_fonts.c
 

examples/chart_area.c

@@ -50,7 +50,7 @@ int main() {
 
 
     /*
-     * Create a area chart.
+     * Chart 1. Create a area chart.
      */
     lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_AREA);
 
@@ -82,7 +82,7 @@ int main() {
 
 
     /*
-     * Create a stacked area chart.
+     * Chart 2. Create a stacked area chart.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_AREA_STACKED);
 
@@ -111,7 +111,7 @@ int main() {
 
 
     /*
-     * Create a percent stacked area chart.
+     * Chart 3. Create a percent stacked area chart.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_AREA_STACKED_PERCENT);
 

examples/chart_bar.c

@@ -50,7 +50,7 @@ int main() {
 
 
     /*
-     * Create a bar chart.
+     * Chart 1. Create a bar chart.
      */
     lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_BAR);
 
@@ -82,7 +82,7 @@ int main() {
 
 
     /*
-     * Create a stacked bar chart.
+     * Chart 2. Create a stacked bar chart.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_BAR_STACKED);
 
@@ -111,7 +111,7 @@ int main() {
 
 
     /*
-     * Create a percent stacked bar chart.
+     * Chart 3. Create a percent stacked bar chart.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_BAR_STACKED_PERCENT);
 

examples/chart_column.c

@@ -50,7 +50,7 @@ int main() {
 
 
     /*
-     * Create a column chart.
+     * Chart 1. Create a column chart.
      */
     lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_COLUMN);
 
@@ -82,7 +82,7 @@ int main() {
 
 
     /*
-     * Create a stacked column chart.
+     * Chart 2. Create a stacked column chart.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_COLUMN_STACKED);
 
@@ -111,7 +111,7 @@ int main() {
 
 
     /*
-     * Create a percent stacked column chart.
+     * Chart 3. Create a percent stacked column chart.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_COLUMN_STACKED_PERCENT);
 

examples/chart_data_tools.c

@@ -0,0 +1,95 @@
+/*
+ * A demo of an various Excel chart data tools that are available via a
+ * libxlsxwriter chart.
+ *
+ * These include Drop Lines and High-Low Lines.
+ *
+ * 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_tools.xlsx");
+    lxw_worksheet    *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart_series *series1;
+    lxw_chart_series *series2;
+
+    /* 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. Example with High Low Lines.
+     */
+    lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_LINE);
+
+    /* Add a chart title. */
+    chart_title_set_name(chart, "Chart with High-Low Lines");
+
+    /* Add the first series to the chart. */
+    series1 = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7");
+    series2 = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7");
+
+    /* Add high-low lines to the chart. */
+    chart_set_high_low_lines(chart, NULL);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("E2"), chart);
+
+
+    /*
+     * Chart 2. Example with Drop Lines.
+     */
+    chart = workbook_add_chart(workbook, LXW_CHART_LINE);
+
+    /* Add a chart title. */
+    chart_title_set_name(chart, "Chart with Drop Lines");
+
+    /* Add the first series to the chart. */
+    series1 = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7");
+    series2 = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7");
+
+    /* Add drop lines to the chart. */
+    chart_set_drop_lines(chart, NULL);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("E18"), chart);
+
+
+    return workbook_close(workbook);
+}

examples/chart_line.c

@@ -50,7 +50,7 @@ int main() {
 
 
     /*
-     * Create a line chart.
+     * Chart 1. Create a line chart.
      */
     lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_LINE);
 

examples/chart_radar.c

@@ -50,7 +50,7 @@ int main() {
 
 
     /*
-     * Create a radar chart.
+     * Chart 1. Create a radar chart.
      */
     lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_RADAR);
 
@@ -82,7 +82,7 @@ int main() {
 
 
     /*
-     * Create a radar chart with markers.
+     * Chart 2. Create a radar chart with markers.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_RADAR_WITH_MARKERS);
 
@@ -111,7 +111,7 @@ int main() {
 
 
     /*
-     * Create a filled radar chart.
+     * Chart 3. Create a filled radar chart.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_RADAR_FILLED);
 

examples/chart_scatter.c

@@ -50,7 +50,7 @@ int main() {
 
 
     /*
-     * Create a scatter chart, the default shows points only.
+     * Chart 1. Create a scatter chart, the default shows points only.
      */
     lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_SCATTER);
 
@@ -82,7 +82,8 @@ int main() {
 
 
     /*
-     * Create a scatter chart with straight lines and markers connecting the points.
+     * Chart 2. Create a scatter chart with straight lines and markers
+     *          connecting the points.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_SCATTER_STRAIGHT_WITH_MARKERS);
 
@@ -111,7 +112,8 @@ int main() {
 
 
     /*
-     * Create a scatter chart with straight lines connecting the points.
+     * Chart 3. Create a scatter chart with straight lines connecting the
+     *           points.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_SCATTER_STRAIGHT);
 
@@ -140,7 +142,8 @@ int main() {
 
 
     /*
-     * Create a scatter chart with smooth lines and markers connecting the points.
+     * Chart 4. Create a scatter chart with smooth lines and markers
+     *          connecting the points.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_SCATTER_SMOOTH_WITH_MARKERS);
 
@@ -169,7 +172,8 @@ int main() {
 
 
     /*
-     * Create a scatter chart with smooth lines connecting the points.
+     * Chart 5. Create a scatter chart with smooth lines connecting the
+     *          points.
      */
     chart = workbook_add_chart(workbook, LXW_CHART_SCATTER_SMOOTH);
 

include/xlsxwriter/chart.h

@@ -2364,8 +2364,62 @@ 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 and format Drop Lines for a chart.
+ *
+ * @param chart Pointer to a lxw_chart instance to be configured.
+ * @param line  A #lxw_chart_line struct.
+ *
+ * The `%chart_set_drop_lines()` function adds Drop Lines to charts to
+ * show the Category value of points in the data:
+ *
+ * @code
+ *     chart_set_drop_lines(chart, NULL);
+ * @endcode
+ *
+ * @image html chart_data_tools6.png
+ *
+ * It is possible to format the Drop Line line properties if required:
+ *
+ * @code
+ *     lxw_chart_line line = {.color     = LXW_COLOR_RED,
+ *                            .dash_type = LXW_CHART_LINE_DASH_SQUARE_DOT};
+ *
+ *     chart_set_drop_lines(chart, &line);
+ * @endcode
+ *
+ * Drop Lines are only available in Line and Area charts.
+ *
+ */
 void chart_set_drop_lines(lxw_chart *chart, lxw_chart_line *line);
 
+/**
+ * @brief Turn on and format high-low Lines for a chart.
+ *
+ * @param chart Pointer to a lxw_chart instance to be configured.
+ * @param line  A #lxw_chart_line struct.
+ *
+ * The `%chart_set_high_low_lines()` function adds High-Low Lines to charts
+ * to show the Category value of points in the data:
+ *
+ * @code
+ *     chart_set_high_low_lines(chart, NULL);
+ * @endcode
+ *
+ * @image html chart_data_tools5.png
+ *
+ * It is possible to format the High-Low Line line properties if required:
+ *
+ * @code
+ *     lxw_chart_line line = {.color     = LXW_COLOR_RED,
+ *                            .dash_type = LXW_CHART_LINE_DASH_SQUARE_DOT};
+ *
+ *     chart_set_high_low_lines(chart, &line);
+ * @endcode
+ *
+ * High-Low Lines are only available in Line charts.
+ *
+ */
 void chart_set_high_low_lines(lxw_chart *chart, lxw_chart_line *line);
 
 /**