libxlsxwriter/include/xlsxwriter/chart.h in fast_excel-0.4.1 vs libxlsxwriter/include/xlsxwriter/chart.h in fast_excel-0.5.0

- old
+ new

@@ -1,9 +1,9 @@ /* * libxlsxwriter * - * Copyright 2014-2019, John McNamara, jmcnamara@cpan.org. See LICENSE.txt. + * Copyright 2014-2022, 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,25 +687,21 @@ 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. * * See @ref chart_fonts. */ typedef struct lxw_chart_font { /** The chart font name, such as "Arial" or "Calibri". */ - char *name; + const char *name; /** The chart font size. The default is 11. */ double size; /** The chart font bold property. Set to 0 or 1. */ @@ -715,29 +711,31 @@ 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 and 360: + * + * - The angles -90 to 90 are the normal range shown in the Excel user interface. + * - The angle 270 gives a stacked (top to bottom) alignment. + * - The angle 271 gives a stacked alignment for East Asian fonts. + * - The angle 360 gives an explicit angle of 0 to override the y axis default. + * */ 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 +789,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. */ + const 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 +965,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 +985,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; @@ -1022,10 +1073,11 @@ uint8_t display_units; uint8_t display_units_visible; uint8_t has_crossing; + uint8_t crossing_min; uint8_t crossing_max; double crossing; } lxw_chart_axis; @@ -1041,12 +1093,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 +1677,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 +1706,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 +1797,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 +1818,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 +1878,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 +1899,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 +1919,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,19 +1946,80 @@ * * 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()`. * @param type The type of trendline: #lxw_chart_trendline_type. * @param value The order/period value for polynomial and moving average @@ -2533,10 +2703,30 @@ * See @ref ww_charts_axes. */ void chart_axis_set_crossing_max(lxw_chart_axis *axis); /** + * @brief Set the opposite axis crossing position as the axis minimum. + * + * @param axis A pointer to a chart #lxw_chart_axis object. + * + * Set the position that the opposite axis will cross as the axis minimum. + * The default axis crossing position is generally the axis minimum so this + * function can be used to reverse the location of the axes without reversing + * the number sequence: + * + * @code + * chart_axis_set_crossing_min(chart->x_axis); + * chart_axis_set_crossing_min(chart->y_axis); + * @endcode + * + * **Axis types**: This function is applicable to to all axes types. + * See @ref ww_charts_axes. + */ +void chart_axis_set_crossing_min(lxw_chart_axis *axis); + +/** * @brief Turn off/hide an axis. * * @param axis A pointer to a chart #lxw_chart_axis object. * * Turn off, hide, a chart axis: @@ -3043,16 +3233,30 @@ * * The `%chart_title_set_name_font()` function is used to set the font of a * chart title: * * @code - * lxw_chart_font font = {.bold = LXW_TRUE, .color = LXW_COLOR_BLUE}; + * lxw_chart_font font = {.color = LXW_COLOR_BLUE}; * * chart_title_set_name(chart, "Year End Results"); * chart_title_set_name_font(chart, &font); * @endcode * * @image html chart_title_set_name_font.png + * + * In Excel a chart title font is bold by default (as shown in the image + * above). To turn off bold in the font you cannot use #LXW_FALSE (0) since + * that is indistinguishable from an uninitialized value. Instead you should + * use #LXW_EXPLICIT_FALSE: + * + * @code + * lxw_chart_font font = {.bold = LXW_EXPLICIT_FALSE, .color = LXW_COLOR_BLUE}; + * + * chart_title_set_name(chart, "Year End Results"); + * chart_title_set_name_font(chart, &font); + * @endcode + * + * @image html chart_title_set_name_font2.png * * For more information see @ref chart_fonts. */ void chart_title_set_name_font(lxw_chart *chart, lxw_chart_font *font);