libxlsxwriter
Functions | Data Structures | Typedefs
chartsheet.h File Reference

Description

The Chartsheet object represents an Excel chartsheet. It handles operations such as adding a chart and setting the page layout.

A Chartsheet object isn't created directly. Instead a chartsheet is created by calling the workbook_add_chartsheet() function from a Workbook object. A chartsheet object functions as a worksheet and not as a chart. In order to have it display data a lxw_chart object must be created and added to the chartsheet:

#include "xlsxwriter.h"
int main() {
lxw_workbook *workbook = new_workbook("chartsheet.xlsx");
lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
lxw_chartsheet *chartsheet = workbook_add_chartsheet(workbook, NULL);
//... Set up the chart.
// Add the chart to the chartsheet.
return workbook_close(workbook);
}

The data for the chartsheet chart must be contained on a separate worksheet. That is why it is always created in conjunction with at least one data worksheet, as shown above.

Functions

lxw_error chartsheet_set_chart (lxw_chartsheet *chartsheet, lxw_chart *chart)
 Insert a chart object into a chartsheet. More...
 
void chartsheet_activate (lxw_chartsheet *chartsheet)
 Make a chartsheet the active, i.e., visible chartsheet. More...
 
void chartsheet_select (lxw_chartsheet *chartsheet)
 Set a chartsheet tab as selected. More...
 
void chartsheet_hide (lxw_chartsheet *chartsheet)
 Hide the current chartsheet. More...
 
void chartsheet_set_first_sheet (lxw_chartsheet *chartsheet)
 Set current chartsheet as the first visible sheet tab. More...
 
void chartsheet_set_tab_color (lxw_chartsheet *chartsheet, lxw_color_t color)
 Set the color of the chartsheet tab. More...
 
void chartsheet_protect (lxw_chartsheet *chartsheet, const char *password, lxw_protection *options)
 Protect elements of a chartsheet from modification. More...
 
void chartsheet_set_zoom (lxw_chartsheet *chartsheet, uint16_t scale)
 Set the chartsheet zoom factor. More...
 
void chartsheet_set_landscape (lxw_chartsheet *chartsheet)
 Set the page orientation as landscape. More...
 
void chartsheet_set_portrait (lxw_chartsheet *chartsheet)
 Set the page orientation as portrait. More...
 
void chartsheet_set_paper (lxw_chartsheet *chartsheet, uint8_t paper_type)
 Set the paper type for printing. More...
 
void chartsheet_set_margins (lxw_chartsheet *chartsheet, double left, double right, double top, double bottom)
 Set the chartsheet margins for the printed page. More...
 
lxw_error chartsheet_set_header (lxw_chartsheet *chartsheet, const char *string)
 Set the printed page header caption. More...
 
lxw_error chartsheet_set_footer (lxw_chartsheet *chartsheet, const char *string)
 Set the printed page footer caption. More...
 
lxw_error chartsheet_set_header_opt (lxw_chartsheet *chartsheet, const char *string, lxw_header_footer_options *options)
 Set the printed page header caption with additional options. More...
 
lxw_error chartsheet_set_footer_opt (lxw_chartsheet *chartsheet, const char *string, lxw_header_footer_options *options)
 Set the printed page footer caption with additional options. More...
 

Function Documentation

◆ chartsheet_set_chart()

lxw_error chartsheet_set_chart ( lxw_chartsheet chartsheet,
lxw_chart chart 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
chartA lxw_chart object created via workbook_add_chart().
Returns
A lxw_error code.

The chartsheet_set_chart() function can be used to insert a chart into a chartsheet. The chart object must be created first using the workbook_add_chart() function and configured using the chart.h functions.

// Create the chartsheet.
lxw_chartsheet *chartsheet = workbook_add_chartsheet(workbook, NULL);
// Create a chart object.
// Add a data series to the chart.
chart_add_series(chart, NULL, "=Sheet1!$A$1:$A$6");
// Insert the chart into the chartsheet.
chartsheet_set_chart(chartsheet, chart);

Note:

A chart may only be inserted once into a chartsheet or a worksheet. If several similar charts are required then each one must be created separately.

Examples
chartsheet.c.

◆ chartsheet_activate()

void chartsheet_activate ( lxw_chartsheet chartsheet)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.

The chartsheet_activate() function is used to specify which chartsheet is initially visible in a multi-sheet workbook:

lxw_worksheet *worksheet1 = workbook_add_worksheet(workbook, NULL);
lxw_chartsheet *chartsheet1 = workbook_add_chartsheet(workbook, NULL);
lxw_chartsheet *chartsheet2 = workbook_add_chartsheet(workbook, NULL);
lxw_chartsheet *chartsheet3 = workbook_add_chartsheet(workbook, NULL);
chartsheet_activate(chartsheet3);

More than one chartsheet can be selected via the chartsheet_select() function, see below, however only one chartsheet can be active.

The default active chartsheet is the first chartsheet.

See also worksheet_activate().

Examples
chartsheet.c.

◆ chartsheet_select()

void chartsheet_select ( lxw_chartsheet chartsheet)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.

The chartsheet_select() function is used to indicate that a chartsheet is selected in a multi-sheet workbook:

chartsheet_activate(chartsheet1);
chartsheet_select(chartsheet2);
chartsheet_select(chartsheet3);

A selected chartsheet has its tab highlighted. Selecting chartsheets is a way of grouping them together so that, for example, several chartsheets could be printed in one go. A chartsheet that has been activated via the chartsheet_activate() function will also appear as selected.

See also worksheet_select().

◆ chartsheet_hide()

void chartsheet_hide ( lxw_chartsheet chartsheet)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.

The chartsheet_hide() function is used to hide a chartsheet:

chartsheet_hide(chartsheet2);

You may wish to hide a chartsheet in order to avoid confusing a user with intermediate data or calculations.

A hidden chartsheet can not be activated or selected so this function is mutually exclusive with the chartsheet_activate() and chartsheet_select() functions. In addition, since the first chartsheet will default to being the active chartsheet, you cannot hide the first chartsheet without activating another sheet:

chartsheet_activate(chartsheet2);
chartsheet_hide(chartsheet1);

See also worksheet_hide().

◆ chartsheet_set_first_sheet()

void chartsheet_set_first_sheet ( lxw_chartsheet chartsheet)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.

The chartsheet_activate() function determines which chartsheet is initially selected. However, if there are a large number of chartsheets the selected chartsheet may not appear on the screen. To avoid this you can select the leftmost visible chartsheet tab using chartsheet_set_first_sheet():

chartsheet_set_first_sheet(chartsheet19); // First visible chartsheet tab.
chartsheet_activate(chartsheet20); // First visible chartsheet.

This function is not required very often. The default value is the first chartsheet.

See also worksheet_set_first_sheet().

◆ chartsheet_set_tab_color()

void chartsheet_set_tab_color ( lxw_chartsheet chartsheet,
lxw_color_t  color 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
colorThe tab color.

The chartsheet_set_tab_color() function is used to change the color of the chartsheet tab:

chartsheet_set_tab_color(chartsheet3, 0xFF9900); // Orange.

The color should be an RGB integer value, see Working with Colors.

See also worksheet_set_tab_color().

◆ chartsheet_protect()

void chartsheet_protect ( lxw_chartsheet chartsheet,
const char *  password,
lxw_protection options 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
passwordA chartsheet password.
optionsChartsheet elements to protect.

The chartsheet_protect() function protects chartsheet elements from modification:

chartsheet_protect(chartsheet, "Some Password", options);

The password and lxw_protection pointer are both optional:

chartsheet_protect(chartsheet2, NULL, my_options);
chartsheet_protect(chartsheet3, "password", NULL);
chartsheet_protect(chartsheet4, "password", my_options);

Passing a NULL password is the same as turning on protection without a password. Passing a NULL password and NULL options had no effect on chartsheets.

You can specify which chartsheet elements you wish to protect by passing a lxw_protection pointer in the options argument. In Excel chartsheets only have two protection options:

no_content
no_objects

All parameters are off by default. Individual elements can be protected as follows:

lxw_protection options = {
.no_content = 1,
.no_objects = 1,
};
chartsheet_protect(chartsheet, NULL, &options);

See also worksheet_protect().

Note: Sheet level passwords in Excel offer very weak protection. They don't encrypt your data and are very easy to deactivate. Full workbook encryption is not supported by libxlsxwriter since it requires a completely different file format.

◆ chartsheet_set_zoom()

void chartsheet_set_zoom ( lxw_chartsheet chartsheet,
uint16_t  scale 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
scaleChartsheet zoom factor.

Set the chartsheet zoom factor in the range 10 <= zoom <= 400:

chartsheet_set_zoom(chartsheet, 75);

The default zoom factor is 100. It isn't possible to set the zoom to "Selection" because it is calculated by Excel at run-time.

See also worksheet_set_zoom().

◆ chartsheet_set_landscape()

void chartsheet_set_landscape ( lxw_chartsheet chartsheet)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.

This function is used to set the orientation of a chartsheet's printed page to landscape. The default chartsheet orientation is landscape, so this function isn't generally required:

◆ chartsheet_set_portrait()

void chartsheet_set_portrait ( lxw_chartsheet chartsheet)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.

This function is used to set the orientation of a chartsheet's printed page to portrait:

◆ chartsheet_set_paper()

void chartsheet_set_paper ( lxw_chartsheet chartsheet,
uint8_t  paper_type 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
paper_typeThe Excel paper format type.

This function is used to set the paper format for the printed output of a chartsheet:

chartsheet_set_paper(chartsheet1, 1); // US Letter
chartsheet_set_paper(chartsheet2, 9); // A4

If you do not specify a paper type the chartsheet will print using the printer's default paper style.

See worksheet_set_paper() for a full list of available paper sizes.

◆ chartsheet_set_margins()

void chartsheet_set_margins ( lxw_chartsheet chartsheet,
double  left,
double  right,
double  top,
double  bottom 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
leftLeft margin in inches. Excel default is 0.7.
rightRight margin in inches. Excel default is 0.7.
topTop margin in inches. Excel default is 0.75.
bottomBottom margin in inches. Excel default is 0.75.

The chartsheet_set_margins() function is used to set the margins of the chartsheet when it is printed. The units are in inches. Specifying -1 for any parameter will give the default Excel value as shown above.

chartsheet_set_margins(chartsheet, 1.3, 1.2, -1, -1);

◆ chartsheet_set_header()

lxw_error chartsheet_set_header ( lxw_chartsheet chartsheet,
const char *  string 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
stringThe header string.
Returns
A lxw_error code.

Headers and footers are generated using a string which is a combination of plain text and control characters

chartsheet_set_header(chartsheet, "&LHello");
// ---------------------------------------------------------------
// | |
// | Hello |
// | |
chartsheet_set_header(chartsheet, "&CHello");
// ---------------------------------------------------------------
// | |
// | Hello |
// | |
chartsheet_set_header(chartsheet, "&RHello");
// ---------------------------------------------------------------
// | |
// | Hello |
// | |

See worksheet_set_header() for a full explanation of the syntax of Excel's header formatting and control characters.

◆ chartsheet_set_footer()

lxw_error chartsheet_set_footer ( lxw_chartsheet chartsheet,
const char *  string 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
stringThe footer string.
Returns
A lxw_error code.

The syntax of this function is the same as chartsheet_set_header().

◆ chartsheet_set_header_opt()

lxw_error chartsheet_set_header_opt ( lxw_chartsheet chartsheet,
const char *  string,
lxw_header_footer_options options 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
stringThe header string.
optionsHeader options.
Returns
A lxw_error code.

The syntax of this function is the same as chartsheet_set_header() with an additional parameter to specify options for the header.

Currently, the only available option is the header margin:

lxw_header_footer_options header_options = { 0.2 };
chartsheet_set_header_opt(chartsheet, "Some text", &header_options);

◆ chartsheet_set_footer_opt()

lxw_error chartsheet_set_footer_opt ( lxw_chartsheet chartsheet,
const char *  string,
lxw_header_footer_options options 
)
Parameters
chartsheetPointer to a lxw_chartsheet instance to be updated.
stringThe footer string.
optionsFooter options.
Returns
A lxw_error code.

The syntax of this function is the same as chartsheet_set_header_opt().

Typedef Documentation

◆ lxw_chartsheet

The members of the lxw_chartsheet struct aren't modified directly. Instead the chartsheet properties are set by calling the functions shown in chartsheet.h.

Data Structures

struct  lxw_chartsheet
 Struct to represent an Excel chartsheet. More...
 

Typedefs

typedef struct lxw_chartsheet lxw_chartsheet
 Struct to represent an Excel chartsheet. More...
 
workbook_add_chartsheet
lxw_chartsheet * workbook_add_chartsheet(lxw_workbook *workbook, const char *sheetname)
Add a new chartsheet to a workbook.
workbook_close
lxw_error workbook_close(lxw_workbook *workbook)
Close the Workbook object and write the XLSX file.
chartsheet_set_margins
void chartsheet_set_margins(lxw_chartsheet *chartsheet, double left, double right, double top, double bottom)
Set the chartsheet margins for the printed page.
chartsheet_activate
void chartsheet_activate(lxw_chartsheet *chartsheet)
Make a chartsheet the active, i.e., visible chartsheet.
lxw_protection
Worksheet protection options.
Definition: worksheet.h:2003
chartsheet_set_paper
void chartsheet_set_paper(lxw_chartsheet *chartsheet, uint8_t paper_type)
Set the paper type for printing.
chart_add_series
lxw_chart_series * chart_add_series(lxw_chart *chart, const char *categories, const char *values)
Add a data series to a chart.
chartsheet_set_zoom
void chartsheet_set_zoom(lxw_chartsheet *chartsheet, uint16_t scale)
Set the chartsheet zoom factor.
chartsheet_set_tab_color
void chartsheet_set_tab_color(lxw_chartsheet *chartsheet, lxw_color_t color)
Set the color of the chartsheet tab.
lxw_protection::no_content
uint8_t no_content
Definition: worksheet.h:2050
chartsheet_select
void chartsheet_select(lxw_chartsheet *chartsheet)
Set a chartsheet tab as selected.
LXW_CHART_BAR
@ LXW_CHART_BAR
Definition: chart.h:104
LXW_CHART_LINE
@ LXW_CHART_LINE
Definition: chart.h:125
lxw_worksheet
Struct to represent an Excel worksheet.
Definition: worksheet.h:2107
chartsheet_set_first_sheet
void chartsheet_set_first_sheet(lxw_chartsheet *chartsheet)
Set current chartsheet as the first visible sheet tab.
chartsheet_set_header_opt
lxw_error chartsheet_set_header_opt(lxw_chartsheet *chartsheet, const char *string, lxw_header_footer_options *options)
Set the printed page header caption with additional options.
lxw_chartsheet
Struct to represent an Excel chartsheet.
Definition: chartsheet.h:74
lxw_chart
Struct to represent an Excel chart.
Definition: chart.h:1090
chartsheet_set_landscape
void chartsheet_set_landscape(lxw_chartsheet *chartsheet)
Set the page orientation as landscape.
LXW_COLOR_GREEN
@ LXW_COLOR_GREEN
Definition: format.h:196
chartsheet_hide
void chartsheet_hide(lxw_chartsheet *chartsheet)
Hide the current chartsheet.
lxw_workbook
Struct to represent an Excel workbook.
Definition: workbook.h:292
chartsheet_set_chart
lxw_error chartsheet_set_chart(lxw_chartsheet *chartsheet, lxw_chart *chart)
Insert a chart object into a chartsheet.
LXW_COLOR_RED
@ LXW_COLOR_RED
Definition: format.h:217
chartsheet_set_portrait
void chartsheet_set_portrait(lxw_chartsheet *chartsheet)
Set the page orientation as portrait.
chartsheet_set_header
lxw_error chartsheet_set_header(lxw_chartsheet *chartsheet, const char *string)
Set the printed page header caption.
workbook_add_worksheet
lxw_worksheet * workbook_add_worksheet(lxw_workbook *workbook, const char *sheetname)
Add a new worksheet to a workbook.
workbook_add_chart
lxw_chart * workbook_add_chart(lxw_workbook *workbook, uint8_t chart_type)
Create a new chart to be added to a worksheet:
chartsheet_protect
void chartsheet_protect(lxw_chartsheet *chartsheet, const char *password, lxw_protection *options)
Protect elements of a chartsheet from modification.