libxlsxwriter
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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);
}
chartsheet.png

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

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);
chartsheet2.png

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.
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);
chartsheet_activate.png

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.
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().

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.

hide_sheet.png

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().

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().

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().

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.

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().

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:

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:

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.

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);
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.

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().

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);
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

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