ext/xlsxwriter/libxlsxwriter/include/xlsxwriter/chart.h in xlsxwriter-0.2.1.pre.2 vs ext/xlsxwriter/libxlsxwriter/include/xlsxwriter/chart.h in xlsxwriter-0.2.2
- old
+ new
@@ -1,9 +1,9 @@
/*
* libxlsxwriter
*
- * Copyright 2014-2019, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
+ * Copyright 2014-2020, John McNamara, jmcnamara@cpan.org. See LICENSE.txt.
*
* chart - A libxlsxwriter library for creating Excel XLSX chart files.
*
*/
@@ -122,10 +122,16 @@
LXW_CHART_DOUGHNUT,
/** Line chart. */
LXW_CHART_LINE,
+ /** Line chart - stacked. */
+ LXW_CHART_LINE_STACKED,
+
+ /** Line chart - percentage stacked. */
+ LXW_CHART_LINE_STACKED_PERCENT,
+
/** Pie chart. */
LXW_CHART_PIE,
/** Scatter chart. */
LXW_CHART_SCATTER,
@@ -645,13 +651,10 @@
uint8_t dash_type;
/** Set the transparency of the line. 0 - 100. Default 0. */
uint8_t transparency;
- /* Members for internal use only. */
- uint8_t has_color;
-
} lxw_chart_line;
/**
* @brief Struct to represent a chart fill.
*
@@ -666,13 +669,10 @@
uint8_t none;
/** Set the transparency of the fill. 0 - 100. Default 0. */
uint8_t transparency;
- /* Members for internal use only. */
- uint8_t has_color;
-
} lxw_chart_fill;
/**
* @brief Struct to represent a chart pattern.
*
@@ -687,14 +687,10 @@
lxw_color_t bg_color;
/** The pattern type. See #lxw_chart_pattern_type. */
uint8_t type;
- /* Members for internal use only. */
- uint8_t has_fg_color;
- uint8_t has_bg_color;
-
} lxw_chart_pattern;
/**
* @brief Struct to represent a chart font.
*
@@ -715,29 +711,28 @@
uint8_t italic;
/** The chart font underline property. Set to 0 or 1. */
uint8_t underline;
- /** The chart font rotation property. Range: -90 to 90. */
+ /** The chart font rotation property. Range: -90 to 90, and 270-271.
+ * The angle 270 gives a stacked (top to bottom) alignment.
+ * The angle 271 gives a stacked alignment for East Asian fonts.
+ * */
int32_t rotation;
/** The chart font color. See @ref working_with_colors. */
lxw_color_t color;
- /** The chart font pitch family property. Rarely required. set to 0. */
+ /** The chart font pitch family property. Rarely required, set to 0. */
uint8_t pitch_family;
- /** The chart font character set property. Rarely required. set to 0. */
+ /** The chart font character set property. Rarely required, set to 0. */
uint8_t charset;
- /** The chart font baseline property. Rarely required. set to 0. */
+ /** The chart font baseline property. Rarely required, set to 0. */
int8_t baseline;
- /* Members for internal use only. */
-
- uint8_t has_color;
-
} lxw_chart_font;
typedef struct lxw_chart_marker {
uint8_t type;
@@ -791,10 +786,58 @@
lxw_chart_pattern *pattern;
} lxw_chart_point;
/**
+ * @brief Struct to represent an Excel chart data label.
+ *
+ * The lxw_chart_data_label struct is used to represent a data label in a
+ * chart series so that custom properties can be set for it.
+ */
+typedef struct lxw_chart_data_label {
+
+ /** The string or formula value for the data label. See
+ * @ref chart_custom_labels. */
+ char *value;
+
+ /** Option to hide/delete the data label from the chart series.
+ * See @ref chart_custom_labels. */
+ uint8_t hide;
+
+ /** The font properties for the chart data label. @ref chart_fonts. */
+ lxw_chart_font *font;
+
+ /** The line/border for the chart data label. See @ref chart_lines. */
+ lxw_chart_line *line;
+
+ /** The fill for the chart data label. See @ref chart_fills. */
+ lxw_chart_fill *fill;
+
+ /** The pattern for the chart data label. See @ref chart_patterns.*/
+ lxw_chart_pattern *pattern;
+
+} lxw_chart_data_label;
+
+/* Internal version of lxw_chart_data_label with more metadata. */
+typedef struct lxw_chart_custom_label {
+
+ char *value;
+ uint8_t hide;
+ lxw_chart_font *font;
+ lxw_chart_line *line;
+ lxw_chart_fill *fill;
+ lxw_chart_pattern *pattern;
+
+ /* We use a range to hold the label formula properties even though it
+ * will only have 1 point in order to re-use similar functions.*/
+ lxw_series_range *range;
+
+ struct lxw_series_data_point data_point;
+
+} lxw_chart_custom_label;
+
+/**
* @brief Define how blank values are displayed in a chart.
*/
typedef enum lxw_chart_blank {
/** Show empty chart cells as gaps in the data. The default. */
@@ -919,11 +962,13 @@
lxw_chart_line *line;
lxw_chart_fill *fill;
lxw_chart_pattern *pattern;
lxw_chart_marker *marker;
lxw_chart_point *points;
+ lxw_chart_custom_label *data_labels;
uint16_t point_count;
+ uint16_t data_label_count;
uint8_t smooth;
uint8_t invert_if_negative;
/* Data label parameters. */
@@ -937,10 +982,13 @@
uint8_t label_position;
uint8_t label_separator;
uint8_t default_label_position;
char *label_num_format;
lxw_chart_font *label_font;
+ lxw_chart_line *label_line;
+ lxw_chart_fill *label_fill;
+ lxw_chart_pattern *label_pattern;
lxw_series_error_bars *x_error_bars;
lxw_series_error_bars *y_error_bars;
uint8_t has_trendline;
@@ -1041,12 +1089,12 @@
uint8_t type;
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
* that configures the X axis.
*/
@@ -1625,15 +1673,15 @@
*
* @code
* 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.
*
* For more information see @ref chart_labels.
@@ -1654,18 +1702,75 @@
* @code
* chart_series_set_labels(series);
* chart_series_set_labels_options(series, LXW_TRUE, LXW_TRUE, LXW_TRUE);
* @endcode
*
- * @image html chart_labels3.png
+ * @image html chart_data_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 properties for data labels in a series.
+*
+* @param series A series object created via `chart_add_series()`.
+* @param data_labels An NULL terminated array of #lxw_chart_data_label pointers.
+*
+* @return A #lxw_error.
+*
+* The `%chart_series_set_labels_custom()` function is used to set the properties
+* for data labels in a series. It can also be used to delete individual data
+* labels in a series.
+*
+* In general properties are set for all the data labels in a chart
+* series. However, it is also possible to set properties for individual data
+* labels in a series using `%chart_series_set_labels_custom()`.
+*
+* 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:
+*
+* @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
+*
+* @note The array of #lxw_chart_point pointers should be NULL terminated as
+* shown in the example. Any #lxw_chart_data_label items set to a default
+* initialization or omitted from the list will be assigned the default data
+* label value.
+*
+* For more details see @ref chart_custom_labels.
+*/
+lxw_error chart_series_set_labels_custom(lxw_chart_series *series, lxw_chart_data_label
+ *data_labels[]);
+
/**
* @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:
@@ -1688,11 +1793,11 @@
* 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
+ * @image html chart_data_labels4.png
*
* For more information see @ref chart_labels.
*/
void chart_series_set_labels_separator(lxw_chart_series *series,
uint8_t separator);
@@ -1709,11 +1814,11 @@
* @code
* chart_series_set_labels(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:
*
* | Position | Line, Scatter | Bar, Column | Pie, Doughnut | Area, Radar |
@@ -1769,11 +1874,11 @@
* @code
* chart_series_set_labels(series);
* chart_series_set_labels_legend(series);
* @endcode
*
- * @image html chart_labels6.png
+ * @image html chart_data_labels6.png
*
* For more information see @ref chart_labels.
*/
void chart_series_set_labels_legend(lxw_chart_series *series);
@@ -1790,11 +1895,11 @@
* 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
+ * @image html chart_data_labels7.png
*
* For more information see @ref chart_labels.
*/
void chart_series_set_labels_percentage(lxw_chart_series *series);
@@ -1810,11 +1915,11 @@
* @code
* chart_series_set_labels(series);
* 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()`.
*
* For more information see @ref chart_labels.
@@ -1837,16 +1942,77 @@
*
* chart_series_set_labels(series);
* 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 and @ref chart_labels.
*
*/
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 *pattern);
/**
* @brief Turn on a trendline for a chart data series.
*
* @param series A series object created via `chart_add_series()`.