c/libxlsxwriter
1
0
Fork 0
mirror of https://github.com/jmcnamara/libxlsxwriter synced 2025-03-28 21:13:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Additional chart docs.

Browse Source
This commit is contained in:
John McNamara 2016-05-23 22:42:27 +01:00
parent 722de1cd06
commit 11d26f7522
16 changed files with 138 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/Doxyfile
View File

@ -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 \

BIN
docs/images/chart_line_opt.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

1
docs/src/mainpage.dox
View File

@ -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

49
docs/src/working_with_charts.dox Normal file
View File

@ -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
*/

2
docs/src/working_with_dates.dox
View File

@ -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
*/

10
examples/chart_area.c
View File

@ -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. */

10
examples/chart_bar.c
View File

@ -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. */

10
examples/chart_column.c
View File

@ -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. */

2
examples/chart_doughnut.c
View File

@ -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. */

2
examples/chart_line.c
View File

@ -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

2
examples/chart_pie.c
View File

@ -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. */

10
examples/chart_radar.c
View File

@ -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. */

18
examples/chart_scatter.c
View File

@ -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. */

24
include/xlsxwriter/chart.h
View File

@ -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.
*
*
*/

2
include/xlsxwriter/workbook.h
View File

@ -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.

51
include/xlsxwriter/worksheet.h
View File

@ -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.