Add docs for chart data labels.

docs/src/examples.dox

@@ -715,20 +715,19 @@ libxlsxwriter chart. These include Drop Lines and High-Low Lines.
 
 
 Chart 1: chart with high-low lines.
-
 @image html chart_data_tools5.png
 
 Chart 2: chart with drop lines.
-
 @image html chart_data_tools6.png
 
 Chart 3: chart with Up-down bars.
-
 @image html chart_data_tools4.png
 
 Chart 4: chart with formatted Up-down bars.
+@image html chart_data_tools7.png
 
-@image html chart_up_down_bars.png
+Chart 5: chart with markers and data labels.
+@image html chart_data_tools8.png
 
 
 

docs/src/examples.txt

@@ -364,20 +364,19 @@ libxlsxwriter chart. These include Drop Lines and High-Low Lines.
 
 
 Chart 1: chart with high-low lines.
-
 @image html chart_data_tools5.png
 
 Chart 2: chart with drop lines.
-
 @image html chart_data_tools6.png
 
 Chart 3: chart with Up-down bars.
-
 @image html chart_data_tools4.png
 
 Chart 4: chart with formatted Up-down bars.
+@image html chart_data_tools7.png
 
-@image html chart_up_down_bars.png
+Chart 5: chart with markers and data labels.
+@image html chart_data_tools8.png
 
 
 ##############################################################

docs/src/working_with_charts.dox

@@ -59,7 +59,7 @@ A Scatter chart (but not a Line chart) has 2 value axes:
 @note Date axes aren't supported yet.
 
 
-@section chart_markers Working with Chart markers
+@section chart_markers Working with Chart Markers
 
 In Excel a chart marker is used to distinguish data points in a plotted
 series. In general only Line and Scatter and Radar chart types use
@@ -146,7 +146,7 @@ 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
+@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.
@@ -239,6 +239,151 @@ For Bar/Column/Area charts "points" refer to bars/areas within the chart:
 
 @image html chart_points3.png
 
+
+@section chart_labels Working with Chart Data Labels
+
+Data labels can be added to a chart series to indicate the values of the
+plotted data points. The functions described below turn on and set data
+label properties.
+
+The `chart_series_set_labels()` function is used to turn on data labels
+for a chart series:
+
+@code
+    chart_series_set_labels(series);
+@endcode
+
+@image html chart_labels1.png
+
+By default data labels are displayed in Excel with only the values shown:
+
+@image html chart_labels2.png
+
+However, it is possible to configure other display options, as shown
+in the functions below.
+
+The `chart_series_set_labels_options()` function is used to set the
+parameters that are displayed in the series data label:
+
+@code
+    chart_series_set_labels(series);
+    chart_series_set_labels_options(series, LXW_TRUE, LXW_TRUE, LXW_TRUE);
+@endcode
+
+@image html chart_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
+separator as shown in the previous example.
+
+The available options are:
+
+- #LXW_CHART_LABEL_SEPARATOR_SEMICOLON: semicolon separator.
+- #LXW_CHART_LABEL_SEPARATOR_PERIOD: a period (dot) separator.
+- #LXW_CHART_LABEL_SEPARATOR_NEWLINE: a newline separator.
+- #LXW_CHART_LABEL_SEPARATOR_SPACE: a space separator.
+
+For example:
+
+@code
+    chart_series_set_labels(series);
+    chart_series_set_labels_options(series, LXW_TRUE, LXW_TRUE, LXW_TRUE);
+    chart_series_set_labels_separator(series, LXW_CHART_LABEL_SEPARATOR_NEWLINE);
+@endcode
+
+@image html chart_labels4.png
+
+The `chart_series_set_labels_position()` function sets the position of
+the labels in the data series:
+
+@code
+    chart_series_set_labels(series);
+    chart_series_set_labels_position(series, LXW_CHART_LABEL_POSITION_ABOVE);
+@endcode
+
+@image html chart_labels5.png
+
+In Excel the allowable data label positions vary for different chart
+types. The allowable, and default, positions are:
+
+| Position                              | Line, Scatter | Bar, Column   | Pie, Doughnut | Area, Radar   |
+| :------------------------------------ | :------------ | :------------ | :------------ | :------------ |
+| #LXW_CHART_LABEL_POSITION_CENTER      | Yes           | Yes           | Yes           | Yes (default) |
+| #LXW_CHART_LABEL_POSITION_RIGHT       | Yes (default) |               |               |               |
+| #LXW_CHART_LABEL_POSITION_LEFT        | Yes           |               |               |               |
+| #LXW_CHART_LABEL_POSITION_ABOVE       | Yes           |               |               |               |
+| #LXW_CHART_LABEL_POSITION_BELOW       | Yes           |               |               |               |
+| #LXW_CHART_LABEL_POSITION_INSIDE_BASE |               | Yes           |               |               |
+| #LXW_CHART_LABEL_POSITION_INSIDE_END  |               | Yes           | Yes           |               |
+| #LXW_CHART_LABEL_POSITION_OUTSIDE_END |               | Yes (default) | Yes           |               |
+| #LXW_CHART_LABEL_POSITION_BEST_FIT    |               |               | Yes (default) |               |
+
+
+The `chart_series_set_labels_leader_line()` function  is used to turn on
+leader lines for the data label of a series. It is mainly used for pie
+or doughnut charts:
+
+@code
+    chart_series_set_labels(series);
+    chart_series_set_labels_leader_line(series);
+@endcode
+
+@note Even when leader lines are turned on they aren't automatically
+      visible in Excel or XlsxWriter. Due to an Excel limitation
+      (or design) leader lines only appear if the data label is moved
+      manually or if the data labels are very close and need to be
+      adjusted automatically.
+
+The `chart_series_set_labels_legend()` function is used to set the
+legend key for a data series:
+
+@code
+    chart_series_set_labels(series);
+    chart_series_set_labels_legend(series);
+@endcode
+
+@image html chart_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
+used for pie charts:
+
+@code
+    chart_series_set_labels(series);
+    chart_series_set_labels_options(series, LXW_FALSE, LXW_FALSE, LXW_FALSE);
+    chart_series_set_labels_percentage(series);
+@endcode
+
+@image html chart_labels7.png
+
+The `chart_series_set_labels_num_format()` function is used to set the
+number format for data labels:
+
+@code
+    chart_series_set_labels(series);
+    chart_series_set_labels_num_format(series, "$0.00");
+@endcode
+
+@image html chart_labels8.png
+
+The number format is similar to the Worksheet Cell Format num_format,
+see `format_set_num_format()`.
+
+The `chart_series_set_labels_font()` function is used to set the font
+for data labels:
+
+@code
+    lxw_chart_font font = {.name = "Consolas", .color = LXW_COLOR_RED};
+
+    chart_series_set_labels(series);
+    chart_series_set_labels_font(series, &font);
+@endcode
+
+@image html chart_labels9.png
+
+For more information see @ref chart_fonts below.
+
+
 @section chart_formatting Chart Formatting
 
 The following chart formatting properties can be set for any chart object that

examples/chart_data_tools.c

@@ -42,7 +42,7 @@ int main() {
 
     lxw_workbook     *workbook  = new_workbook("chart_data_tools.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);
@@ -126,10 +126,32 @@ int main() {
     lxw_chart_fill down_fill = {.color = LXW_COLOR_RED};
 
     chart_set_up_down_bars_format(chart, &line, &up_fill, &line, &down_fill);
-    
+
     /* Insert the chart into the worksheet. */
     worksheet_insert_chart(worksheet, CELL("E50"), chart);
 
 
+    /*
+     * Chart 5. Example with Markers and data labels.
+     */
+    chart = workbook_add_chart(workbook, LXW_CHART_LINE);
+
+    /* Add a chart title. */
+    chart_title_set_name(chart, "Chart with Data Labels and Markers");
+
+    /* Add the first series to the chart. */
+    series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7");
+    chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7");
+
+    /* Add series markers. */
+    chart_series_set_marker_type(series, LXW_CHART_MARKER_CIRCLE);
+
+    /* Add sereis data labels. */
+    chart_series_set_labels(series);
+
+    /* Insert the chart into the worksheet. */
+    worksheet_insert_chart(worksheet, CELL("E66"), chart);
+
+
     return workbook_close(workbook);
 }

include/xlsxwriter/chart.h

@@ -1466,27 +1466,236 @@ lxw_error chart_series_set_points(lxw_chart_series *series,
  */
 void chart_series_set_smooth(lxw_chart_series *series, uint8_t smooth);
 
+/**
+ * @brief Add data labels to a chart series.
+ *
+ * @param series A series object created via `chart_add_series()`.
+ *
+ * The `%chart_series_set_labels()` function is used to turn on data labels
+ * for a chart series. Data labels indicate the values of the plotted data
+ * points.
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ * @endcode
+ *
+ * @image html chart_labels1.png
+ *
+ * By default data labels are displayed in Excel with only the values shown:
+ *
+ * @image html chart_labels2.png
+ *
+ * However, it is possible to configure other display options, as shown
+ * in the functions below.
+ *
+ * For more information see @ref chart_labels.
+ */
 void chart_series_set_labels(lxw_chart_series *series);
 
+/**
+ * @brief Set the display options for the labels of a data series.
+ *
+ * @param series        A series object created via `chart_add_series()`.
+ * @param show_name     Turn on/off the series name in the label caption.
+ * @param show_category Turn on/off the category name in the label caption.
+ * @param show_value    Turn on/off the value in the label caption.
+ *
+ * The `%chart_series_set_labels_options()` function is used to set the
+ * parameters that are displayed in the series data label:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_options(series, LXW_TRUE, LXW_TRUE, LXW_TRUE);
+ * @endcode
+ *
+ * @image html chart_labels3.png
+ *
+ * For more information see @ref chart_labels.
+ */
 void chart_series_set_labels_options(lxw_chart_series *series,
                                      uint8_t show_name, uint8_t show_category,
                                      uint8_t show_value);
 
+/**
+ * @brief Set the separator for the data label captions.
+ *
+ * @param series    A series object created via `chart_add_series()`.
+ * @param separator The separator for the data label options:
+ *                  #lxw_chart_label_separator.
+ *
+ * The `%chart_series_set_labels_separator()` function is used to change the
+ * separator between multiple data label items. The default options is a comma
+ * separator as shown in the previous example.
+ *
+ * The available options are:
+ *
+ * - #LXW_CHART_LABEL_SEPARATOR_SEMICOLON: semicolon separator.
+ * - #LXW_CHART_LABEL_SEPARATOR_PERIOD: a period (dot) separator.
+ * - #LXW_CHART_LABEL_SEPARATOR_NEWLINE: a newline separator.
+ * - #LXW_CHART_LABEL_SEPARATOR_SPACE: a space separator.
+ *
+ * For example:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_options(series, LXW_TRUE, LXW_TRUE, LXW_TRUE);
+ *     chart_series_set_labels_separator(series, LXW_CHART_LABEL_SEPARATOR_NEWLINE);
+ * @endcode
+ *
+ * @image html chart_labels4.png
+ *
+ * For more information see @ref chart_labels.
+ */
 void chart_series_set_labels_separator(lxw_chart_series *series,
                                        uint8_t separator);
 
+/**
+ * @brief Set the data label position for a series.
+ *
+ * @param series   A series object created via `chart_add_series()`.
+ * @param position The data label position: #lxw_chart_label_position.
+ *
+ * The `%chart_series_set_labels_position()` function sets the position of
+ * the labels in the data series:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_position(series, LXW_CHART_LABEL_POSITION_ABOVE);
+ * @endcode
+ *
+ * @image html chart_labels5.png
+ *
+ * In Excel the allowable data label positions vary for different chart
+ * types. The allowable, and default, positions are:
+ *
+ * | Position                              | Line, Scatter | Bar, Column   | Pie, Doughnut | Area, Radar   |
+ * | :------------------------------------ | :------------ | :------------ | :------------ | :------------ |
+ * | #LXW_CHART_LABEL_POSITION_CENTER      | Yes           | Yes           | Yes           | Yes (default) |
+ * | #LXW_CHART_LABEL_POSITION_RIGHT       | Yes (default) |               |               |               |
+ * | #LXW_CHART_LABEL_POSITION_LEFT        | Yes           |               |               |               |
+ * | #LXW_CHART_LABEL_POSITION_ABOVE       | Yes           |               |               |               |
+ * | #LXW_CHART_LABEL_POSITION_BELOW       | Yes           |               |               |               |
+ * | #LXW_CHART_LABEL_POSITION_INSIDE_BASE |               | Yes           |               |               |
+ * | #LXW_CHART_LABEL_POSITION_INSIDE_END  |               | Yes           | Yes           |               |
+ * | #LXW_CHART_LABEL_POSITION_OUTSIDE_END |               | Yes (default) | Yes           |               |
+ * | #LXW_CHART_LABEL_POSITION_BEST_FIT    |               |               | Yes (default) |               |
+ *
+ *
+ * For more information see @ref chart_labels.
+ */
 void chart_series_set_labels_position(lxw_chart_series *series,
                                       uint8_t position);
 
+/**
+ * @brief Set leader lines for Pie and Doughnut charts.
+ *
+ * @param series A series object created via `chart_add_series()`.
+ *
+ * The `%chart_series_set_labels_leader_line()` function  is used to turn on
+ * leader lines for the data label of a series. It is mainly used for pie
+ * or doughnut charts:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_leader_line(series);
+ * @endcode
+ *
+ * @note Even when leader lines are turned on they aren't automatically
+ *       visible in Excel or XlsxWriter. Due to an Excel limitation
+ *       (or design) leader lines only appear if the data label is moved
+ *       manually or if the data labels are very close and need to be
+ *       adjusted automatically.
+ *
+ * For more information see @ref chart_labels.
+ */
 void chart_series_set_labels_leader_line(lxw_chart_series *series);
 
+/**
+ * @brief Set the legend key for a data label in a chart series.
+ *
+ * @param series A series object created via `chart_add_series()`.
+ *
+ * The `%chart_series_set_labels_legend()` function is used to set the
+ * legend key for a data series:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_legend(series);
+ * @endcode
+ *
+ * @image html chart_labels6.png
+ *
+ * For more information see @ref chart_labels.
+ */
 void chart_series_set_labels_legend(lxw_chart_series *series);
 
+/**
+ * @brief Set the percentage for a Pie/Doughnut data point.
+ *
+ * @param series A series object created via `chart_add_series()`.
+ *
+ * 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
+ * used for pie charts:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_options(series, LXW_FALSE, LXW_FALSE, LXW_FALSE);
+ *     chart_series_set_labels_percentage(series);
+ * @endcode
+ *
+ * @image html chart_labels7.png
+ *
+ * For more information see @ref chart_labels.
+ */
 void chart_series_set_labels_percentage(lxw_chart_series *series);
 
+/**
+ * @brief Set the number format for chart data labels in a series.
+ *
+ * @param series     A series object created via `chart_add_series()`.
+ * @param num_format The number format string.
+ *
+ * The `%chart_series_set_labels_num_format()` function is used to set the
+ * number format for data labels:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_num_format(series, "$0.00");
+ * @endcode
+ *
+ * @image html chart_labels8.png
+ *
+ * The number format is similar to the Worksheet Cell Format num_format,
+ * see `format_set_num_format()`.
+ *
+ * For more information see @ref chart_labels.
+ */
 void chart_series_set_labels_num_format(lxw_chart_series *series,
                                         char *num_format);
 
+/**
+ * @brief Set the font properties for chart data labels in a series
+ *
+ * @param series A series object created via `chart_add_series()`.
+ * @param font   A pointer to a chart #lxw_chart_font font struct.
+ *
+ *
+ * The `%chart_series_set_labels_font()` function is used to set the font
+ * for data labels:
+ *
+ * @code
+ *     lxw_chart_font font = {.name = "Consolas", .color = LXW_COLOR_RED};
+ *
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_font(series, &font);
+ * @endcode
+ *
+ * @image html chart_labels9.png
+ *
+ * For more information see @ref chart_fonts and @ref chart_labels.
+ *
+ */
 void chart_series_set_labels_font(lxw_chart_series *series,
                                   lxw_chart_font *font);
 
@@ -2811,3 +3020,148 @@ STATIC void _chart_write_legend(lxw_chart *chart);
 /* *INDENT-ON* */
 
 #endif /* __LXW_CHART_H__ */
+
+/**
+ * Data labels can be added to a chart series to indicate the values of the
+ * plotted data points. The functions described below turn on and set data
+ * label properties.
+ *
+ * The `%chart_series_set_labels()` function is used to turn on data labels
+ * for a chart series. Data labels indicate the values of the plotted data
+ * points.
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ * @endcode
+ *
+ * @image html chart_labels1.png
+ *
+ * By default data labels are displayed in Excel with only the values shown:
+ *
+ * @image html chart_labels2.png
+ *
+ * However, it is possible to configure other display options, as shown
+ * in the functions below.
+ *
+ * The `%chart_series_set_labels_options()` function is used to set the
+ * parameters that are displayed in the series data label:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_options(series, LXW_TRUE, LXW_TRUE, LXW_TRUE);
+ * @endcode
+ *
+ * @image html chart_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
+ * separator as shown in the previous example.
+ *
+ * The available options are:
+ *
+ * - #LXW_CHART_LABEL_SEPARATOR_SEMICOLON: semicolon separator.
+ * - #LXW_CHART_LABEL_SEPARATOR_PERIOD: a period (dot) separator.
+ * - #LXW_CHART_LABEL_SEPARATOR_NEWLINE: a newline separator.
+ * - #LXW_CHART_LABEL_SEPARATOR_SPACE: a space separator.
+ *
+ * For example:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_options(series, LXW_TRUE, LXW_TRUE, LXW_TRUE);
+ *     chart_series_set_labels_separator(series, LXW_CHART_LABEL_SEPARATOR_NEWLINE);
+ * @endcode
+ *
+ * @image html chart_labels4.png
+ *
+ * The `%chart_series_set_labels_position()` function sets the position of
+ * the labels in the data series:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_position(series, LXW_CHART_LABEL_POSITION_ABOVE);
+ * @endcode
+ *
+ * @image html chart_labels5.png
+ *
+ * In Excel the allowable data label positions vary for different chart
+ * types. The allowable, and default, positions are:
+ *
+ * | Position                              | Line, Scatter | Bar, Column   | Pie, Doughnut | Area, Radar   |
+ * | :------------------------------------ | :------------ | :------------ | :------------ | :------------ |
+ * | #LXW_CHART_LABEL_POSITION_CENTER      | Yes           | Yes           | Yes           | Yes (default) |
+ * | #LXW_CHART_LABEL_POSITION_RIGHT       | Yes (default) |               |               |               |
+ * | #LXW_CHART_LABEL_POSITION_LEFT        | Yes           |               |               |               |
+ * | #LXW_CHART_LABEL_POSITION_ABOVE       | Yes           |               |               |               |
+ * | #LXW_CHART_LABEL_POSITION_BELOW       | Yes           |               |               |               |
+ * | #LXW_CHART_LABEL_POSITION_INSIDE_BASE |               | Yes           |               |               |
+ * | #LXW_CHART_LABEL_POSITION_INSIDE_END  |               | Yes           | Yes           |               |
+ * | #LXW_CHART_LABEL_POSITION_OUTSIDE_END |               | Yes (default) | Yes           |               |
+ * | #LXW_CHART_LABEL_POSITION_BEST_FIT    |               |               | Yes (default) |               |
+ *
+ *
+ * The `%chart_series_set_labels_leader_line()` function  is used to turn on
+ * leader lines for the data label of a series. It is mainly used for pie
+ * or doughnut charts:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_leader_line(series);
+ * @endcode
+ *
+ * @note Even when leader lines are turned on they aren't automatically
+ *       visible in Excel or XlsxWriter. Due to an Excel limitation
+ *       (or design) leader lines only appear if the data label is moved
+ *       manually or if the data labels are very close and need to be
+ *       adjusted automatically.
+ *
+ * The `%chart_series_set_labels_legend()` function is used to set the
+ * legend key for a data series:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_legend(series);
+ * @endcode
+ *
+ * @image html chart_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
+ * used for pie charts:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_options(series, LXW_FALSE, LXW_FALSE, LXW_FALSE);
+ *     chart_series_set_labels_percentage(series);
+ * @endcode
+ *
+ * @image html chart_labels7.png
+ *
+ * The `%chart_series_set_labels_num_format()` function is used to set the
+ * number format for data labels:
+ *
+ * @code
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_num_format(series, "$0.00");
+ * @endcode
+ *
+ * @image html chart_labels8.png
+ *
+ * The number format is similar to the Worksheet Cell Format num_format,
+ * see `format_set_num_format()`.
+ *
+ * The `%chart_series_set_labels_font()` function is used to set the font
+ * for data labels:
+ *
+ * @code
+ *     lxw_chart_font font = {.name = "Consolas", .color = LXW_COLOR_RED};
+ *
+ *     chart_series_set_labels(series);
+ *     chart_series_set_labels_font(series, &font);
+ * @endcode
+ *
+ * @image html chart_labels9.png
+ *
+ * For more information see @ref chart_fonts and @ref chart_labels.
+ *
+ */

src/chart.c

@@ -82,7 +82,6 @@ _chart_free_font(lxw_chart_font *font)
     free(font);
 }
 
-
 /*
  * Free a series object.
  */
@@ -128,7 +127,6 @@ _chart_init_data_cache(lxw_series_range *range)
     return LXW_NO_ERROR;
 }
 
-
 /*
  * Free a chart object.
  */