diff --git a/docs/Doxyfile b/docs/Doxyfile index 670fad6e..9c9588e4 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -769,6 +769,7 @@ INPUT = src/mainpage.dox \ src/working_with_formats.dox \ src/working_with_colors.dox \ src/working_with_dates.dox \ + src/working_with_charts.dox \ src/working_with_memory.dox \ src/examples.dox \ src/running_the_tests.dox \ diff --git a/docs/images/chart_line_opt.png b/docs/images/chart_line_opt.png new file mode 100644 index 00000000..38e3048e Binary files /dev/null and b/docs/images/chart_line_opt.png differ diff --git a/docs/src/mainpage.dox b/docs/src/mainpage.dox index 0d9fc796..3d6aa955 100644 --- a/docs/src/mainpage.dox +++ b/docs/src/mainpage.dox @@ -47,6 +47,7 @@ following sections for more information: - @ref working_with_formats - @ref working_with_colors - @ref working_with_dates +- @ref working_with_charts - @ref working_with_memory - @ref examples diff --git a/docs/src/working_with_charts.dox b/docs/src/working_with_charts.dox new file mode 100644 index 00000000..8ebc936d --- /dev/null +++ b/docs/src/working_with_charts.dox @@ -0,0 +1,49 @@ +/** +@page working_with_charts Working with Charts + +This section explains how to work with some of the options and features of +@ref chart.h "The Chart object". + + +Chart Value and Category Axes +----------------------------- + +When working with charts it is important to understand how Excel +differentiates between a chart axis that is used for series categories and a +chart axis that is used for series values. + +In the example above the X axis is the **category** axis and each of the values +is evenly spaced and sequential. The Y axis is the **value** axis and points +are displayed according to their value. + +Excel treats these two types of axis differently and exposes different +properties for each. + +As such some of the `libxlsxwriter`` axis properties can be set for a value +axis, some can be set for a category axis and some properties can be set for +both. The documentation calls out the type of axis to which functions apply. + + +Chart Limitations +----------------- + +The following chart features aren't currently supported in libxlsxwriter but +will be in time: + +- Chart formatting. +- Chart markers. +- Secondary axis. +- Combined charts. +- Chart legend formatting. +- Chart area and plot area formatting. +- Chart tables. +- Up down lines. +- Drop boxes. + +If required these features are all available in the Perl and Python versions +of this library. + + +Next: @ref working_with_memory + +*/ diff --git a/docs/src/working_with_dates.dox b/docs/src/working_with_dates.dox index 85a5a4cb..f30f6fdf 100644 --- a/docs/src/working_with_dates.dox +++ b/docs/src/working_with_dates.dox @@ -75,6 +75,6 @@ is a longer example that shows the same date in a several different formats: @image html date_example03.png -Next: @ref working_with_memory +Next: @ref working_with_charts */ diff --git a/examples/chart_area.c b/examples/chart_area.c index abce3dd9..8571e10c 100644 --- a/examples/chart_area.c +++ b/examples/chart_area.c @@ -57,7 +57,7 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add a second series but leave the categories and values undefined. They @@ -89,13 +89,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ @@ -118,13 +118,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ diff --git a/examples/chart_bar.c b/examples/chart_bar.c index 92ce0ef8..9f8e43aa 100644 --- a/examples/chart_bar.c +++ b/examples/chart_bar.c @@ -57,7 +57,7 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add a second series but leave the categories and values undefined. They @@ -89,13 +89,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ @@ -118,13 +118,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ diff --git a/examples/chart_column.c b/examples/chart_column.c index 9f02e355..eece43b1 100644 --- a/examples/chart_column.c +++ b/examples/chart_column.c @@ -57,7 +57,7 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add a second series but leave the categories and values undefined. They @@ -89,13 +89,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ @@ -118,13 +118,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ diff --git a/examples/chart_doughnut.c b/examples/chart_doughnut.c index dee628b4..ab300638 100644 --- a/examples/chart_doughnut.c +++ b/examples/chart_doughnut.c @@ -48,7 +48,7 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "Doughnut sales data"); /* Add a chart title. */ diff --git a/examples/chart_line.c b/examples/chart_line.c index 2c22a1c2..5349b902 100644 --- a/examples/chart_line.c +++ b/examples/chart_line.c @@ -57,7 +57,7 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add a second series but leave the categories and values undefined. They diff --git a/examples/chart_pie.c b/examples/chart_pie.c index f39118f8..17f39b5c 100644 --- a/examples/chart_pie.c +++ b/examples/chart_pie.c @@ -48,7 +48,7 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$4", "=Sheet1!$B$2:$B$4"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "Pie sales data"); /* Add a chart title. */ diff --git a/examples/chart_radar.c b/examples/chart_radar.c index 54aa60ff..15667604 100644 --- a/examples/chart_radar.c +++ b/examples/chart_radar.c @@ -57,7 +57,7 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add a second series but leave the categories and values undefined. They @@ -89,13 +89,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ @@ -118,13 +118,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ diff --git a/examples/chart_scatter.c b/examples/chart_scatter.c index 6b97a5a2..8f41f18e 100644 --- a/examples/chart_scatter.c +++ b/examples/chart_scatter.c @@ -57,7 +57,7 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add a second series but leave the categories and values undefined. They @@ -89,13 +89,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ @@ -118,13 +118,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ @@ -147,13 +147,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ @@ -176,13 +176,13 @@ int main() { /* Add the first series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$B$2:$B$7"); - /* Set the name for the series instead of the default "Series1". */ + /* Set the name for the series instead of the default "Series 1". */ chart_series_set_name(series, "=Sheet1!$B1$1"); /* Add the second series to the chart. */ series = chart_add_series(chart, "=Sheet1!$A$2:$A$7", "=Sheet1!$C$2:$C$7"); - /* Set the name for the series instead of the default "Series2". */ + /* Set the name for the series instead of the default "Series 2". */ chart_series_set_name(series, "=Sheet1!$C1$1"); /* Add a chart title and some axis labels. */ diff --git a/include/xlsxwriter/chart.h b/include/xlsxwriter/chart.h index 5b44adab..e5c5bb78 100644 --- a/include/xlsxwriter/chart.h +++ b/include/xlsxwriter/chart.h @@ -23,7 +23,8 @@ * adding data series to the chart and for configuring the chart. * * A Chart object isn't created directly. Instead a chart is created by - * calling the workbook_add_chart() function from a Workbook object: + * calling the `workbook_add_chart()` function from a Workbook object. For + * example: * * @code * @@ -342,7 +343,8 @@ void lxw_chart_assemble_xml_file(lxw_chart *chart); * @return A lxw_chart_series object pointer. * * In Excel a chart **series** is a collection of information that defines - * which data is plotted such as values, axis labels and formatting. + * which data is plotted such as the categories and values. It is also used to + * define the formatting for the data. * * For an libxlsxwriter chart object the `%chart_add_series()` function is * used to set the categories and values of the series: @@ -368,11 +370,11 @@ void lxw_chart_assemble_xml_file(lxw_chart *chart); * only mandatory option for every chart object. This parameter links the * chart with the worksheet data that it displays. * - * The `categories` and `values` should be a string formula like it is - * represented in Excel such as `"=Sheet1!$A$2:$A$7"`. This is convenient when - * recreating a chart from an example in Excel or when the range is - * particularly complex but it is trickier to generate programmatically. For - * these cases set the `categories` and `values` to `NULL` and use the + * The `categories` and `values` should be a string formula like + * `"=Sheet1!$A$2:$A$7"` in the same way it is represented in Excel. This is + * convenient when recreating a chart from an example in Excel but it is + * trickier to generate programmatically. For these cases you can set the + * `categories` and `values` to `NULL` and use the * `chart_series_set_categories()` and `chart_series_set_values()` functions: * * @code @@ -383,7 +385,7 @@ void lxw_chart_assemble_xml_file(lxw_chart *chart); * chart_series_set_values( series, "Sheet1", 1, 2, 6, 2); // "=Sheet1!$C$2:$C$7" * @endcode * - * As shown in the previous example the return values from + * As shown in the previous example the return value from * `%chart_add_series()` is a lxw_chart_series pointer. This can be used in * other functions that configure a series. * @@ -642,8 +644,8 @@ void chart_title_off(lxw_chart *chart); * @param chart Pointer to a lxw_chart instance to be configured. * @param style_id An index representing the chart style, 1 - 48. * - * The `%chart_set_style()` method is used to set the style of the chart to one - * of the 48 built-in styles available on the "Design" tab in Excel 2007: + * The `%chart_set_style()` function is used to set the style of the chart to + * one of the 48 built-in styles available on the "Design" tab in Excel 2007: * * @code * chart_set_style(chart, 37) @@ -660,7 +662,7 @@ void chart_title_off(lxw_chart *chart); * were referred to as "Layouts" in previous versions of Excel. These layouts * are not defined in the file format. They are a collection of modifications * to the base chart type. They can not be defined by the `chart_set_style()`` - * method. + * function. * * */ diff --git a/include/xlsxwriter/workbook.h b/include/xlsxwriter/workbook.h index 79a3bbbd..46e84fd2 100644 --- a/include/xlsxwriter/workbook.h +++ b/include/xlsxwriter/workbook.h @@ -420,7 +420,7 @@ lxw_format *workbook_add_format(lxw_workbook *workbook); * * See @ref chart.h for details. */ -lxw_chart *workbook_add_chart(lxw_workbook *workbook, uint8_t chart_type); +lxw_chart *workbook_add_chart(lxw_workbook *workbook, uint8_t chart_type); /** * @brief Close the Workbook object and write the XLSX file. diff --git a/include/xlsxwriter/worksheet.h b/include/xlsxwriter/worksheet.h index 99480843..1b3d5e9b 100644 --- a/include/xlsxwriter/worksheet.h +++ b/include/xlsxwriter/worksheet.h @@ -1292,7 +1292,7 @@ int worksheet_insert_image(lxw_worksheet *worksheet, * #lxw_image_options struct to scale and position the image: * * @code - * lxw_image_options options = {.x_offset = 30, .y_offset = 10, + * lxw_image_options options = {.x_offset = 30, .y_offset = 10, * .x_scale = 0.5, .y_scale = 0.5}; * * worksheet_insert_image_opt(worksheet, 2, 1, "logo.png", &options); @@ -1308,11 +1308,6 @@ int worksheet_insert_image_opt(lxw_worksheet *worksheet, lxw_row_t row, lxw_col_t col, const char *filename, lxw_image_options *options); - -int worksheet_insert_chart_opt(lxw_worksheet *worksheet, - lxw_row_t row_num, lxw_col_t col_num, - lxw_chart *chart, - lxw_image_options *user_options); /** * @brief Insert a chart object into a worksheet. * @@ -1324,8 +1319,9 @@ int worksheet_insert_chart_opt(lxw_worksheet *worksheet, * @return 0 for success, non-zero on error. * * The `%worksheet_insert_chart()` can be used to insert a chart into a - * worksheet. A chart object is created via the `workbook_add_chart()` - * function: + * worksheet. The chart object must be created first using the + * `workbook_add_chart()` function and configured using the @ref chart.h + * functions. * * @code * // Create a chart object. @@ -1343,14 +1339,47 @@ int worksheet_insert_chart_opt(lxw_worksheet *worksheet, * * **Note:** * - * A chart can only be inserted into a worksheet once. If several similar + * A chart may only be inserted into a worksheet once. If several similar * charts are required then each one must be created separately with * `%worksheet_insert_chart()`. * */ int worksheet_insert_chart(lxw_worksheet *worksheet, - lxw_row_t row, lxw_col_t col, - lxw_chart *chart); + lxw_row_t row, lxw_col_t col, lxw_chart *chart); + +/** + * @brief Insert a chart object into a worksheet, with options. + * + * @param worksheet Pointer to a lxw_worksheet instance to be updated. + * @param row The zero indexed row number. + * @param col The zero indexed column number. + * @param chart A #lxw_chart object created via workbook_add_chart(). + * @param user_options Optional chart parameters. + * + * @return 0 for success, non-zero on error. + * + * The `%worksheet_insert_chart_opt()` function is like + * `worksheet_insert_chart()` function except that it takes an optional + * #lxw_image_options struct to scale and position the image of the chart: + * + * @code + * lxw_image_options options = {.x_offset = 30, .y_offset = 10, + * .x_scale = 0.5, .y_scale = 0.75}; + * + * worksheet_insert_chart_opt(worksheet, 0, 2, chart, &options); + * + * @endcode + * + * @image html chart_line_opt.png + * + * The #lxw_image_options struct is the same struct used in + * `worksheet_insert_image_opt()` to position and scale images. + * + */ +int worksheet_insert_chart_opt(lxw_worksheet *worksheet, + lxw_row_t row, lxw_col_t col, + lxw_chart *chart, + lxw_image_options *user_options); /** * @brief Merge a range of cells.