workbook.h File Reference

Description

The Workbook is the main object exposed by the libxlsxwriter library. It represents the entire spreadsheet as you see it in Excel and internally it represents the Excel file as it is written on disk.

#include "xlsxwriter.h"
 
int main() {
 
    lxw_workbook  *workbook  = workbook_new("filename.xlsx");
    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
 
    worksheet_write_string(worksheet, 0, 0, "Hello Excel", NULL);
 
    return workbook_close(workbook);
}

Functions
lxw_workbook *	workbook_new (const char *filename)
	Create a new workbook object.
lxw_workbook *	workbook_new_opt (const char *filename, lxw_workbook_options *options)
	Create a new workbook object, and set the workbook options.
lxw_worksheet *	workbook_add_worksheet (lxw_workbook *workbook, const char *sheetname)
	Add a new worksheet to a workbook.
lxw_chartsheet *	workbook_add_chartsheet (lxw_workbook *workbook, const char *sheetname)
	Add a new chartsheet to a workbook.
lxw_format *	workbook_add_format (lxw_workbook *workbook)
	Create a new Format object to formats cells in worksheets.
lxw_chart *	workbook_add_chart (lxw_workbook *workbook, uint8_t chart_type)
	Create a new chart to be added to a worksheet:
lxw_error	workbook_close (lxw_workbook *workbook)
	Close the Workbook object and write the XLSX file.
lxw_error	workbook_set_properties (lxw_workbook *workbook, lxw_doc_properties *properties)
	Set the document properties such as Title, Author etc.
lxw_error	workbook_set_custom_property_string (lxw_workbook *workbook, const char *name, const char *value)
	Set a custom document text property.
lxw_error	workbook_set_custom_property_number (lxw_workbook *workbook, const char *name, double value)
	Set a custom document number property.
lxw_error	workbook_set_custom_property_boolean (lxw_workbook *workbook, const char *name, uint8_t value)
	Set a custom document boolean property.
lxw_error	workbook_set_custom_property_datetime (lxw_workbook *workbook, const char *name, lxw_datetime *datetime)
	Set a custom document date or time property.
lxw_error	workbook_define_name (lxw_workbook *workbook, const char *name, const char *formula)
	Create a defined name in the workbook to use as a variable.
lxw_format *	workbook_get_default_url_format (lxw_workbook *workbook)
	Get the default URL format used with worksheet_write_url().
lxw_worksheet *	workbook_get_worksheet_by_name (lxw_workbook *workbook, const char *name)
	Get a worksheet object from its name.
lxw_chartsheet *	workbook_get_chartsheet_by_name (lxw_workbook *workbook, const char *name)
	Get a chartsheet object from its name.
lxw_error	workbook_validate_sheet_name (lxw_workbook *workbook, const char *sheetname)
	Validate a worksheet or chartsheet name.
lxw_error	workbook_add_vba_project (lxw_workbook *workbook, const char *filename)
	Add a vbaProject binary to the Excel workbook.
lxw_error	workbook_add_signed_vba_project (lxw_workbook *workbook, const char *vba_project, const char *signature)
	Add a vbaProject binary and a vbaProjectSignature binary to the Excel workbook.
lxw_error	workbook_set_vba_name (lxw_workbook *workbook, const char *name)
	Set the VBA name for the workbook.
void	workbook_read_only_recommended (lxw_workbook *workbook)
	Add a recommendation to open the file in "read-only" mode.

Function Documentation

workbook_new()

lxw_workbook * workbook_new

(

const char *

filename

)

Parameters

filename

The name of the new Excel file to create.

Returns

A lxw_workbook instance.

The workbook_new() constructor is used to create a new Excel workbook with a given filename:

lxw_workbook *workbook  = workbook_new("filename.xlsx");

When specifying a filename it is recommended that you use an .xlsx extension or Excel will generate a warning when opening the file.

Examples

anatomy.c, array_formula.c, autofilter.c, background.c, chart.c, chart_area.c, chart_bar.c, chart_clustered.c, chart_column.c, chart_data_labels.c, chart_data_table.c, chart_data_tools.c, chart_doughnut.c, chart_fonts.c, chart_line.c, chart_pattern.c, chart_pie.c, chart_radar.c, chart_scatter.c, chart_styles.c, chartsheet.c, comments1.c, comments2.c, conditional_format1.c, conditional_format2.c, data_validate.c, dates_and_times01.c, dates_and_times02.c, dates_and_times03.c, dates_and_times04.c, defined_name.c, demo.c, diagonal_border.c, doc_custom_properties.c, doc_properties.c, dynamic_arrays.c, format_font.c, format_num_format.c, headers_footers.c, hello.c, hide_row_col.c, hide_sheet.c, hyperlinks.c, ignore_errors.c, image_buffer.c, images.c, lambda.c, macro.c, merge_range.c, merge_rich_string.c, outline.c, outline_collapsed.c, panes.c, rich_strings.c, tab_colors.c, tables.c, tutorial1.c, tutorial2.c, tutorial3.c, utf8.c, watermark.c, and worksheet_protection.c.

workbook_new_opt()

lxw_workbook * workbook_new_opt	(	const char *	filename,
		lxw_workbook_options *	options
	)

Parameters

filename	The name of the new Excel file to create.
options	Workbook options.

Returns

A lxw_workbook instance.

This function is the same as the workbook_new() constructor but allows additional options to be set.

lxw_workbook_options options = {.constant_memory = LXW_TRUE,
                                .tmpdir = "C:\\Temp",
                                .use_zip64 = LXW_FALSE,
                                .output_buffer = NULL,
                                .output_buffer_size = NULL};
 
lxw_workbook  *workbook  = workbook_new_opt("filename.xlsx", &options);

The options that can be set via lxw_workbook_options are:

• constant_memory: This option reduces the amount of data stored in memory so that large files can be written efficiently. This option is off by default. See the note below for limitations when this mode is on.
• tmpdir: libxlsxwriter stores workbook data in temporary files prior to assembling the final XLSX file. The temporary files are created in the system's temp directory. If the default temporary directory isn't accessible to your application, or doesn't contain enough space, you can specify an alternative location using the tmpdir option.
• use_zip64: Make the zip library use ZIP64 extensions when writing very large xlsx files to allow the zip container, or individual XML files within it, to be greater than 4 GB. See ZIP64 on Wikipedia for more information. This option is off by default.
• output_buffer: Output to a memory buffer instead of a file. The buffer must be freed manually by calling free(). This option can only be used if filename is NULL.
• output_buffer_size: Used with output_buffer to get the size of the created buffer. This option can only be used if filename is NULL.

Note

In constant_memory mode each row of in-memory data is written to disk and then freed when a new row is started via one of the worksheet_write_*() functions. Therefore, once this option is active data should be written in sequential row by row order. For this reason worksheet_merge_range() and some other row based functionality doesn't work in this mode. See Constant Memory Mode for more details.

Also, in constant_memory mode the library uses temp file storage for worksheet data. This can lead to an issue on OSes that map the /tmp directory into memory since it is possible to consume the "system" memory even though the "process" memory remains constant. In these cases you should use an alternative temp file location by using the tmpdir option shown above. See Constant memory mode and the /tmp directory for more details.

Examples

constant_memory.c, and output_buffer.c.

workbook_add_worksheet()

lxw_worksheet * workbook_add_worksheet	(	lxw_workbook *	workbook,
		const char *	sheetname
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
sheetname	Optional worksheet name, defaults to Sheet1, etc.

Returns

A lxw_worksheet object.

The workbook_add_worksheet() function adds a new worksheet to a workbook.

At least one worksheet should be added to a new workbook: The Worksheet object is used to write data and configure a worksheet in the workbook.

The sheetname parameter is optional. If it is NULL the default Excel convention will be followed, i.e. Sheet1, Sheet2, etc.:

worksheet = workbook_add_worksheet(workbook, NULL  );     // Sheet1
worksheet = workbook_add_worksheet(workbook, "Foglio2");  // Foglio2
worksheet = workbook_add_worksheet(workbook, "Data");     // Data
worksheet = workbook_add_worksheet(workbook, NULL  );     // Sheet4

The worksheet name must be a valid Excel worksheet name, i.e:

• The name is less than or equal to 31 UTF-8 characters.
• The name doesn't contain any of the characters: [ ] : * ? / \
• The name doesn't start or end with an apostrophe.
• The name isn't already in use. (Case insensitive).

If any of these errors are encountered the function will return NULL. You can check for valid name using the workbook_validate_sheet_name() function.

Note

You should also avoid using the worksheet name "History" (case insensitive) which is reserved in English language versions of Excel. Non-English versions may have restrictions on the equivalent word.

Examples

anatomy.c, array_formula.c, autofilter.c, background.c, chart.c, chart_area.c, chart_bar.c, chart_clustered.c, chart_column.c, chart_data_labels.c, chart_data_table.c, chart_data_tools.c, chart_doughnut.c, chart_fonts.c, chart_line.c, chart_pattern.c, chart_pie.c, chart_radar.c, chart_scatter.c, chart_styles.c, chartsheet.c, comments1.c, comments2.c, conditional_format1.c, conditional_format2.c, constant_memory.c, data_validate.c, dates_and_times01.c, dates_and_times02.c, dates_and_times03.c, dates_and_times04.c, defined_name.c, demo.c, diagonal_border.c, doc_custom_properties.c, doc_properties.c, dynamic_arrays.c, format_font.c, format_num_format.c, headers_footers.c, hello.c, hide_row_col.c, hide_sheet.c, hyperlinks.c, ignore_errors.c, image_buffer.c, images.c, lambda.c, macro.c, merge_range.c, merge_rich_string.c, outline.c, outline_collapsed.c, output_buffer.c, panes.c, rich_strings.c, tab_colors.c, tables.c, tutorial1.c, tutorial2.c, tutorial3.c, utf8.c, watermark.c, and worksheet_protection.c.

workbook_add_chartsheet()

lxw_chartsheet * workbook_add_chartsheet	(	lxw_workbook *	workbook,
		const char *	sheetname
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
sheetname	Optional chartsheet name, defaults to Chart1, etc.

Returns

A lxw_chartsheet object.

The workbook_add_chartsheet() function adds a new chartsheet to a workbook. The Chartsheet object is like a worksheet except it displays a chart instead of cell data.

The sheetname parameter is optional. If it is NULL the default Excel convention will be followed, i.e. Chart1, Chart2, etc.:

chartsheet = workbook_add_chartsheet(workbook, NULL  );     // Chart1
chartsheet = workbook_add_chartsheet(workbook, "My Chart"); // My Chart
chartsheet = workbook_add_chartsheet(workbook, NULL  );     // Chart3

The chartsheet name must be a valid Excel worksheet name, i.e.:

• The name is less than or equal to 31 UTF-8 characters.
• The name doesn't contain any of the characters: [ ] : * ? / \
• The name doesn't start or end with an apostrophe.
• The name isn't already in use. (Case insensitive).

If any of these errors are encountered the function will return NULL. You can check for valid name using the workbook_validate_sheet_name() function.

Note

You should also avoid using the worksheet name "History" (case insensitive) which is reserved in English language versions of Excel. Non-English versions may have restrictions on the equivalent word.

At least one worksheet should be added to a new workbook when creating a chartsheet in order to provide data for the chart. The Worksheet object is used to write data and configure a worksheet in the workbook.

Examples

chartsheet.c.

workbook_add_format()

lxw_format * workbook_add_format

(

lxw_workbook *

workbook

)

Parameters

workbook

Pointer to a lxw_workbook instance.

Returns

A lxw_format instance.

The workbook_add_format() function can be used to create new Format objects which are used to apply formatting to a cell.

// Create the Format.
lxw_format *format = workbook_add_format(workbook);
 
// Set some of the format properties.
format_set_bold(format);
format_set_font_color(format, LXW_COLOR_RED);
 
// Use the format to change the text format in a cell.
worksheet_write_string(worksheet, 0, 0, "Hello", format);

See the Format object and Working with Formats sections for more details about Format properties and how to set them.

Examples

anatomy.c, autofilter.c, chart_area.c, chart_bar.c, chart_clustered.c, chart_column.c, chart_data_labels.c, chart_data_table.c, chart_data_tools.c, chart_doughnut.c, chart_line.c, chart_pattern.c, chart_pie.c, chart_radar.c, chart_scatter.c, chartsheet.c, comments2.c, conditional_format1.c, conditional_format2.c, data_validate.c, dates_and_times01.c, dates_and_times02.c, dates_and_times03.c, dates_and_times04.c, demo.c, diagonal_border.c, dynamic_arrays.c, format_font.c, format_num_format.c, hyperlinks.c, merge_range.c, merge_rich_string.c, outline.c, outline_collapsed.c, panes.c, rich_strings.c, tables.c, tutorial2.c, tutorial3.c, and worksheet_protection.c.

workbook_add_chart()

lxw_chart * workbook_add_chart	(	lxw_workbook *	workbook,
		uint8_t	chart_type
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
chart_type	The type of chart to be created. See lxw_chart_type.

Returns

A lxw_chart object.

The workbook_add_chart() function creates a new chart object that can be added to a worksheet:

// Create a chart object.
lxw_chart *chart = workbook_add_chart(workbook, LXW_CHART_COLUMN);
 
// Add data series to the chart.
chart_add_series(chart, NULL, "Sheet1!$A$1:$A$5");
chart_add_series(chart, NULL, "Sheet1!$B$1:$B$5");
chart_add_series(chart, NULL, "Sheet1!$C$1:$C$5");
 
// Insert the chart into the worksheet
worksheet_insert_chart(worksheet, CELL("B7"), chart);

The available chart types are defined in lxw_chart_type. The types of charts that are supported are:

Chart type	Description
LXW_CHART_AREA	Area chart.
LXW_CHART_AREA_STACKED	Area chart - stacked.
LXW_CHART_AREA_STACKED_PERCENT	Area chart - percentage stacked.
LXW_CHART_BAR	Bar chart.
LXW_CHART_BAR_STACKED	Bar chart - stacked.
LXW_CHART_BAR_STACKED_PERCENT	Bar chart - percentage stacked.
LXW_CHART_COLUMN	Column chart.
LXW_CHART_COLUMN_STACKED	Column chart - stacked.
LXW_CHART_COLUMN_STACKED_PERCENT	Column chart - percentage stacked.
LXW_CHART_DOUGHNUT	Doughnut chart.
LXW_CHART_LINE	Line chart.
LXW_CHART_LINE_STACKED	Line chart - stacked.
LXW_CHART_LINE_STACKED_PERCENT	Line chart - percentage stacked.
LXW_CHART_PIE	Pie chart.
LXW_CHART_SCATTER	Scatter chart.
LXW_CHART_SCATTER_STRAIGHT	Scatter chart - straight.
LXW_CHART_SCATTER_STRAIGHT_WITH_MARKERS	Scatter chart - straight with markers.
LXW_CHART_SCATTER_SMOOTH	Scatter chart - smooth.
LXW_CHART_SCATTER_SMOOTH_WITH_MARKERS	Scatter chart - smooth with markers.
LXW_CHART_RADAR	Radar chart.
LXW_CHART_RADAR_WITH_MARKERS	Radar chart - with markers.
LXW_CHART_RADAR_FILLED	Radar chart - filled.

See chart.h for details.

Examples

chart.c, chart_area.c, chart_bar.c, chart_clustered.c, chart_column.c, chart_data_labels.c, chart_data_table.c, chart_data_tools.c, chart_doughnut.c, chart_fonts.c, chart_line.c, chart_pattern.c, chart_pie.c, chart_radar.c, chart_scatter.c, chart_styles.c, and chartsheet.c.

workbook_close()

lxw_error workbook_close

(

lxw_workbook *

workbook

)

Parameters

workbook

Pointer to a lxw_workbook instance.

Returns

A lxw_error.

The workbook_close() function closes a Workbook object, writes the Excel file to disk, frees any memory allocated internally to the Workbook and frees the object itself.

workbook_close(workbook);

The workbook_close() function returns any lxw_error error codes encountered when creating the Excel file. The error code can be returned from the program main or the calling function:

return workbook_close(workbook);

Examples

anatomy.c, array_formula.c, autofilter.c, background.c, chart.c, chart_area.c, chart_bar.c, chart_clustered.c, chart_column.c, chart_data_labels.c, chart_data_table.c, chart_data_tools.c, chart_doughnut.c, chart_fonts.c, chart_line.c, chart_pattern.c, chart_pie.c, chart_radar.c, chart_scatter.c, chart_styles.c, chartsheet.c, comments1.c, comments2.c, conditional_format1.c, conditional_format2.c, constant_memory.c, data_validate.c, dates_and_times01.c, dates_and_times02.c, dates_and_times03.c, dates_and_times04.c, defined_name.c, demo.c, diagonal_border.c, doc_custom_properties.c, doc_properties.c, dynamic_arrays.c, format_font.c, format_num_format.c, headers_footers.c, hello.c, hide_row_col.c, hide_sheet.c, hyperlinks.c, ignore_errors.c, image_buffer.c, images.c, lambda.c, macro.c, merge_range.c, merge_rich_string.c, outline.c, outline_collapsed.c, output_buffer.c, panes.c, rich_strings.c, tab_colors.c, tables.c, tutorial1.c, tutorial2.c, tutorial3.c, utf8.c, watermark.c, and worksheet_protection.c.

workbook_set_properties()

lxw_error workbook_set_properties	(	lxw_workbook *	workbook,
		lxw_doc_properties *	properties
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
properties	Document properties to set.

Returns

A lxw_error.

The workbook_set_properties function can be used to set the document properties of the Excel file created by libxlsxwriter. These properties are visible when you use the Office Button -> Prepare -> Properties option in Excel and are also available to external applications that read or index windows files.

The properties that can be set are:

• title
• subject
• author
• manager
• company
• category
• keywords
• comments
• hyperlink_base
• created

The properties are specified via a lxw_doc_properties struct. All the fields are all optional. An example of how to create and pass the properties is:

// Create a properties structure and set some of the fields.
lxw_doc_properties properties = {
    .title    = "This is an example spreadsheet",
    .subject  = "With document properties",
    .author   = "John McNamara",
    .manager  = "Dr. Heinz Doofenshmirtz",
    .company  = "of Wolves",
    .category = "Example spreadsheets",
    .keywords = "Sample, Example, Properties",
    .comments = "Created with libxlsxwriter",
    .status   = "Quo",
};
 
// Set the properties in the workbook.
workbook_set_properties(workbook, &properties);

The created parameter sets the file creation date/time shown in Excel. This defaults to the current time and date if set to 0. If you wish to create files that are binary equivalent (for the same input data) then you should set this creation date/time to a known value using a time_t value.

Examples

doc_properties.c.

workbook_set_custom_property_string()

lxw_error workbook_set_custom_property_string	(	lxw_workbook *	workbook,
		const char *	name,
		const char *	value
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
name	The name of the custom property.
value	The value of the custom property.

Returns

A lxw_error.

The workbook_set_custom_property_string() function can be used to set one or more custom document text properties not covered by the standard properties in the workbook_set_properties() function above.

For example:

workbook_set_custom_property_string(workbook, "Checked by", "Eve");

There are 4 workbook_set_custom_property_string_*() functions for each of the custom property types supported by Excel:

• text/string: workbook_set_custom_property_string()
• number: workbook_set_custom_property_number()
• datetime: workbook_set_custom_property_datetime()
• boolean: workbook_set_custom_property_boolean()

Note: the name and value parameters are limited to 255 characters by Excel.

Examples

doc_custom_properties.c.

workbook_set_custom_property_number()

lxw_error workbook_set_custom_property_number	(	lxw_workbook *	workbook,
		const char *	name,
		double	value
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
name	The name of the custom property.
value	The value of the custom property.

Returns

A lxw_error.

Set a custom document number property. See workbook_set_custom_property_string() above for details.

workbook_set_custom_property_number(workbook, "Document number", 12345);

Examples

doc_custom_properties.c.

workbook_set_custom_property_boolean()

lxw_error workbook_set_custom_property_boolean	(	lxw_workbook *	workbook,
		const char *	name,
		uint8_t	value
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
name	The name of the custom property.
value	The value of the custom property.

Returns

A lxw_error.

Set a custom document boolean property. See workbook_set_custom_property_string() above for details.

workbook_set_custom_property_boolean(workbook, "Has Review", 1);

Examples

doc_custom_properties.c.

workbook_set_custom_property_datetime()

lxw_error workbook_set_custom_property_datetime	(	lxw_workbook *	workbook,
		const char *	name,
		lxw_datetime *	datetime
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
name	The name of the custom property.
datetime	The value of the custom property.

Returns

A lxw_error.

Set a custom date or time number property. See workbook_set_custom_property_string() above for details.

lxw_datetime datetime  = {2016, 12, 1,  11, 55, 0.0};
 
workbook_set_custom_property_datetime(workbook, "Date completed", &datetime);

Examples

doc_custom_properties.c.

workbook_define_name()

lxw_error workbook_define_name	(	lxw_workbook *	workbook,
		const char *	name,
		const char *	formula
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
name	The defined name.
formula	The cell or range that the defined name refers to.

Returns

A lxw_error.

This function is used to defined a name that can be used to represent a value, a single cell or a range of cells in a workbook: These defined names can then be used in formulas:

workbook_define_name(workbook, "Exchange_rate", "=0.96");
worksheet_write_formula(worksheet, 2, 1, "=Exchange_rate", NULL);

As in Excel a name defined like this is "global" to the workbook and can be referred to from any worksheet:

// Global workbook name.
workbook_define_name(workbook, "Sales", "=Sheet1!$G$1:$H$10");

It is also possible to define a local/worksheet name by prefixing it with the sheet name using the syntax ‘'sheetname!definedname’`:

// Local worksheet name.
workbook_define_name(workbook, "Sheet2!Sales", "=Sheet2!$G$1:$G$10");

If the sheet name contains spaces or special characters you must follow the Excel convention and enclose it in single quotes:

workbook_define_name(workbook, "'New Data'!Sales", "=Sheet2!$G$1:$G$10");

The rules for names in Excel are explained in the Microsoft Office documentation.

Examples

defined_name.c, and lambda.c.

workbook_get_default_url_format()

lxw_format * workbook_get_default_url_format

(

lxw_workbook *

workbook

)

Parameters

workbook

Pointer to a lxw_workbook instance.

Returns

A lxw_format instance that has hyperlink properties set.

This function returns a lxw_format instance that is used for the default blue underline hyperlink in the worksheet_write_url() function when a format isn't specified:

lxw_format *url_format = workbook_get_default_url_format(workbook);

The format is the hyperlink style defined by Excel for the default theme. This format is only ever required when overwriting a string URL with data of a different type. See the example below.

Examples

hyperlinks.c.

workbook_get_worksheet_by_name()

lxw_worksheet * workbook_get_worksheet_by_name	(	lxw_workbook *	workbook,
		const char *	name
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
name	Worksheet name.

Returns

A lxw_worksheet object.

This function returns a lxw_worksheet object reference based on its name:

worksheet = workbook_get_worksheet_by_name(workbook, "Sheet1");

workbook_get_chartsheet_by_name()

lxw_chartsheet * workbook_get_chartsheet_by_name	(	lxw_workbook *	workbook,
		const char *	name
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
name	chartsheet name.

Returns

A lxw_chartsheet object.

This function returns a lxw_chartsheet object reference based on its name:

chartsheet = workbook_get_chartsheet_by_name(workbook, "Chart1");

workbook_validate_sheet_name()

lxw_error workbook_validate_sheet_name	(	lxw_workbook *	workbook,
		const char *	sheetname
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
sheetname	Sheet name to validate.

Returns

A lxw_error.

This function is used to validate a worksheet or chartsheet name according to the rules used by Excel:

• The name is less than or equal to 31 UTF-8 characters.
• The name doesn't contain any of the characters: [ ] : * ? / \
• The name doesn't start or end with an apostrophe.
• The name isn't already in use. (Case insensitive, see the note below).

lxw_error err = workbook_validate_sheet_name(workbook, "Foglio");

This function is called by workbook_add_worksheet() and workbook_add_chartsheet() but it can be explicitly called by the user beforehand to ensure that the sheet name is valid.

Note

You should also avoid using the worksheet name "History" (case insensitive) which is reserved in English language versions of Excel. Non-English versions may have restrictions on the equivalent word.

This function does an ASCII lowercase string comparison to determine if the sheet name is already in use. It doesn't take UTF-8 characters into account. Thus it would flag "Café" and "café" as a duplicate (just like Excel) but it wouldn't catch "CAFÉ". If you need a full UTF-8 case insensitive check you should use a third party library to implement it.

workbook_add_vba_project()

lxw_error workbook_add_vba_project	(	lxw_workbook *	workbook,
		const char *	filename
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
filename	The path/filename of the vbaProject.bin file.

The workbook_add_vba_project() function can be used to add macros or functions to a workbook using a binary VBA project file that has been extracted from an existing Excel xlsm file:

workbook_add_vba_project(workbook, "vbaProject.bin");

Only one vbaProject.bin file can be added per workbook. The name doesn't have to be vbaProject.bin. Any suitable path/name for an existing VBA bin file will do.

Once you add a VBA project had been add to an libxlsxwriter workbook you should ensure that the file extension is .xlsm to prevent Excel from giving a warning when it opens the file:

lxw_workbook *workbook = new_workbook("macro.xlsm");

See also Working with VBA Macros

Returns

A lxw_error.

Examples

macro.c.

workbook_add_signed_vba_project()

lxw_error workbook_add_signed_vba_project	(	lxw_workbook *	workbook,
		const char *	vba_project,
		const char *	signature
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
vba_project	The path/filename of the vbaProject.bin file.
signature	The path/filename of the vbaProjectSignature.bin file.

The workbook_add_signed_vba_project() function can be used to add digitally signed macros or functions to a workbook. The function adds a binary VBA project file and a binary VBA project signature file that have been extracted from an existing Excel xlsm file with digitally signed macros:

workbook_add_signed_vba_project(workbook, "vbaProject.bin", "vbaProjectSignature.bin");

Only one vbaProject.bin file can be added per workbook. The name doesn't have to be vbaProject.bin. Any suitable path/name for an existing VBA bin file will do. The same applies for vbaProjectSignature.bin.

See also Working with VBA Macros

Returns

A lxw_error.

workbook_set_vba_name()

lxw_error workbook_set_vba_name	(	lxw_workbook *	workbook,
		const char *	name
	)

Parameters

workbook	Pointer to a lxw_workbook instance.
name	Name of the workbook used by VBA.

The workbook_set_vba_name() function can be used to set the VBA name for the workbook. This is sometimes required when a vbaProject macro included via workbook_add_vba_project() refers to the workbook by a name other than ThisWorkbook.

workbook_set_vba_name(workbook, "MyWorkbook");

If an Excel VBA name for the workbook isn't specified then libxlsxwriter will use ThisWorkbook.

See also Working with VBA Macros

Returns

A lxw_error.

workbook_read_only_recommended()

void workbook_read_only_recommended

(

lxw_workbook *

workbook

)

Parameters

workbook

Pointer to a lxw_workbook instance.

This function can be used to set the Excel "Read-only Recommended" option that is available when saving a file. This presents the user of the file with an option to open it in "read-only" mode. This means that any changes to the file can't be saved back to the same file and must be saved to a new file. It can be set as follows:

workbook_read_only_recommended(workbook);

Which will raise a dialog like the following when opening the file:

Typedef Documentation

lxw_doc_properties

typedef struct lxw_doc_properties lxw_doc_properties

Workbook document properties. Set any unused fields to NULL or 0.

lxw_workbook_options

typedef struct lxw_workbook_options lxw_workbook_options

Optional parameters when creating a new Workbook object via workbook_new_opt().

The following properties are supported:

• constant_memory: This option reduces the amount of data stored in memory so that large files can be written efficiently. This option is off by default. See the notes below for limitations when this mode is on.
• tmpdir: libxlsxwriter stores workbook data in temporary files prior to assembling the final XLSX file. The temporary files are created in the system's temp directory. If the default temporary directory isn't accessible to your application, or doesn't contain enough space, you can specify an alternative location using the tmpdir option.
• use_zip64: Make the zip library use ZIP64 extensions when writing very large xlsx files to allow the zip container, or individual XML files within it, to be greater than 4 GB. See ZIP64 on Wikipedia for more information. This option is off by default.
• output_buffer: Output to a buffer instead of a file. The buffer must be freed manually by calling free(). This option can only be used if filename is NULL.
• output_buffer_size: Used with output_buffer to get the size of the created buffer. This option can only be used if filename is NULL.

Note

In constant_memory mode each row of in-memory data is written to disk and then freed when a new row is started via one of the worksheet_write_*() functions. Therefore, once this option is active data should be written in sequential row by row order. For this reason worksheet_merge_range() and some other row based functionality doesn't work in this mode. See Constant Memory Mode for more details.

Also, in constant_memory mode the library uses temp file storage for worksheet data. This can lead to an issue on OSes that map the /tmp directory into memory since it is possible to consume the "system" memory even though the "process" memory remains constant. In these cases you should use an alternative temp file location by using the tmpdir option shown above. See Constant memory mode and the /tmp directory for more details.

lxw_workbook

typedef struct lxw_workbook lxw_workbook

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

Macro Definition Documentation

LXW_FOREACH_WORKSHEET

#define LXW_FOREACH_WORKSHEET	(		worksheet,
			workbook
	)		STAILQ_FOREACH((worksheet), (workbook)->worksheets, list_pointers)

This macro allows you to loop over all the worksheets that have been added to a workbook. You must provide a lxw_worksheet pointer and a pointer to the lxw_workbook:

lxw_workbook  *workbook = workbook_new("test.xlsx");
 
lxw_worksheet *worksheet; // Generic worksheet pointer.
 
// Worksheet objects used in the program.
lxw_worksheet *worksheet1 = workbook_add_worksheet(workbook, NULL);
lxw_worksheet *worksheet2 = workbook_add_worksheet(workbook, NULL);
lxw_worksheet *worksheet3 = workbook_add_worksheet(workbook, NULL);
 
// Iterate over the 3 worksheets and perform the same operation on each.
LXW_FOREACH_WORKSHEET(worksheet, workbook) {
    worksheet_write_string(worksheet, 0, 0, "Hello", NULL);
}

Examples

defined_name.c.

Data Structures
struct	lxw_doc_properties
struct	lxw_workbook_options
	Workbook options. More...
struct	lxw_workbook
	Struct to represent an Excel workbook. More...

Typedefs
typedef struct lxw_doc_properties	lxw_doc_properties
typedef struct lxw_workbook_options	lxw_workbook_options
	Workbook options.
typedef struct lxw_workbook	lxw_workbook
	Struct to represent an Excel workbook.

Macros
#define	LXW_FOREACH_WORKSHEET(worksheet, workbook)    STAILQ_FOREACH((worksheet), (workbook)->worksheets, list_pointers)
	Macro to loop over all the worksheets in a workbook.