Added docs for chart points.

docs/src/examples.dox

@@ -615,11 +615,18 @@ Filled radar chart:
 </tr>
 </table>
 
-Example of creating an Excel Pie chart.
+Examples of creating an Excel Pie chart.
 
 The default pie chart:
 @image html chart_pie1.png
 
+A pie chart with user defined colors:
+@image html chart_pie2.png
+
+A pie chart with rotated segments:
+@image html chart_pie3.png
+
+
 
 
 
@@ -638,6 +645,14 @@ Example of creating an Excel Doughnut chart.
 The default doughnut chart:
 @image html chart_doughnut1.png
 
+It is possible to define chart colors for most types of libxlsxwriter charts
+via the series formatting functions. However, Pie/Doughnut charts are a
+special case since each segment is represented as a point so it is necessary
+to assign formatting to each point in the series.
+
+Chart 4 shows how to set segment colors and other options.
+@image html chart_doughnut2.png
+
 
 
 

docs/src/examples.txt

@@ -300,11 +300,18 @@ Filled radar chart:
 ##############################################################
 @example chart_pie.c
 
-Example of creating an Excel Pie chart.
+Examples of creating an Excel Pie chart.
 
 The default pie chart:
 @image html chart_pie1.png
 
+A pie chart with user defined colors:
+@image html chart_pie2.png
+
+A pie chart with rotated segments:
+@image html chart_pie3.png
+
+
 
 ##############################################################
 @example chart_doughnut.c
@@ -314,6 +321,14 @@ Example of creating an Excel Doughnut chart.
 The default doughnut chart:
 @image html chart_doughnut1.png
 
+It is possible to define chart colors for most types of libxlsxwriter charts
+via the series formatting functions. However, Pie/Doughnut charts are a
+special case since each segment is represented as a point so it is necessary
+to assign formatting to each point in the series.
+
+Chart 4 shows how to set segment colors and other options.
+@image html chart_doughnut2.png
+
 
 ##############################################################
 @example chart_fonts.c

docs/src/working_with_charts.dox

@@ -146,6 +146,99 @@ For more information on line/border and fill formatting see @ref chart_lines
 and @ref chart_fills below.
 
 
+@section chart_points Working with Chart points
+
+In general formatting is applied to an entire series in a chart. However, it
+is occasionally required to format individual points within a series.
+
+In Excel charts "points" have a different meaning depending on the type of
+chart:
+
+- Line/Scatter chart: points are used to reference individual markers.
+- Bar/Column/Area charts: points are used to reference individual bars or areas.
+- Pie/Doughnut charts: points are used to reference each segment.
+
+The most common use case is to format segments of a pie chart like this
+example:
+
+@dontinclude chart_pie_colors.c
+@skip include
+@until close
+@until }
+
+@image html chart_points1.png
+
+The #lxw_chart_point objects can be used to set the following properties for a
+chart point:
+
+- Line/Border
+- Fill
+- Pattern
+
+These properties are explained in the Chart Formatting subsections below.
+
+The points should be passed as a NULL terminated array of pointers to
+#lxw_chart_point objects:
+
+@code
+    lxw_chart_point red_point   = {.fill = &red_fill  };
+    lxw_chart_point green_point = {.fill = &green_fill};
+
+    lxw_chart_point *points[] = {&green_point,
+                                 &red_point,
+                                 NULL}; // Indicates the end of the list.
+
+    chart_series_set_points(series, points);
+@endcode
+
+You can skip points in the series that you don't want to format by passing a
+zero-initialized #lxw_chart_point:
+
+@code
+    lxw_chart_point default_point = {0, 0, 0};
+
+
+    lxw_chart_line line         = {.color = LXW_COLOR_BLACK};
+    lxw_chart_fill red_fill     = {.color = LXW_COLOR_RED};
+    lxw_chart_fill green_fill   = {.color = LXW_COLOR_GREEN};
+
+    lxw_chart_point red_point   = {.fill = &red_fill,   .line = &line};
+    lxw_chart_point green_point = {.fill = &green_fill, .line = &line};
+
+    lxw_chart_point *points[] = {&red_point,
+                                 &default_point,
+                                 &green_point,
+                                 &default_point,
+                                 &red_point,
+                                 NULL};
+
+    chart_series_set_points(series, points);
+
+    chart_series_set_marker_type(series, LXW_CHART_MARKER_SQUARE);
+    chart_series_set_marker_size(series, 10);
+@endcode
+
+@image html chart_points2.png
+
+The array of #lxw_chart_point objects pointers corresponds to the order of the
+points in the series starting from the first point. However, it does not have
+to extend to the entire range of the series. It can be NULL terminated at any
+point in the series, such as in the previous example.
+
+For Bar/Column/Area charts "points" refer to bars/areas within the chart:
+
+@code
+    lxw_chart_fill  red_fill      = {.color = LXW_COLOR_RED};
+    lxw_chart_point red_point     = {.fill = &red_fill};
+    lxw_chart_point default_point = {0, 0, 0};
+
+    lxw_chart_point *points[] = {&default_point, &default_point, &red_point, NULL};
+
+    chart_series_set_points(series2, points);
+@endcode
+
+@image html chart_points3.png
+
 @section chart_formatting Chart Formatting
 
 The following chart formatting properties can be set for any chart object that

examples/chart_doughnut.c

@@ -1,6 +1,12 @@
 /*
  * An example of creating an Excel doughnut chart using the libxlsxwriter library.
  *
+ * The demo also shows how to set segment colors. It is possible to define
+ * chart colors for most types of libxlsxwriter charts via the series
+ * formatting functions. However, Pie/Doughnut charts are a special case since
+ * each segment is represented as a point so it is necessary to assign
+ * formatting to each point in the series.
+ *
  * Copyright 2014-2017, John McNamara, jmcnamara@cpan.org
  *
  */
@@ -25,11 +31,13 @@ void write_worksheet_data(lxw_worksheet *worksheet, lxw_format *bold) {
 
 /*
  * Create a worksheet with examples charts.
+ *
  */
 int main() {
 
     lxw_workbook     *workbook  = new_workbook("chart_doughnut.xlsx");
     lxw_worksheet    *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart *chart ;
     lxw_chart_series *series;
 
     /* Add a bold format to use to highlight the header cells. */
@@ -41,9 +49,9 @@ int main() {
 
 
     /*
-     * Create a doughnut chart.
+     * Chart 1: Create a simple doughnut chart.
      */
-    lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_DOUGHNUT);
+    chart = workbook_add_chart(workbook, LXW_CHART_DOUGHNUT);
 
     /* Add the first series to the chart. */
     series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4");
@@ -61,5 +69,94 @@ int main() {
     worksheet_insert_chart(worksheet, CELL("D2"), chart);
 
 
+    /*
+     * Chart 2: Create a doughnut chart with user defined segment colors.
+     */
+    chart = workbook_add_chart(workbook, LXW_CHART_DOUGHNUT);
+
+    /* Add the first series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4");
+
+    /* Set the name for the series instead of the default "Series 1". */
+    chart_series_set_name(series, "Doughnut sales data");
+
+    /* Add a chart title. */
+    chart_title_set_name(chart, "Doughnut Chart with user defined colors");
+
+    /* Add for fills for use in the chart. */
+    lxw_chart_fill fill1 = {.color = 0xFA58D0};
+    lxw_chart_fill fill2 = {.color = 0x61210B};
+    lxw_chart_fill fill3 = {.color = 0xF5F6CE};
+
+    /* Add some points with the above fills. */
+    lxw_chart_point point1 = {.fill = &fill1};
+    lxw_chart_point point2 = {.fill = &fill2};
+    lxw_chart_point point3 = {.fill = &fill3};
+
+    /* Create an array of the point objects. */
+    lxw_chart_point *points[] = {&point1,
+                                 &point2,
+                                 &point3,
+                                 NULL};
+
+    /* Add/override the points/segments of the chart. */
+    chart_series_set_points(series, points);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("D18"), chart);
+
+
+    /*
+     * Chart 3: Create a Doughnut chart with rotation of the segments.
+     */
+    chart = workbook_add_chart(workbook, LXW_CHART_DOUGHNUT);
+
+    /* Add the first series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4");
+
+    /* Set the name for the series instead of the default "Series 1". */
+    chart_series_set_name(series, "Doughnut sales data");
+
+    /* Add a chart title. */
+    chart_title_set_name(chart, "Doughnut Chart with segment rotation");
+
+
+    /* Change the angle/rotation of the first segment. */
+    chart_set_rotation(chart, 90);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("D34"), chart);
+
+
+    /*
+     * Chart 4: Create a Doughnut chart with user defined hole size and other
+     *          options.
+     */
+    chart = workbook_add_chart(workbook, LXW_CHART_DOUGHNUT);
+
+    /* Add the first series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4");
+
+    /* Set the name for the series instead of the default "Series 1". */
+    chart_series_set_name(series, "Doughnut sales data");
+
+    /* Add a chart title. */
+    chart_title_set_name(chart, "Doughnut Chart with options applied.");
+
+    /* Add/override the points/segments defined in Chart 2. */
+    chart_series_set_points(series, points);
+
+    /* Set an Excel chart style. */
+    chart_set_style(chart, 26);
+
+    /* Change the angle/rotation of the first segment. */
+    chart_set_rotation(chart, 28);
+
+    /* Change the hole size. */
+    chart_set_hole_size(chart, 33);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("D50"), chart);
+
     return workbook_close(workbook);
 }

examples/chart_pie.c

@@ -1,6 +1,12 @@
 /*
  * An example of creating an Excel pie chart using the libxlsxwriter library.
  *
+ * The demo also shows how to set segment colors. It is possible to define
+ * chart colors for most types of libxlsxwriter charts via the series
+ * formatting functions. However, Pie/Doughnut charts are a special case since
+ * each segment is represented as a point so it is necessary to assign
+ * formatting to each point in the series.
+ *
  * Copyright 2014-2017, John McNamara, jmcnamara@cpan.org
  *
  */
@@ -25,11 +31,13 @@ void write_worksheet_data(lxw_worksheet *worksheet, lxw_format *bold) {
 
 /*
  * Create a worksheet with examples charts.
+ *
  */
 int main() {
 
     lxw_workbook     *workbook  = new_workbook("chart_pie.xlsx");
     lxw_worksheet    *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart *chart ;
     lxw_chart_series *series;
 
     /* Add a bold format to use to highlight the header cells. */
@@ -41,9 +49,9 @@ int main() {
 
 
     /*
-     * Create a pie chart.
+     * Chart 1: Create a simple pie chart.
      */
-    lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_PIE);
+    chart = workbook_add_chart(workbook, LXW_CHART_PIE);
 
     /* Add the first series to the chart. */
     series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4");
@@ -61,5 +69,64 @@ int main() {
     worksheet_insert_chart(worksheet, CELL("D2"), chart);
 
 
+    /*
+     * Chart 2: Create a pie chart with user defined segment colors.
+     */
+    chart = workbook_add_chart(workbook, LXW_CHART_PIE);
+
+    /* Add the first series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4");
+
+    /* Set the name for the series instead of the default "Series 1". */
+    chart_series_set_name(series, "Pie sales data");
+
+    /* Add a chart title. */
+    chart_title_set_name(chart, "Pie Chart with user defined colors");
+
+    /* Add for fills for use in the chart. */
+    lxw_chart_fill fill1 = {.color = 0x5ABA10};
+    lxw_chart_fill fill2 = {.color = 0xFE110E};
+    lxw_chart_fill fill3 = {.color = 0xCA5C05};
+
+    /* Add some points with the above fills. */
+    lxw_chart_point point1 = {.fill = &fill1};
+    lxw_chart_point point2 = {.fill = &fill2};
+    lxw_chart_point point3 = {.fill = &fill3};
+
+    /* Create an array of the point objects. */
+    lxw_chart_point *points[] = {&point1,
+                                 &point2,
+                                 &point3,
+                                 NULL};
+
+    /* Add/override the points/segments of the chart. */
+    chart_series_set_points(series, points);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("D18"), chart);
+
+
+    /*
+     * Chart 3: Create a pie chart with rotation of the segments.
+     */
+    chart = workbook_add_chart(workbook, LXW_CHART_PIE);
+
+    /* Add the first series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4");
+
+    /* Set the name for the series instead of the default "Series 1". */
+    chart_series_set_name(series, "Pie sales data");
+
+    /* Add a chart title. */
+    chart_title_set_name(chart, "Pie Chart with segment rotation");
+
+
+    /* Change the angle/rotation of the first segment. */
+    chart_set_rotation(chart, 90);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("D34"), chart);
+
+
     return workbook_close(workbook);
 }

examples/chart_pie_colors.c

@@ -0,0 +1,62 @@
+/*
+ * An example of creating an Excel pie chart with user defined colors using
+ * the libxlsxwriter library.
+ *
+ * In general formatting is applied to an entire series in a chart. However,
+ * it is occasionally required to format individual points in a series. In
+ * particular this is required for Pie/Doughnut charts where each segment is
+ * represented by a point.
+
+ * Copyright 2014-2017, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+
+/*
+ * Create a worksheet with an example Pie chart.
+ */
+int main() {
+
+    lxw_workbook     *workbook  = new_workbook("chart_pie_colors.xlsx");
+    lxw_worksheet    *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart_series *series;
+
+
+    /* Write some data for the chart. */
+    worksheet_write_string(worksheet, CELL("A1"), "Pass", NULL);
+    worksheet_write_string(worksheet, CELL("A2"), "Fail", NULL);
+    worksheet_write_number(worksheet, CELL("B1"), 90,     NULL);
+    worksheet_write_number(worksheet, CELL("B2"), 10,     NULL);
+
+    /* Create a pie chart. */
+    lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_PIE);
+
+    /* Add the data series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$1:$A$2",
+                                     "=Sheet1!$B$1:$B$2");
+
+    /* Create some fills for the chart points/segments. */
+    lxw_chart_fill red_fill     = {.color = LXW_COLOR_RED  };
+    lxw_chart_fill green_fill   = {.color = LXW_COLOR_GREEN};
+
+    /* Add the fills to the point objects. */
+    lxw_chart_point red_point   = {.fill = &red_fill  };
+    lxw_chart_point green_point = {.fill = &green_fill};
+
+    /* Create an array of pointer to chart points. Note, the array should be
+     * NULL terminated. */
+    lxw_chart_point *points[] = {&green_point,
+                                 &red_point,
+                                 NULL};
+
+    /* Add the points to the series. */
+    chart_series_set_points(series, points);
+
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("D2"), chart);
+
+    return workbook_close(workbook);
+}

examples/chart_working_with_example.c

@@ -33,7 +33,7 @@ int main() {
 
     (void)series; /* Do something with series in the real examples. */
 
-     /* Insert the chart into the worksheet. */
+    /* Insert the chart into the worksheet. */
     worksheet_insert_chart(worksheet, CELL("C1"), chart);
 
     return workbook_close(workbook);

include/xlsxwriter/chart.h

@@ -686,10 +686,21 @@ typedef struct lxw_chart_title {
 
 } lxw_chart_title;
 
+/**
+ * @brief Struct to represent an Excel chart data point.
+ *
+ * The lxw_chart_point used to set the line, fill and pattern of one or more
+ * points in a chart data series. See @ref chart_points.
+ */
 typedef struct lxw_chart_point {
 
+    /** The line/border for the chart point. See @ref chart_lines. */
     lxw_chart_line *line;
+
+    /** The fill for the chart point. See @ref chart_fills. */
     lxw_chart_fill *fill;
+
+    /** The pattern for the chart point. See @ref chart_patterns.*/
     lxw_chart_pattern *pattern;
 
 } lxw_chart_point;
@@ -1295,6 +1306,30 @@ void chart_series_set_marker_fill(lxw_chart_series *series,
 void chart_series_set_marker_pattern(lxw_chart_series *series,
                                      lxw_chart_pattern *pattern);
 
+/**
+ * @brief Set the formatting for points in the series.
+ *
+ * @param series A series object created via `chart_add_series()`.
+ * @param points An NULL terminated array of #lxw_chart_point pointers.
+ *
+ * @return A #lxw_error.
+ *
+ * In general formatting is applied to an entire series in a chart. However,
+ * it is occasionally required to format individual points in a series. In
+ * particular this is required for Pie/Doughnut charts where each segment is
+ * represented by a point.
+ *
+ * @dontinclude chart_pie_colors.c
+ * @skip Add the data series
+ * @until chart_series_set_points
+ *
+ * @image html chart_points1.png
+ *
+ * @note The array of #lxw_chart_point pointers should be NULL terminated
+ * as shown in the example.
+ *
+ * For more details see @ref chart_points
+ */
 lxw_error chart_series_set_points(lxw_chart_series *series,
                                   lxw_chart_point *points[]);
 
@@ -2303,7 +2338,45 @@ void chart_plotarea_set_pattern(lxw_chart *chart, lxw_chart_pattern *pattern);
  */
 void chart_set_style(lxw_chart *chart, uint8_t style_id);
 
+/**
+ * @brief Set the Pie/Doughnut chart rotation.
+ *
+ * @param chart    Pointer to a lxw_chart instance to be configured.
+ * @param rotation The angle of rotation.
+ *
+ * The `chart_set_rotation()` function is used to set the rotation of the
+ * first segment of a Pie/Doughnut chart. This has the effect of rotating
+ * the entire chart:
+ *
+ * @code
+ *     chart_set_rotation(chart, 28);
+ * @endcode
+ *
+ * The angle of rotation must be in the range `0 <= rotation <= 360`.
+ *
+ * This option is only available for Pie/Doughnut charts.
+ *
+ */
 void chart_set_rotation(lxw_chart *chart, uint16_t rotation);
+
+/**
+ * @brief Set the Doughnut chart hole size.
+ *
+ * @param chart Pointer to a lxw_chart instance to be configured.
+ * @param size  The hole size as a percentage.
+ *
+ * The `chart_set_hole_size()` function is used to set the hole size of a
+ * Doughnut chart:
+ *
+ * @code
+ *     chart_set_hole_size(chart, 33);
+ * @endcode
+ *
+ * The hole size must be in the range `10 <= size <= 90`.
+ *
+ * This option is only available for Doughnut charts.
+ *
+ */
 void chart_set_hole_size(lxw_chart *chart, uint8_t size);
 
 lxw_error lxw_chart_add_data_cache(lxw_series_range *range, uint8_t *data,