Working with Formats

The methods and properties used to add formatting to a cell are shown in The Format Class.

This section provides some additional information about working with formats.

Creating and using a Format object

Cell formatting is defined through a Format object. Format objects are created by calling the workbook add_format() method as follows:

format1 = workbook.add_format()       # Set properties later.
format2 = workbook.add_format(props)  # Set properties at creation.

Once a Format object has been constructed and its properties have been set it can be passed as an argument to the worksheet write methods as follows:

worksheet.write       (0, 0, 'Foo', format)
worksheet.write_string(1, 0, 'Bar', format)
worksheet.write_number(2, 0, 3,     format)
worksheet.write_blank (3, 0, '',    format)

Formats can also be passed to the worksheet set_row() and set_column() methods to define the default property for a row or column:

worksheet.set_row(0, 18, format)
worksheet.set_column('A:D', 20, format)

Format methods and Format properties

The following table shows the Excel format categories, the formatting properties that can be applied and the equivalent object method:

Category Description Property Method Name
Font Font type 'font_name' set_font_name()
  Font size 'font_size' set_font_size()
  Font color 'font_color' set_font_color()
  Bold 'bold' set_bold()
  Italic 'italic' set_italic()
  Underline 'underline' set_underline()
  Strikeout 'font_strikeout' set_font_strikeout()
  Super/Subscript 'font_script' set_font_script()
Number Numeric format 'num_format' set_num_format()
Protection Lock cells 'locked' set_locked()
  Hide formulas 'hidden' set_hidden()
Alignment Horizontal align 'align' set_align()
  Vertical align 'valign' set_align()
  Rotation 'rotation' set_rotation()
  Text wrap 'text_wrap' set_text_wrap()
  Justify last 'text_justlast' set_text_justlast()
  Center across 'center_across' set_center_across()
  Indentation 'indent' set_indent()
  Shrink to fit 'shrink' set_shrink()
Pattern Cell pattern 'pattern' set_pattern()
  Background color 'bg_color' set_bg_color()
  Foreground color 'fg_color' set_fg_color()
Border Cell border 'border' set_border()
  Bottom border 'bottom' set_bottom()
  Top border 'top' set_top()
  Left border 'left' set_left()
  Right border 'right' set_right()
  Border color 'border_color' set_border_color()
  Bottom color 'bottom_color' set_bottom_color()
  Top color 'top_color' set_top_color()
  Left color 'left_color' set_left_color()
  Right color 'right_color' set_right_color()

There are two ways of setting Format properties: by using the object interface or by setting the property as a dictionary of key/value pairs in the constructor. For example, a typical use of the object interface would be as follows:

format = workbook.add_format()
format.set_bold()
format.set_font_color('red')

By comparison the properties can be set by passing a dictionary of properties to the add_format() constructor:

format = workbook.add_format({'bold': True, 'font_color': 'red'})

The object method interface is mainly provided for backward compatibility with Excel::Writer::XLSX. The key/value interface has proved to be more flexible in real world programs and is the recommended method for setting format properties.

Format Colors

Format property colors are specified using a Html sytle #RRGGBB index:

cell_format.set_font_color('#FF0000')

For backward compatibility with Excel::Writer::XLSX a limited number of color names are supported:

cell_format.set_font_color('red')

The color names and corresponding #RRGGBB indices are shown below:

Color name RGB color code
black #000000
blue #0000FF
brown #800000
cyan #00FFFF
gray #808080
green #008000
lime #00FF00
magenta #FF00FF
navy #000080
orange #FF6600
pink #FF00FF
purple #800080
red #FF0000
silver #C0C0C0
white #FFFFFF
yellow #FFFF00

Format Defaults

The default Excel 2007+ cell format is Calibri 11 with all other properties off.

In general a format method call without an argument will turn a property on, for example:

format1 = workbook.add_format()

format1.set_bold()   # Turns bold on.
format1.set_bold(1)  # Also turns bold on.

Since most properties are already off by default it isn’t generally required to turn them off. However, it is possible if required:

format1.set_bold(0); # Turns bold off.

Modifying Formats

Each unique cell format in an XlsxWriter spreadsheet must have a corresponding Format object. It isn’t possible to use a Format with a write() method and then redefine it for use at a later stage. This is because a Format is applied to a cell not in its current state but in its final state. Consider the following example:

format = workbook.add_format({'bold': True, 'font_color': 'red'})
worksheet.write('A1', 'Cell A1', format)

# Later...
format.set_font_color('green')
worksheet.write('B1', 'Cell B1', format)

Cell A1 is assigned a format which is initially has the font set to the colour red. However, the colour is subsequently set to green. When Excel displays Cell A1 it will display the final state of the Format which in this case will be the colour green.