format.h File Reference

Description

This section describes the functions and properties that are available for formatting cells in Excel.

The properties of a cell that can be formatted include: fonts, colors, patterns, borders, alignment and number formatting.

Formats in libxlsxwriter are accessed via the lxw_format struct. Throughout this document these will be referred to simply as Formats.

Formats are created by calling the workbook_add_format() method as follows:

lxw_format *format = workbook_add_format(workbook);

The members of the lxw_format struct aren't modified directly. Instead the format properties are set by calling the functions shown in this section. For example:

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

The full range of formatting options that can be applied using libxlsxwriter are shown below.

Functions
void	format_set_font_name (lxw_format *format, const char *font_name)
	Set the font used in the cell.
void	format_set_font_size (lxw_format *format, double size)
	Set the size of the font used in the cell.
void	format_set_font_color (lxw_format *format, lxw_color_t color)
	Set the color of the font used in the cell.
void	format_set_bold (lxw_format *format)
	Turn on bold for the format font.
void	format_set_italic (lxw_format *format)
	Turn on italic for the format font.
void	format_set_underline (lxw_format *format, uint8_t style)
	Turn on underline for the format:
void	format_set_font_strikeout (lxw_format *format)
	Set the strikeout property of the font.
void	format_set_font_script (lxw_format *format, uint8_t style)
	Set the superscript/subscript property of the font.
void	format_set_num_format (lxw_format *format, const char *num_format)
	Set the number format for a cell.
void	format_set_num_format_index (lxw_format *format, uint8_t index)
	Set the Excel built-in number format for a cell.
void	format_set_unlocked (lxw_format *format)
	Set the cell unlocked state.
void	format_set_hidden (lxw_format *format)
	Hide formulas in a cell.
void	format_set_align (lxw_format *format, uint8_t alignment)
	Set the alignment for data in the cell.
void	format_set_text_wrap (lxw_format *format)
	Wrap text in a cell.
void	format_set_rotation (lxw_format *format, int16_t angle)
	Set the rotation of the text in a cell.
void	format_set_indent (lxw_format *format, uint8_t level)
	Set the cell text indentation level.
void	format_set_shrink (lxw_format *format)
	Turn on the text "shrink to fit" for a cell.
void	format_set_pattern (lxw_format *format, uint8_t index)
	Set the background fill pattern for a cell.
void	format_set_bg_color (lxw_format *format, lxw_color_t color)
	Set the pattern background color for a cell.
void	format_set_fg_color (lxw_format *format, lxw_color_t color)
	Set the pattern foreground color for a cell.
void	format_set_border (lxw_format *format, uint8_t style)
	Set the cell border style.
void	format_set_bottom (lxw_format *format, uint8_t style)
	Set the cell bottom border style.
void	format_set_top (lxw_format *format, uint8_t style)
	Set the cell top border style.
void	format_set_left (lxw_format *format, uint8_t style)
	Set the cell left border style.
void	format_set_right (lxw_format *format, uint8_t style)
	Set the cell right border style.
void	format_set_border_color (lxw_format *format, lxw_color_t color)
	Set the color of the cell border.
void	format_set_bottom_color (lxw_format *format, lxw_color_t color)
	Set the color of the bottom cell border.
void	format_set_top_color (lxw_format *format, lxw_color_t color)
	Set the color of the top cell border.
void	format_set_left_color (lxw_format *format, lxw_color_t color)
	Set the color of the left cell border.
void	format_set_right_color (lxw_format *format, lxw_color_t color)
	Set the color of the right cell border.
void	format_set_diag_type (lxw_format *format, uint8_t type)
	Set the diagonal cell border type.
void	format_set_diag_border (lxw_format *format, uint8_t style)
	Set the diagonal cell border style.
void	format_set_diag_color (lxw_format *format, lxw_color_t color)
	Set the diagonal cell border color.
void	format_set_quote_prefix (lxw_format *format)
	Turn on quote prefix for the format.

Function Documentation

format_set_font_name()

void format_set_font_name	(	lxw_format *	format,
		const char *	font_name
	)

Parameters

format	Pointer to a Format instance.
font_name	Cell font name.

Specify the font used used in the cell format:

format_set_font_name(format, "Avenir Black Oblique");

Excel can only display fonts that are installed on the system that it is running on. Therefore it is generally best to use the fonts that come as standard with Excel such as Calibri, Times New Roman and Courier New.

The default font in Excel 2007, and later, is Calibri.

format_set_font_size()

void format_set_font_size	(	lxw_format *	format,
		double	size
	)

Parameters

format	Pointer to a Format instance.
size	The cell font size.

Set the font size of the cell format:

format_set_font_size(format, 30);

Excel adjusts the height of a row to accommodate the largest font size in the row. You can also explicitly specify the height of a row using the worksheet_set_row() function.

format_set_font_color()

void format_set_font_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell font color.

Set the font color:

format = workbook_add_format(workbook);
format_set_font_color(format, LXW_COLOR_RED);
 
worksheet_write_string(worksheet, 0, 0, "Wheelbarrow", format);

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

Note

The format_set_font_color() method is used to set the font color in a cell. To set the color of a cell background use the format_set_bg_color() and format_set_pattern() methods.

Examples

conditional_format1.c, conditional_format2.c, dynamic_arrays.c, hyperlinks.c, merge_rich_string.c, and rich_strings.c.

format_set_bold()

void format_set_bold

(

lxw_format *

format

)

Parameters

format

Pointer to a Format instance.

Set the bold property of the font:

format = workbook_add_format(workbook);
format_set_bold(format);
 
worksheet_write_string(worksheet, 0, 0, "Bold Text", format);

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, data_validate.c, dates_and_times04.c, demo.c, format_font.c, merge_range.c, outline.c, outline_collapsed.c, panes.c, rich_strings.c, tutorial2.c, and tutorial3.c.

format_set_italic()

void format_set_italic

(

lxw_format *

format

)

Parameters

format

Pointer to a Format instance.

Set the italic property of the font:

format = workbook_add_format(workbook);
format_set_italic(format);
 
worksheet_write_string(worksheet, 0, 0, "Italic Text", format);

Examples

format_font.c, and rich_strings.c.

format_set_underline()

void format_set_underline	(	lxw_format *	format,
		uint8_t	style
	)

Parameters

format	Pointer to a Format instance.
style	Underline style.

Set the underline property of the format:

format_set_underline(format, LXW_UNDERLINE_SINGLE);

The available underline styles are:

• LXW_UNDERLINE_SINGLE
• LXW_UNDERLINE_DOUBLE
• LXW_UNDERLINE_SINGLE_ACCOUNTING
• LXW_UNDERLINE_DOUBLE_ACCOUNTING

Examples

hyperlinks.c.

format_set_font_strikeout()

void format_set_font_strikeout

(

lxw_format *

format

)

Parameters

format

Pointer to a Format instance.

format_set_font_script()

void format_set_font_script	(	lxw_format *	format,
		uint8_t	style
	)

Parameters

format	Pointer to a Format instance.
style	Superscript or subscript style.

Set the superscript o subscript property of the font.

The available script styles are:

• LXW_FONT_SUPERSCRIPT
• LXW_FONT_SUBSCRIPT

Examples

rich_strings.c.

format_set_num_format()

void format_set_num_format	(	lxw_format *	format,
		const char *	num_format
	)

Parameters

format	Pointer to a Format instance.
num_format	The cell number format string.

This method is used to define the numerical format of a number in Excel. It controls whether a number is displayed as an integer, a floating point number, a date, a currency value or some other user defined format.

The numerical format of a cell can be specified by using a format string:

format = workbook_add_format(workbook);
format_set_num_format(format, "d mmm yyyy");

Format strings can control any aspect of number formatting allowed by Excel:

    format_set_num_format(format01, "0.000");
    format_set_num_format(format02, "#,##0");
    format_set_num_format(format03, "#,##0.00");
    format_set_num_format(format04, "0.00");
    format_set_num_format(format05, "mm/dd/yy");
    format_set_num_format(format06, "mmm d yyyy");
    format_set_num_format(format07, "d mmmm yyyy");
    format_set_num_format(format08, "dd/mm/yyyy hh:mm AM/PM");
    format_set_num_format(format09, "0 \"dollar and\" .00 \"cents\"");
 
    /* Write data using the formats. */
    worksheet_write_number(worksheet, 0, 0, 3.1415926, NULL);      // 3.1415926
    worksheet_write_number(worksheet, 1, 0, 3.1415926, format01);  // 3.142
    worksheet_write_number(worksheet, 2, 0, 1234.56,   format02);  // 1,235
    worksheet_write_number(worksheet, 3, 0, 1234.56,   format03);  // 1,234.56
    worksheet_write_number(worksheet, 4, 0, 49.99,     format04);  // 49.99
    worksheet_write_number(worksheet, 5, 0, 36892.521, format05);  // 01/01/01
    worksheet_write_number(worksheet, 6, 0, 36892.521, format06);  // Jan 1 2001
    worksheet_write_number(worksheet, 7, 0, 36892.521, format07);  // 1 January 2001
    worksheet_write_number(worksheet, 8, 0, 36892.521, format08);  // 01/01/2001 12:30 AM
    worksheet_write_number(worksheet, 9, 0, 1.87,      format09);  // 1 dollar and .87 cents
 
    /* Show limited conditional number formats. */
    format_set_num_format(format10, "[Green]General;[Red]-General;General");
    worksheet_write_number(worksheet, 10, 0, 123, format10);  // > 0 Green
    worksheet_write_number(worksheet, 11, 0, -45, format10);  // < 0 Red
    worksheet_write_number(worksheet, 12, 0,   0, format10);  // = 0 Default color
 
    /* Format a Zip code. */
    format_set_num_format(format11, "00000");
    worksheet_write_number(worksheet, 13, 0, 1209, format11);

To set a number format that matches an Excel format category such as "Date" or "Currency" see Number Format Categories.

The number system used for dates is described in Working with Dates and Times.

For more information on number formats in Excel refer to the Microsoft documentation on cell formats.

Examples

anatomy.c, dates_and_times01.c, dates_and_times02.c, dates_and_times03.c, dates_and_times04.c, format_num_format.c, tables.c, tutorial2.c, and tutorial3.c.

format_set_num_format_index()

void format_set_num_format_index	(	lxw_format *	format,
		uint8_t	index
	)

Parameters

format	Pointer to a Format instance.
index	The built-in number format index for the cell.

This function is similar to format_set_num_format() except that it takes an index to a limited number of Excel's built-in number formats instead of a user defined format string:

format = workbook_add_format(workbook);
format_set_num_format_index(format, 0x0F); // d-mmm-yy

Note

Unless you need to specifically access one of Excel's built-in number formats the format_set_num_format() function above is a better solution. The format_set_num_format_index() function is mainly included for backward compatibility and completeness.

The Excel built-in number formats as shown in the table below:

Index	Index	Format String
0	0x00	General
1	0x01	0
2	0x02	0.00
3	0x03	#,##0
4	0x04	#,##0.00
5	0x05	($#,##0_);($#,##0)
6	0x06	($#,##0_);[Red]($#,##0)
7	0x07	($#,##0.00_);($#,##0.00)
8	0x08	($#,##0.00_);[Red]($#,##0.00)
9	0x09	0%
10	0x0a	0.00%
11	0x0b	0.00E+00
12	0x0c	# ?/?
13	0x0d	# ??/??
14	0x0e	m/d/yy
15	0x0f	d-mmm-yy
16	0x10	d-mmm
17	0x11	mmm-yy
18	0x12	h:mm AM/PM
19	0x13	h:mm:ss AM/PM
20	0x14	h:mm
21	0x15	h:mm:ss
22	0x16	m/d/yy h:mm
...	...	...
37	0x25	(#,##0_);(#,##0)
38	0x26	(#,##0_);[Red](#,##0)
39	0x27	(#,##0.00_);(#,##0.00)
40	0x28	(#,##0.00_);[Red](#,##0.00)
41	0x29	_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)
42	0x2a	_($* #,##0_);_($* (#,##0);_($* "-"_);_(@_)
43	0x2b	_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)
44	0x2c	_($* #,##0.00_);_($* (#,##0.00);_($* "-"??_);_(@_)
45	0x2d	mm:ss
46	0x2e	[h]:mm:ss
47	0x2f	mm:ss.0
48	0x30	##0.0E+0
49	0x31	@

Note

• Numeric formats 23 to 36 are not documented by Microsoft and may differ in international versions. The listed date and currency formats may also vary depending on system settings.
• The dollar sign in the above format appears as the defined local currency symbol.
• These formats can also be set via format_set_num_format().
• See also Number Format Categories.

format_set_unlocked()

void format_set_unlocked

(

lxw_format *

format

)

Parameters

format

Pointer to a Format instance.

This property can be used to allow modification of a cell in a protected worksheet. In Excel, cell locking is turned on by default for all cells. However, it only has an effect if the worksheet has been protected using the worksheet worksheet_protect() function:

format = workbook_add_format(workbook);
format_set_unlocked(format);
 
// Enable worksheet protection, without password or options.
worksheet_protect(worksheet, NULL, NULL);
 
// This cell cannot be edited.
worksheet_write_formula(worksheet, 0, 0, "=1+2", NULL);
 
// This cell can be edited.
worksheet_write_formula(worksheet, 1, 0, "=1+2", format);

Examples

worksheet_protection.c.

format_set_hidden()

void format_set_hidden

(

lxw_format *

format

)

Parameters

format

Pointer to a Format instance.

This property is used to hide a formula while still displaying its result. This is generally used to hide complex calculations from end users who are only interested in the result. It only has an effect if the worksheet has been protected using the worksheet worksheet_protect() function:

format = workbook_add_format(workbook);
format_set_hidden(format);
 
// Enable worksheet protection, without password or options.
worksheet_protect(worksheet, NULL, NULL);
 
// The formula in this cell isn't visible.
worksheet_write_formula(worksheet, 0, 0, "=1+2", format);

Examples

worksheet_protection.c.

format_set_align()

void format_set_align	(	lxw_format *	format,
		uint8_t	alignment
	)

Parameters

format	Pointer to a Format instance.
alignment	The horizontal and or vertical alignment direction.

This method is used to set the horizontal and vertical text alignment within a cell. The following are the available horizontal alignments:

• LXW_ALIGN_LEFT
• LXW_ALIGN_CENTER
• LXW_ALIGN_RIGHT
• LXW_ALIGN_FILL
• LXW_ALIGN_JUSTIFY
• LXW_ALIGN_CENTER_ACROSS
• LXW_ALIGN_DISTRIBUTED

The following are the available vertical alignments:

• LXW_ALIGN_VERTICAL_TOP
• LXW_ALIGN_VERTICAL_BOTTOM
• LXW_ALIGN_VERTICAL_CENTER
• LXW_ALIGN_VERTICAL_JUSTIFY
• LXW_ALIGN_VERTICAL_DISTRIBUTED

As in Excel, vertical and horizontal alignments can be combined:

format = workbook_add_format(workbook);
 
format_set_align(format, LXW_ALIGN_CENTER);
format_set_align(format, LXW_ALIGN_VERTICAL_CENTER);
 
worksheet_set_row(0, 30);
worksheet_write_string(worksheet, 0, 0, "Some Text", format);

Text can be aligned across two or more adjacent cells using the center_across property. However, for genuine merged cells it is better to use the worksheet_merge_range() worksheet method.

The vertical justify option can be used to provide automatic text wrapping in a cell. The height of the cell will be adjusted to accommodate the wrapped text. To specify where the text wraps use the format_set_text_wrap() method.

Examples

comments2.c, data_validate.c, dates_and_times04.c, merge_range.c, merge_rich_string.c, panes.c, and rich_strings.c.

format_set_text_wrap()

void format_set_text_wrap

(

lxw_format *

format

)

Turn text wrapping on for text in a cell.

format = workbook_add_format(workbook);
format_set_text_wrap(format);
 
worksheet_write_string(worksheet, 0, 0, "Some long text to wrap in a cell", format);

If you wish to control where the text is wrapped you can add newline characters to the string:

format = workbook_add_format(workbook);
format_set_text_wrap(format);
 
worksheet_write_string(worksheet, 0, 0, "It's\na bum\nwrap", format);

Excel will adjust the height of the row to accommodate the wrapped text. A similar effect can be obtained without newlines using the format_set_align() function with LXW_ALIGN_VERTICAL_JUSTIFY.

Examples

comments2.c, and data_validate.c.

format_set_rotation()

void format_set_rotation	(	lxw_format *	format,
		int16_t	angle
	)

Parameters

format	Pointer to a Format instance.
angle	Rotation angle in the range -90 to 90 and 270.

Set the rotation of the text in a cell. The rotation can be any angle in the range -90 to 90 degrees:

format = workbook_add_format(workbook);
format_set_rotation(format, 30);
 
worksheet_write_string(worksheet, 0, 0, "This text is rotated", format);

The angle 270 is also supported. This indicates text where the letters run from top to bottom.

format_set_indent()

void format_set_indent	(	lxw_format *	format,
		uint8_t	level
	)

Parameters

format	Pointer to a Format instance.
level	Indentation level.

This method can be used to indent text in a cell. The argument, which should be an integer, is taken as the level of indentation:

format1 = workbook_add_format(workbook);
format2 = workbook_add_format(workbook);
 
format_set_indent(format1, 1);
format_set_indent(format2, 2);
 
worksheet_write_string(worksheet, 0, 0, "This text is indented 1 level",  format1);
worksheet_write_string(worksheet, 1, 0, "This text is indented 2 levels", format2);

Note

Indentation is a horizontal alignment property. It will override any other horizontal properties but it can be used in conjunction with vertical properties.

Examples

data_validate.c.

format_set_shrink()

void format_set_shrink

(

lxw_format *

format

)

Parameters

format

Pointer to a Format instance.

This method can be used to shrink text so that it fits in a cell:

format = workbook_add_format(workbook);
format_set_shrink(format);
 
worksheet_write_string(worksheet, 0, 0, "Honey, I shrunk the text!", format);

format_set_pattern()

void format_set_pattern	(	lxw_format *	format,
		uint8_t	index
	)

Parameters

format	Pointer to a Format instance.
index	Pattern index.

Set the background pattern for a cell.

The most common pattern is a solid fill of the background color:

format = workbook_add_format(workbook);
 
format_set_pattern (format, LXW_PATTERN_SOLID);
format_set_bg_color(format, LXW_COLOR_YELLOW);

The available fill patterns are:

Fill Type	Define
Solid	LXW_PATTERN_SOLID
Medium gray	LXW_PATTERN_MEDIUM_GRAY
Dark gray	LXW_PATTERN_DARK_GRAY
Light gray	LXW_PATTERN_LIGHT_GRAY
Dark horizontal line	LXW_PATTERN_DARK_HORIZONTAL
Dark vertical line	LXW_PATTERN_DARK_VERTICAL
Dark diagonal stripe	LXW_PATTERN_DARK_DOWN
Reverse dark diagonal stripe	LXW_PATTERN_DARK_UP
Dark grid	LXW_PATTERN_DARK_GRID
Dark trellis	LXW_PATTERN_DARK_TRELLIS
Light horizontal line	LXW_PATTERN_LIGHT_HORIZONTAL
Light vertical line	LXW_PATTERN_LIGHT_VERTICAL
Light diagonal stripe	LXW_PATTERN_LIGHT_DOWN
Reverse light diagonal stripe	LXW_PATTERN_LIGHT_UP
Light grid	LXW_PATTERN_LIGHT_GRID
Light trellis	LXW_PATTERN_LIGHT_TRELLIS
12.5% gray	LXW_PATTERN_GRAY_125
6.25% gray	LXW_PATTERN_GRAY_0625

format_set_bg_color()

void format_set_bg_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell pattern background color.

The format_set_bg_color() method can be used to set the background color of a pattern. Patterns are defined via the format_set_pattern() method. If a pattern hasn't been defined then a solid fill pattern is used as the default.

Here is an example of how to set up a solid fill in a cell:

format = workbook_add_format(workbook);
 
format_set_pattern (format, LXW_PATTERN_SOLID);
format_set_bg_color(format, LXW_COLOR_GREEN);
 
worksheet_write_string(worksheet, 0, 0, "Ray", format);

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

Examples

conditional_format2.c, dynamic_arrays.c, and merge_range.c.

format_set_fg_color()

void format_set_fg_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell pattern foreground color.

The format_set_fg_color() method can be used to set the foreground color of a pattern.

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

Examples

data_validate.c, and panes.c.

format_set_border()

void format_set_border	(	lxw_format *	format,
		uint8_t	style
	)

Parameters

format	Pointer to a Format instance.
style	Border style index.

Set the cell border style:

format_set_border(format, LXW_BORDER_THIN);

Individual border elements can be configured using the following functions with the same parameters:

• format_set_bottom()
• format_set_top()
• format_set_left()
• format_set_right()

A cell border is comprised of a border on the bottom, top, left and right. These can be set to the same value using format_set_border() or individually using the relevant method calls shown above.

The following border styles are available:

• LXW_BORDER_THIN
• LXW_BORDER_MEDIUM
• LXW_BORDER_DASHED
• LXW_BORDER_DOTTED
• LXW_BORDER_THICK
• LXW_BORDER_DOUBLE
• LXW_BORDER_HAIR
• LXW_BORDER_MEDIUM_DASHED
• LXW_BORDER_DASH_DOT
• LXW_BORDER_MEDIUM_DASH_DOT
• LXW_BORDER_DASH_DOT_DOT
• LXW_BORDER_MEDIUM_DASH_DOT_DOT

• LXW_BORDER_SLANT_DASH_DOT

  The most commonly used style is the thin style.

Examples

data_validate.c, merge_range.c, merge_rich_string.c, and panes.c.

format_set_bottom()

void format_set_bottom	(	lxw_format *	format,
		uint8_t	style
	)

Parameters

format	Pointer to a Format instance.
style	Border style index.

Set the cell bottom border style. See format_set_border() for details on the border styles.

format_set_top()

void format_set_top	(	lxw_format *	format,
		uint8_t	style
	)

Parameters

format	Pointer to a Format instance.
style	Border style index.

Set the cell top border style. See format_set_border() for details on the border styles.

format_set_left()

void format_set_left	(	lxw_format *	format,
		uint8_t	style
	)

Parameters

format	Pointer to a Format instance.
style	Border style index.

Set the cell left border style. See format_set_border() for details on the border styles.

format_set_right()

void format_set_right	(	lxw_format *	format,
		uint8_t	style
	)

Parameters

format	Pointer to a Format instance.
style	Border style index.

Set the cell right border style. See format_set_border() for details on the border styles.

format_set_border_color()

void format_set_border_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell border color.

Individual border elements can be configured using the following methods with the same parameters:

• format_set_bottom_color()
• format_set_top_color()
• format_set_left_color()
• format_set_right_color()

Set the color of the cell borders. A cell border is comprised of a border on the bottom, top, left and right. These can be set to the same color using format_set_border_color() or individually using the relevant method calls shown above.

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

format_set_bottom_color()

void format_set_bottom_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell border color.

See format_set_border_color() for details on the border colors.

format_set_top_color()

void format_set_top_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell border color.

See format_set_border_color() for details on the border colors.

format_set_left_color()

void format_set_left_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell border color.

See format_set_border_color() for details on the border colors.

format_set_right_color()

void format_set_right_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell border color.

See format_set_border_color() for details on the border colors.

format_set_diag_type()

void format_set_diag_type	(	lxw_format *	format,
		uint8_t	type
	)

Parameters

format	Pointer to a Format instance.
type	The lxw_format_diagonal_types diagonal border type.

Set the diagonal cell border type:

lxw_format *format1 = workbook_add_format(workbook);
format_set_diag_type(  format1, LXW_DIAGONAL_BORDER_UP);
 
lxw_format *format2 = workbook_add_format(workbook);
format_set_diag_type(  format2, LXW_DIAGONAL_BORDER_DOWN);
 
lxw_format *format3 = workbook_add_format(workbook);
format_set_diag_type(  format3, LXW_DIAGONAL_BORDER_UP_DOWN);
 
lxw_format *format4 = workbook_add_format(workbook);
format_set_diag_type(  format4, LXW_DIAGONAL_BORDER_UP_DOWN);
format_set_diag_border(format4, LXW_BORDER_HAIR);
format_set_diag_color( format4, LXW_COLOR_RED);
 
worksheet_write_string(worksheet, CELL("B3"),  "Text", format1);
worksheet_write_string(worksheet, CELL("B6"),  "Text", format2);
worksheet_write_string(worksheet, CELL("B9"),  "Text", format3);
worksheet_write_string(worksheet, CELL("B12"), "Text", format4);

The allowable border types are defined in lxw_format_diagonal_types:

• LXW_DIAGONAL_BORDER_UP: Cell diagonal border from bottom left to top right.
• LXW_DIAGONAL_BORDER_DOWN: Cell diagonal border from top left to bottom right.
• LXW_DIAGONAL_BORDER_UP_DOWN: Cell diagonal border from top left to bottom right. A combination of the 2 previous types.

If the border style isn't specified with format_set_diag_border() then it will default to LXW_BORDER_THIN.

Examples

diagonal_border.c.

format_set_diag_border()

void format_set_diag_border	(	lxw_format *	format,
		uint8_t	style
	)

Parameters

format	Pointer to a Format instance.
style	The lxw_format_borders style.

Set the diagonal border style. This should be a lxw_format_borders value. See the example above.

Examples

diagonal_border.c.

format_set_diag_color()

void format_set_diag_color	(	lxw_format *	format,
		lxw_color_t	color
	)

Parameters

format	Pointer to a Format instance.
color	The cell diagonal border color.

Set the diagonal border color. The color should be an RGB integer value, see Working with Colors and the above example.

Examples

diagonal_border.c.

format_set_quote_prefix()

void format_set_quote_prefix

(

lxw_format *

format

)

Parameters

format

Pointer to a Format instance.

Set the quote prefix property of a format to ensure a string is treated as a string after editing. This is the same as prefixing the string with a single quote in Excel. You don't need to add the quote to the string but you do need to add the format.

format = workbook_add_format(workbook);
format_set_quote_prefix(format);
 
worksheet_write_string(worksheet, 0, 0, "=Foo", format);

Typedef Documentation

lxw_color_t

typedef uint32_t lxw_color_t

The type for RGB colors in libxlsxwriter. The valid range is 0x000000 (black) to 0xFFFFFF (white). See Working with Colors.

lxw_format

typedef struct lxw_format lxw_format

Formats in libxlsxwriter are accessed via this struct.

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

For example:

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

Enumeration Type Documentation

lxw_format_underlines

enum lxw_format_underlines

Format underline values for format_set_underline().

Enumerator
LXW_UNDERLINE_SINGLE	Single underline
LXW_UNDERLINE_DOUBLE	Double underline
LXW_UNDERLINE_SINGLE_ACCOUNTING	Single accounting underline
LXW_UNDERLINE_DOUBLE_ACCOUNTING	Double accounting underline

lxw_format_scripts

enum lxw_format_scripts

Superscript and subscript values for format_set_font_script().

Enumerator
LXW_FONT_SUPERSCRIPT	Superscript font
LXW_FONT_SUBSCRIPT	Subscript font

lxw_format_alignments

enum lxw_format_alignments

Alignment values for format_set_align().

Enumerator
LXW_ALIGN_NONE	No alignment. Cell will use Excel's default for the data type
LXW_ALIGN_LEFT	Left horizontal alignment
LXW_ALIGN_CENTER	Center horizontal alignment
LXW_ALIGN_RIGHT	Right horizontal alignment
LXW_ALIGN_FILL	Cell fill horizontal alignment
LXW_ALIGN_JUSTIFY	Justify horizontal alignment
LXW_ALIGN_CENTER_ACROSS	Center Across horizontal alignment
LXW_ALIGN_DISTRIBUTED	Left horizontal alignment
LXW_ALIGN_VERTICAL_TOP	Top vertical alignment
LXW_ALIGN_VERTICAL_BOTTOM	Bottom vertical alignment
LXW_ALIGN_VERTICAL_CENTER	Center vertical alignment
LXW_ALIGN_VERTICAL_JUSTIFY	Justify vertical alignment
LXW_ALIGN_VERTICAL_DISTRIBUTED	Distributed vertical alignment

lxw_format_diagonal_types

enum lxw_format_diagonal_types

Diagonal border types.

Enumerator
LXW_DIAGONAL_BORDER_UP	Cell diagonal border from bottom left to top right.
LXW_DIAGONAL_BORDER_DOWN	Cell diagonal border from top left to bottom right.
LXW_DIAGONAL_BORDER_UP_DOWN	Cell diagonal border in both directions.

lxw_defined_colors

enum lxw_defined_colors

Predefined values for common colors.

Enumerator
LXW_COLOR_BLACK	Black
LXW_COLOR_BLUE	Blue
LXW_COLOR_BROWN	Brown
LXW_COLOR_CYAN	Cyan
LXW_COLOR_GRAY	Gray
LXW_COLOR_GREEN	Green
LXW_COLOR_LIME	Lime
LXW_COLOR_MAGENTA	Magenta
LXW_COLOR_NAVY	Navy
LXW_COLOR_ORANGE	Orange
LXW_COLOR_PINK	Pink
LXW_COLOR_PURPLE	Purple
LXW_COLOR_RED	Red
LXW_COLOR_SILVER	Silver
LXW_COLOR_WHITE	White
LXW_COLOR_YELLOW	Yellow

lxw_format_patterns

enum lxw_format_patterns

Pattern value for use with format_set_pattern().

Enumerator
LXW_PATTERN_NONE	Empty pattern
LXW_PATTERN_SOLID	Solid pattern
LXW_PATTERN_MEDIUM_GRAY	Medium gray pattern
LXW_PATTERN_DARK_GRAY	Dark gray pattern
LXW_PATTERN_LIGHT_GRAY	Light gray pattern
LXW_PATTERN_DARK_HORIZONTAL	Dark horizontal line pattern
LXW_PATTERN_DARK_VERTICAL	Dark vertical line pattern
LXW_PATTERN_DARK_DOWN	Dark diagonal stripe pattern
LXW_PATTERN_DARK_UP	Reverse dark diagonal stripe pattern
LXW_PATTERN_DARK_GRID	Dark grid pattern
LXW_PATTERN_DARK_TRELLIS	Dark trellis pattern
LXW_PATTERN_LIGHT_HORIZONTAL	Light horizontal Line pattern
LXW_PATTERN_LIGHT_VERTICAL	Light vertical line pattern
LXW_PATTERN_LIGHT_DOWN	Light diagonal stripe pattern
LXW_PATTERN_LIGHT_UP	Reverse light diagonal stripe pattern
LXW_PATTERN_LIGHT_GRID	Light grid pattern
LXW_PATTERN_LIGHT_TRELLIS	Light trellis pattern
LXW_PATTERN_GRAY_125	12.5% gray pattern
LXW_PATTERN_GRAY_0625	6.25% gray pattern

lxw_format_borders

enum lxw_format_borders

Cell border styles for use with format_set_border().

Enumerator
LXW_BORDER_NONE	No border
LXW_BORDER_THIN	Thin border style
LXW_BORDER_MEDIUM	Medium border style
LXW_BORDER_DASHED	Dashed border style
LXW_BORDER_DOTTED	Dotted border style
LXW_BORDER_THICK	Thick border style
LXW_BORDER_DOUBLE	Double border style
LXW_BORDER_HAIR	Hair border style
LXW_BORDER_MEDIUM_DASHED	Medium dashed border style
LXW_BORDER_DASH_DOT	Dash-dot border style
LXW_BORDER_MEDIUM_DASH_DOT	Medium dash-dot border style
LXW_BORDER_DASH_DOT_DOT	Dash-dot-dot border style
LXW_BORDER_MEDIUM_DASH_DOT_DOT	Medium dash-dot-dot border style
LXW_BORDER_SLANT_DASH_DOT	Slant dash-dot border style

Data Structures
struct	lxw_format
	Struct to represent the formatting properties of an Excel format. More...

Typedefs
typedef uint32_t	lxw_color_t
	The type for RGB colors in libxlsxwriter.
typedef struct lxw_format	lxw_format
	Struct to represent the formatting properties of an Excel format.

Enumerations
enum	lxw_format_underlines { }
enum	lxw_format_scripts { LXW_FONT_SUPERSCRIPT = 1 , LXW_FONT_SUBSCRIPT }
enum	lxw_format_alignments {   LXW_ALIGN_NONE = 0 , LXW_ALIGN_LEFT , LXW_ALIGN_CENTER , LXW_ALIGN_RIGHT ,   LXW_ALIGN_FILL , LXW_ALIGN_JUSTIFY , LXW_ALIGN_CENTER_ACROSS , LXW_ALIGN_DISTRIBUTED ,   LXW_ALIGN_VERTICAL_TOP , LXW_ALIGN_VERTICAL_BOTTOM , LXW_ALIGN_VERTICAL_CENTER , LXW_ALIGN_VERTICAL_JUSTIFY ,   LXW_ALIGN_VERTICAL_DISTRIBUTED }
enum	lxw_format_diagonal_types { LXW_DIAGONAL_BORDER_UP = 1 , LXW_DIAGONAL_BORDER_DOWN , LXW_DIAGONAL_BORDER_UP_DOWN }
enum	lxw_defined_colors {   LXW_COLOR_BLACK = 0x1000000 , LXW_COLOR_BLUE = 0x0000FF , LXW_COLOR_BROWN = 0x800000 , LXW_COLOR_CYAN = 0x00FFFF ,   LXW_COLOR_GRAY = 0x808080 , LXW_COLOR_GREEN = 0x008000 , LXW_COLOR_LIME = 0x00FF00 , LXW_COLOR_MAGENTA = 0xFF00FF ,   LXW_COLOR_NAVY = 0x000080 , LXW_COLOR_ORANGE = 0xFF6600 , LXW_COLOR_PINK = 0xFF00FF , LXW_COLOR_PURPLE = 0x800080 ,   LXW_COLOR_RED = 0xFF0000 , LXW_COLOR_SILVER = 0xC0C0C0 , LXW_COLOR_WHITE = 0xFFFFFF , LXW_COLOR_YELLOW = 0xFFFF00 }
enum	lxw_format_patterns {   LXW_PATTERN_NONE = 0 , LXW_PATTERN_SOLID , LXW_PATTERN_MEDIUM_GRAY , LXW_PATTERN_DARK_GRAY ,   LXW_PATTERN_LIGHT_GRAY , LXW_PATTERN_DARK_HORIZONTAL , LXW_PATTERN_DARK_VERTICAL , LXW_PATTERN_DARK_DOWN ,   LXW_PATTERN_DARK_UP , LXW_PATTERN_DARK_GRID , LXW_PATTERN_DARK_TRELLIS , LXW_PATTERN_LIGHT_HORIZONTAL ,   LXW_PATTERN_LIGHT_VERTICAL , LXW_PATTERN_LIGHT_DOWN , LXW_PATTERN_LIGHT_UP , LXW_PATTERN_LIGHT_GRID ,   LXW_PATTERN_LIGHT_TRELLIS , LXW_PATTERN_GRAY_125 , LXW_PATTERN_GRAY_0625 }
enum	lxw_format_borders {   LXW_BORDER_NONE , LXW_BORDER_THIN , LXW_BORDER_MEDIUM , LXW_BORDER_DASHED ,   LXW_BORDER_DOTTED , LXW_BORDER_THICK , LXW_BORDER_DOUBLE , LXW_BORDER_HAIR ,   LXW_BORDER_MEDIUM_DASHED , LXW_BORDER_DASH_DOT , LXW_BORDER_MEDIUM_DASH_DOT , LXW_BORDER_DASH_DOT_DOT ,   LXW_BORDER_MEDIUM_DASH_DOT_DOT , LXW_BORDER_SLANT_DASH_DOT }