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);
    lxw_chart      *chart      = workbook_add_chart(workbook, LXW_CHART_BAR);
 
    //... 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.
void	chartsheet_activate (lxw_chartsheet *chartsheet)
	Make a chartsheet the active, i.e., visible chartsheet.
void	chartsheet_select (lxw_chartsheet *chartsheet)
	Set a chartsheet tab as selected.
void	chartsheet_hide (lxw_chartsheet *chartsheet)
	Hide the current chartsheet.
void	chartsheet_set_first_sheet (lxw_chartsheet *chartsheet)
	Set current chartsheet as the first visible sheet tab.
void	chartsheet_set_tab_color (lxw_chartsheet *chartsheet, lxw_color_t color)
	Set the color of the chartsheet tab.
void	chartsheet_protect (lxw_chartsheet *chartsheet, const char *password, lxw_protection *options)
	Protect elements of a chartsheet from modification.
void	chartsheet_set_zoom (lxw_chartsheet *chartsheet, uint16_t scale)
	Set the chartsheet zoom factor.
void	chartsheet_set_landscape (lxw_chartsheet *chartsheet)
	Set the page orientation as landscape.
void	chartsheet_set_portrait (lxw_chartsheet *chartsheet)
	Set the page orientation as portrait.
void	chartsheet_set_paper (lxw_chartsheet *chartsheet, uint8_t paper_type)
	Set the paper type for printing.
void	chartsheet_set_margins (lxw_chartsheet *chartsheet, double left, double right, double top, double bottom)
	Set the chartsheet margins for the printed page.
lxw_error	chartsheet_set_header (lxw_chartsheet *chartsheet, const char *string)
	Set the printed page header caption.
lxw_error	chartsheet_set_footer (lxw_chartsheet *chartsheet, const char *string)
	Set the printed page footer caption.
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_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.

Function Documentation

chartsheet_set_chart()

lxw_error chartsheet_set_chart	(	lxw_chartsheet *	chartsheet,
		lxw_chart *	chart
	)

Parameters

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
chart	A 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.
lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_LINE);
 
// 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

chartsheet

Pointer 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

chartsheet

Pointer 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

chartsheet

Pointer 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

chartsheet

Pointer 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

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
color	The tab color.

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

chartsheet_set_tab_color(chartsheet1, LXW_COLOR_RED);
chartsheet_set_tab_color(chartsheet2, LXW_COLOR_GREEN);
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

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
password	A chartsheet password.
options	Chartsheet 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

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
scale	Chartsheet 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

chartsheet

Pointer 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_landscape(chartsheet);

chartsheet_set_portrait()

void chartsheet_set_portrait

(

lxw_chartsheet *

chartsheet

)

Parameters

chartsheet

Pointer 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_portrait(chartsheet);

chartsheet_set_paper()

void chartsheet_set_paper	(	lxw_chartsheet *	chartsheet,
		uint8_t	paper_type
	)

Parameters

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
paper_type	The 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

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
left	Left margin in inches. Excel default is 0.7.
right	Right margin in inches. Excel default is 0.7.
top	Top margin in inches. Excel default is 0.75.
bottom	Bottom 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

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
string	The 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

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
string	The 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

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
string	The header string.
options	Header 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

chartsheet	Pointer to a lxw_chartsheet instance to be updated.
string	The footer string.
options	Footer options.

Returns

A lxw_error code.

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

Typedef Documentation

lxw_chartsheet

typedef struct lxw_chartsheet 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.