Added docs for custom chart data labels.

docs/src/examples.dox

@@ -859,7 +859,7 @@ Chart 2 is a column chart with default data table with legend keys:
 <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>
+  <td align="right">@ref chart_data_labels.c "chart_data_labels.c &gt;&gt;"</td>
 </tr>
 </table>
 
@@ -892,11 +892,51 @@ Chart 7: chart with a trendline.
 
 
 
-@example chart_fonts.c
+@example chart_data_labels.c
 
 <table  width="600">
 <tr>
   <td>@ref chart_data_tools.c "&lt;&lt; chart_data_tools.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 label features that are available via a
+libxlsxwriter chart, including custom data labels.
+
+Chart 1: chart with standard data labels.
+@image html chart_data_labels11.png
+
+Chart 2: chart with Category and Value data labels.
+@image html chart_data_labels12.png
+
+Chart 3: chart with data labels with a user defined font.
+@image html chart_data_labels13.png
+
+Chart 4: chart with custom string data labels.
+@image html chart_data_labels14.png
+
+Chart 5: chart with custom data labels referenced from worksheet cells.
+@image html chart_data_labels15.png
+
+Chart 6: chart with a mix of custom and default labels. The items inialised
+with '{0}' and items without a custom label (points 5 and 6 which come after
+NULL) will get the default value. We also set a font for the custom items as
+an extra example.
+@image html chart_data_labels16.png
+
+Chart 7: chart with some deleted custom labels and defaults.
+@image html chart_data_labels17.png
+
+
+
+
+
+@example chart_fonts.c
+
+<table  width="600">
+<tr>
+  <td>@ref chart_data_labels.c "&lt;&lt; chart_data_labels.c"</td>
   <td align="right">@ref chart_pattern.c "chart_pattern.c &gt;&gt;"</td>
 </tr>
 </table>

docs/src/examples.txt

@@ -457,6 +457,37 @@ Chart 7: chart with a trendline.
 @image html chart_data_tools9.png
 
 
+##############################################################
+@example chart_data_labels.c
+
+A demo of an various Excel chart data label features that are available via a
+libxlsxwriter chart, including custom data labels.
+
+Chart 1: chart with standard data labels.
+@image html chart_data_labels11.png
+
+Chart 2: chart with Category and Value data labels.
+@image html chart_data_labels12.png
+
+Chart 3: chart with data labels with a user defined font.
+@image html chart_data_labels13.png
+
+Chart 4: chart with custom string data labels.
+@image html chart_data_labels14.png
+
+Chart 5: chart with custom data labels referenced from worksheet cells.
+@image html chart_data_labels15.png
+
+Chart 6: chart with a mix of custom and default labels. The items inialised
+with '{0}' and items without a custom label (points 5 and 6 which come after
+NULL) will get the default value. We also set a font for the custom items as
+an extra example.
+@image html chart_data_labels16.png
+
+Chart 7: chart with some deleted custom labels and defaults.
+@image html chart_data_labels17.png
+
+
 ##############################################################
 @example chart_fonts.c
 

docs/src/working_with_charts.dox

@@ -514,11 +514,11 @@ for a chart series:
     chart_series_set_labels(series);
 @endcode
 
-@image html chart_labels1.png
+@image html chart_data_labels1.png
 
 By default data labels are displayed in Excel with only the values shown:
 
-@image html chart_labels2.png
+@image html chart_data_labels2.png
 
 However, it is possible to configure other display options, as shown
 in the functions below.
@@ -531,7 +531,7 @@ parameters that are displayed in the series data label:
     chart_series_set_labels_options(series, LXW_TRUE, LXW_TRUE, LXW_TRUE);
 @endcode
 
-@image html chart_labels3.png
+@image html chart_data_labels3.png
 
 The `chart_series_set_labels_separator()` function is used to change the
 separator between multiple data label items. The default options is a comma
@@ -552,7 +552,7 @@ For example:
     chart_series_set_labels_separator(series, LXW_CHART_LABEL_SEPARATOR_NEWLINE);
 @endcode
 
-@image html chart_labels4.png
+@image html chart_data_labels4.png
 
 The `chart_series_set_labels_position()` function sets the position of
 the labels in the data series:
@@ -562,7 +562,7 @@ the labels in the data series:
     chart_series_set_labels_position(series, LXW_CHART_LABEL_POSITION_ABOVE);
 @endcode
 
-@image html chart_labels5.png
+@image html chart_data_labels5.png
 
 In Excel the allowable data label positions vary for different chart
 types. The allowable, and default, positions are:
@@ -603,7 +603,7 @@ legend key for a data series:
     chart_series_set_labels_legend(series);
 @endcode
 
-@image html chart_labels6.png
+@image html chart_data_labels6.png
 
 The `chart_series_set_labels_percentage()` function is used to turn on
 the display of data labels as a percentage for a series. It is mainly
@@ -615,7 +615,7 @@ used for pie charts:
     chart_series_set_labels_percentage(series);
 @endcode
 
-@image html chart_labels7.png
+@image html chart_data_labels7.png
 
 The `chart_series_set_labels_num_format()` function is used to set the
 number format for data labels:
@@ -625,7 +625,7 @@ number format for data labels:
     chart_series_set_labels_num_format(series, "$0.00");
 @endcode
 
-@image html chart_labels8.png
+@image html chart_data_labels8.png
 
 The number format is similar to the Worksheet Cell Format num_format,
 see `format_set_num_format()`.
@@ -640,10 +640,171 @@ for data labels:
     chart_series_set_labels_font(series, &font);
 @endcode
 
-@image html chart_labels9.png
+@image html chart_data_labels9.png
 
 For more information see @ref chart_fonts below.
 
+@subsection chart_custom_labels Custom Chart Data Labels
+
+The `chart_series_set_labels_custom()` function is used to set the properties
+of individual data labels in a series. The most common use for this is to set
+custom text or number labels:
+
+@code
+    // Add the series data labels.
+    chart_series_set_labels(series);
+
+    // Create some custom labels.
+    lxw_chart_data_label data_label1 = {.value = "Jan"};
+    lxw_chart_data_label data_label2 = {.value = "Feb"};
+    lxw_chart_data_label data_label3 = {.value = "Mar"};
+    lxw_chart_data_label data_label4 = {.value = "Apr"};
+    lxw_chart_data_label data_label5 = {.value = "May"};
+    lxw_chart_data_label data_label6 = {.value = "Jun"};
+
+    // Create an array of label pointers. NULL indicates the end of the array.
+    lxw_chart_data_label *data_labels[] = {
+        &data_label1,
+        &data_label2,
+        &data_label3,
+        &data_label4,
+        &data_label5,
+        &data_label6,
+        NULL
+    };
+
+    // Set the custom labels.
+    chart_series_set_labels_custom(series, data_labels);
+@endcode
+
+@image html chart_data_labels18.png
+
+As shown in the previous example the `chart_series_set_labels_custom()`
+function takes a pointer to an array of #lxw_chart_data_label pointers. The
+list should be `NULL` terminated. Any #lxw_chart_data_label items set to a
+default initialization or omitted from the list will be assigned the default
+data label value:
+
+@code
+    // Add the series data labels.
+    chart_series_set_labels(series);
+
+    // Create some custom labels.
+    lxw_chart_data_label default_label = {0};
+    lxw_chart_data_label data_label2   = {.value = "Feb"};
+    lxw_chart_data_label data_label3   = {.value = "Mar"};
+    lxw_chart_data_label data_label4   = {.value = "Apr"};
+
+
+    // Create an array of label pointers. NULL indicates the end of the array.
+    lxw_chart_data_label *data_labels[] = {
+        &default_label,
+        &data_label2,
+        &data_label3,
+        &data_label4,
+        NULL
+    };
+
+    // Set the custom labels.
+    chart_series_set_labels_custom(series, data_labels);
+@endcode
+
+@image html chart_data_labels19.png
+
+The `value` element in the #lxw_chart_data_label struct should be a string, a
+number as a string, or formula string that refers to a cell from which the
+value will be taken:
+
+@code
+    // Add the series data labels.
+    chart_series_set_labels(series);
+
+    // Create some custom labels.
+    lxw_chart_data_label data_label1 = {.value = "=Sheet1!$C$1"};
+    lxw_chart_data_label data_label2 = {.value = "=Sheet1!$C$2"};
+    lxw_chart_data_label data_label3 = {.value = "=Sheet1!$C$3"};
+    lxw_chart_data_label data_label4 = {.value = "=Sheet1!$C$4"};
+    lxw_chart_data_label data_label5 = {.value = "=Sheet1!$C$5"};
+    lxw_chart_data_label data_label6 = {.value = "=Sheet1!$C$6"};
+
+    // Create an array of label pointers. NULL indicates the end of the array.
+    lxw_chart_data_label *data_labels[] = {
+        &data_label1,
+        &data_label2,
+        &data_label3,
+        &data_label4,
+        &data_label5,
+        &data_label6,
+        NULL
+    };
+
+    // Set the custom labels.
+    chart_series_set_labels_custom(series, data_labels);
+@endcode
+
+The `font` element in the #lxw_chart_data_label struct can be used to set the
+font for the label in the data series (see @ref chart_fonts):
+
+@code
+    lxw_chart_font font = {.color = LXW_COLOR_RED};
+
+    // Add the series data labels.
+    chart_series_set_labels(series);
+
+    // Create some custom labels.
+    lxw_chart_data_label data_label1 = {.value = "=Sheet1!$C$1", .font = &font};
+    lxw_chart_data_label data_label2 = {.value = "=Sheet1!$C$2", .font = &font};
+    lxw_chart_data_label data_label3 = {.value = "=Sheet1!$C$3", .font = &font};
+    lxw_chart_data_label data_label4 = {.value = "=Sheet1!$C$4", .font = &font};
+    lxw_chart_data_label data_label5 = {.value = "=Sheet1!$C$5", .font = &font};
+    lxw_chart_data_label data_label6 = {.value = "=Sheet1!$C$6", .font = &font};
+
+    // Create an array of label pointers. NULL indicates the end of the array.
+    lxw_chart_data_label *data_labels[] = {
+        &data_label1,
+        &data_label2,
+        &data_label3,
+        &data_label4,
+        &data_label5,
+        &data_label6,
+        NULL
+    };
+
+    // Set the custom labels.
+    chart_series_set_labels_custom(series, data_labels);
+@endcode
+
+@image html chart_data_labels20.png
+
+The `delete` element in the #lxw_chart_data_label struct can be used to delete
+labels in a series. This can be useful if you want to highlight one or more
+cells in the series, for example the maximum and the minimum:
+
+@code
+    // Add the series data labels.
+    chart_series_set_labels(series);
+
+    // Create some custom labels.
+    lxw_chart_data_label delete = {.delete = LXW_TRUE};
+    lxw_chart_data_label keep   = {.delete = LXW_FALSE};
+
+    // Create an array of label pointers. NULL indicates the end of the array.
+    lxw_chart_data_label *data_labels[] = {
+        &delete,
+        &keep,
+        &delete,
+        &delete,
+        &keep,
+        &delete,
+        NULL
+    };
+
+    // Set the custom labels.
+    chart_series_set_labels_custom(series, data_labels);
+@endcode
+
+@image html chart_data_labels21.png
+
 
 @section chart_formatting Chart Formatting