Added docs for data label formatting.

docs/src/examples.dox

@@ -913,21 +913,27 @@ Chart 2: chart with Category and Value data labels.
 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.
+Chart 4: chart with data labels and formatting.
+@image html chart_data_labels22.png
+
+Chart 5: chart with custom string data labels.
 @image html chart_data_labels14.png
 
-Chart 5: chart with custom data labels referenced from worksheet cells.
+Chart 6: 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 initialized
+Chart 7: chart with a mix of custom and default labels. The items initialized
 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.
+Chart 8: chart with some deleted custom labels and defaults.
 @image html chart_data_labels17.png
 
+Chart 9: chart with custom string data labels and formatting.
+@image html chart_data_labels23.png
+
 
 
 

docs/src/examples.txt

@@ -472,21 +472,27 @@ Chart 2: chart with Category and Value data labels.
 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.
+Chart 4: chart with data labels and formatting.
+@image html chart_data_labels22.png
+
+Chart 5: chart with custom string data labels.
 @image html chart_data_labels14.png
 
-Chart 5: chart with custom data labels referenced from worksheet cells.
+Chart 6: 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 initialized
+Chart 7: chart with a mix of custom and default labels. The items initialized
 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.
+Chart 8: chart with some deleted custom labels and defaults.
 @image html chart_data_labels17.png
 
+Chart 9: chart with custom string data labels and formatting.
+@image html chart_data_labels23.png
+
 
 ##############################################################
 @example chart_fonts.c

docs/src/working_with_charts.dox

@@ -644,6 +644,21 @@ for data labels:
 
 For more information see @ref chart_fonts below.
 
+The `chart_series_set_labels_line()`, `chart_series_set_labels_fill()` and
+`chart_series_set_labels_pattern()` functions can be used to set the
+formatting for a data series using standard chart formatting structs:
+
+@code
+    lxw_chart_line line = {.color = LXW_COLOR_RED};
+    lxw_chart_fill fill = {.color = LXW_COLOR_YELLOW};
+
+    chart_series_set_labels_line(series, &line);
+    chart_series_set_labels_fill(series, &fill);
+@endcode
+
+@image html chart_data_labels24.png
+
+
 @subsection chart_custom_labels Custom Chart Data Labels
 
 The `chart_series_set_labels_custom()` function is used to set the properties
@@ -806,6 +821,47 @@ one or more cells in the series, for example the maximum and the minimum:
 @image html chart_data_labels21.png
 
 
+Standard chart formatting such as #lxw_chart_line, #lxw_chart_fill and
+#lxw_chart_pattern can also be applied to custom data labels via
+#lxw_chart_data_label:
+
+@code
+    // Set the border/line and fill for the data labels.
+    lxw_chart_line line2 = {.color = LXW_COLOR_RED};
+    lxw_chart_fill fill2 = {.color = LXW_COLOR_YELLOW};
+    lxw_chart_line line3 = {.color = LXW_COLOR_BLUE};
+    lxw_chart_fill fill3 = {.color = LXW_COLOR_GREEN};
+
+    // Create some custom labels.
+    lxw_chart_data_label data_label9_1 = {.value = "Amy", .line = &line3};
+    lxw_chart_data_label data_label9_2 = {.value = "Bea"};
+    lxw_chart_data_label data_label9_3 = {.value = "Eva"};
+    lxw_chart_data_label data_label9_4 = {.value = "Fay"};
+    lxw_chart_data_label data_label9_5 = {.value = "Liv"};
+    lxw_chart_data_label data_label9_6 = {.value = "Una", .fill = &fill3};
+
+    // Set the default formatting for the data labels in the series.
+    chart_series_set_labels_line(series, &line2);
+    chart_series_set_labels_fill(series, &fill2);
+
+    // Create an array of label pointers. NULL indicates the end of the array.
+    lxw_chart_data_label *data_labels9[] = {
+        &data_label9_1,
+        &data_label9_2,
+        &data_label9_3,
+        &data_label9_4,
+        &data_label9_5,
+        &data_label9_6,
+        NULL
+    };
+
+    /* Set the custom labels. */
+    chart_series_set_labels_custom(series, data_labels9);
+@endcode
+
+@image html chart_data_labels25.png
+
+
 @section chart_formatting Chart Formatting
 
 The following chart formatting properties can be set for any chart object that

examples/chart_data_labels.c

@@ -166,21 +166,21 @@ int main() {
     chart_series_set_labels(series);
 
     /* Create some custom labels. */
-    lxw_chart_data_label data_label51 = {.value = "Amy"};
-    lxw_chart_data_label data_label52 = {.value = "Bea"};
-    lxw_chart_data_label data_label53 = {.value = "Eva"};
-    lxw_chart_data_label data_label54 = {.value = "Fay"};
-    lxw_chart_data_label data_label55 = {.value = "Liv"};
-    lxw_chart_data_label data_label56 = {.value = "Una"};
+    lxw_chart_data_label data_label5_1 = {.value = "Amy"};
+    lxw_chart_data_label data_label5_2 = {.value = "Bea"};
+    lxw_chart_data_label data_label5_3 = {.value = "Eva"};
+    lxw_chart_data_label data_label5_4 = {.value = "Fay"};
+    lxw_chart_data_label data_label5_5 = {.value = "Liv"};
+    lxw_chart_data_label data_label5_6 = {.value = "Una"};
 
     /* Create an array of label pointers. NULL indicates the end of the array. */
     lxw_chart_data_label *data_labels5[] = {
-        &data_label51,
-        &data_label52,
-        &data_label53,
-        &data_label54,
-        &data_label55,
-        &data_label56,
+        &data_label5_1,
+        &data_label5_2,
+        &data_label5_3,
+        &data_label5_4,
+        &data_label5_5,
+        &data_label5_6,
         NULL
     };
 
@@ -210,21 +210,21 @@ int main() {
     chart_series_set_labels(series);
 
     /* Create some custom labels. */
-    lxw_chart_data_label data_label61 = {.value = "=Sheet1!$C$2"};
-    lxw_chart_data_label data_label62 = {.value = "=Sheet1!$C$3"};
-    lxw_chart_data_label data_label63 = {.value = "=Sheet1!$C$4"};
-    lxw_chart_data_label data_label64 = {.value = "=Sheet1!$C$5"};
-    lxw_chart_data_label data_label65 = {.value = "=Sheet1!$C$6"};
-    lxw_chart_data_label data_label66 = {.value = "=Sheet1!$C$7"};
+    lxw_chart_data_label data_label6_1 = {.value = "=Sheet1!$C$2"};
+    lxw_chart_data_label data_label6_2 = {.value = "=Sheet1!$C$3"};
+    lxw_chart_data_label data_label6_3 = {.value = "=Sheet1!$C$4"};
+    lxw_chart_data_label data_label6_4 = {.value = "=Sheet1!$C$5"};
+    lxw_chart_data_label data_label6_5 = {.value = "=Sheet1!$C$6"};
+    lxw_chart_data_label data_label6_6 = {.value = "=Sheet1!$C$7"};
 
     /* Create an array of label pointers. NULL indicates the end of the array. */
     lxw_chart_data_label *data_labels6[] = {
-        &data_label61,
-        &data_label62,
-        &data_label63,
-        &data_label64,
-        &data_label65,
-        &data_label66,
+        &data_label6_1,
+        &data_label6_2,
+        &data_label6_3,
+        &data_label6_4,
+        &data_label6_5,
+        &data_label6_6,
         NULL
     };
 
@@ -262,17 +262,17 @@ int main() {
      * and 6 which come after NULL) will get the default value. We also set a
      * font for the custom items as an extra example.
      */
-    lxw_chart_data_label data_label71 = {.value = "=Sheet1!$C$2", .font = &font2};
-    lxw_chart_data_label data_label72 = {0};
-    lxw_chart_data_label data_label73 = {.value = "=Sheet1!$C$4", .font = &font2};
-    lxw_chart_data_label data_label74 = {.value = "=Sheet1!$C$5", .font = &font2};
+    lxw_chart_data_label data_label7_1 = {.value = "=Sheet1!$C$2", .font = &font2};
+    lxw_chart_data_label data_label7_2 = {0};
+    lxw_chart_data_label data_label7_3 = {.value = "=Sheet1!$C$4", .font = &font2};
+    lxw_chart_data_label data_label7_4 = {.value = "=Sheet1!$C$5", .font = &font2};
 
     /* Create an array of label pointers. NULL indicates the end of the array. */
     lxw_chart_data_label *data_labels7[] = {
-        &data_label71,
-        &data_label72,
-        &data_label73,
-        &data_label74,
+        &data_label7_1,
+        &data_label7_2,
+        &data_label7_3,
+        &data_label7_4,
         NULL
     };
 
@@ -350,25 +350,26 @@ int main() {
     lxw_chart_line line3 = {.color = LXW_COLOR_BLUE};
     lxw_chart_fill fill3 = {.color = LXW_COLOR_GREEN};
 
+    /* Create some custom labels. */
+    lxw_chart_data_label data_label9_1 = {.value = "Amy", .line = &line3};
+    lxw_chart_data_label data_label9_2 = {.value = "Bea"};
+    lxw_chart_data_label data_label9_3 = {.value = "Eva"};
+    lxw_chart_data_label data_label9_4 = {.value = "Fay"};
+    lxw_chart_data_label data_label9_5 = {.value = "Liv"};
+    lxw_chart_data_label data_label9_6 = {.value = "Una", .fill = &fill3};
+
+    /* Set the default formatting for the data labels in the series. */
     chart_series_set_labels_line(series, &line2);
     chart_series_set_labels_fill(series, &fill2);
 
-    /* Create some custom labels. */
-    lxw_chart_data_label data_label91 = {.value = "Amy", .line = &line3};
-    lxw_chart_data_label data_label92 = {.value = "Bea"};
-    lxw_chart_data_label data_label93 = {.value = "Eva"};
-    lxw_chart_data_label data_label94 = {.value = "Fay"};
-    lxw_chart_data_label data_label95 = {.value = "Liv"};
-    lxw_chart_data_label data_label96 = {.value = "Una", .fill = &fill3};
-
     /* Create an array of label pointers. NULL indicates the end of the array. */
     lxw_chart_data_label *data_labels9[] = {
-        &data_label91,
-        &data_label92,
-        &data_label93,
-        &data_label94,
-        &data_label95,
-        &data_label96,
+        &data_label9_1,
+        &data_label9_2,
+        &data_label9_3,
+        &data_label9_4,
+        &data_label9_5,
+        &data_label9_6,
         NULL
     };
 

include/xlsxwriter/chart.h

@@ -1091,8 +1091,8 @@ typedef struct lxw_chart {
     uint8_t subtype;
     uint16_t series_index;
 
-    void (*write_chart_type) (struct lxw_chart *);
-    void (*write_plot_area) (struct lxw_chart *);
+    void (*write_chart_type)(struct lxw_chart *);
+    void (*write_plot_area)(struct lxw_chart *);
 
     /**
      * A pointer to the chart x_axis object which can be used in functions
@@ -1952,14 +1952,66 @@ void chart_series_set_labels_num_format(lxw_chart_series *series,
 void chart_series_set_labels_font(lxw_chart_series *series,
                                   lxw_chart_font *font);
 
+/**
+ * @brief Set the line properties for the data labels in a chart series.
+ *
+ * @param series A series object created via `chart_add_series()`.
+ * @param line   A #lxw_chart_line struct.
+ *
+ * Set the line/border properties of the data labels in a chart series:
+ *
+ * @code
+ *     lxw_chart_line line = {.color = LXW_COLOR_RED};
+ *     lxw_chart_fill fill = {.color = LXW_COLOR_YELLOW};
+ *
+ *     chart_series_set_labels_line(series, &line);
+ *     chart_series_set_labels_fill(series, &fill);
+ *
+ * @endcode
+ *
+ * @image html chart_data_labels24.png
+ *
+ * For more information see @ref chart_lines and @ref chart_labels.
+ */
 void chart_series_set_labels_line(lxw_chart_series *series,
                                   lxw_chart_line *line);
 
+/**
+ * @brief Set the fill properties for the data labels in a chart series.
+ *
+ * @param series A series object created via `chart_add_series()`.
+ * @param fill   A #lxw_chart_fill struct.
+ *
+ * Set the fill properties of the data labels in a chart series:
+ *
+ * @code
+ *     lxw_chart_fill fill = {.color = LXW_COLOR_YELLOW};
+ *
+ *     chart_series_set_labels_fill(series, &fill);
+ * @endcode
+ *
+ * See the example and image above and also see @ref chart_fills and
+ * @ref chart_labels.
+ */
 void chart_series_set_labels_fill(lxw_chart_series *series,
                                   lxw_chart_fill *fill);
 
+/**
+ * @brief Set the pattern properties for the data labels in a chart series.
+ *
+ * @param series  A series object created via `chart_add_series()`.
+ * @param pattern A #lxw_chart_pattern struct.
+ *
+ * Set the pattern properties of the data labels in a chart series:
+ *
+ * @code
+ *     chart_series_set_labels_pattern(series, &pattern);
+ * @endcode
+ *
+ * For more information see #lxw_chart_pattern_type and @ref chart_patterns.
+ */
 void chart_series_set_labels_pattern(lxw_chart_series *series,
-                                     lxw_chart_pattern *line);
+                                     lxw_chart_pattern *pattern);
 
 /**
  * @brief Turn on a trendline for a chart data series.