Style annotations

`@ExcelStyle`

Declares a named style: a set of formatting attributes that slots reference by name.

Where. On the sheet class, or on a style sheet class annotated with @ExcelStyleSheet to share it.
Repeatable. Write it as many times as needed on the same class.
Names. Not blank (V-16), unique within the declaring class (V-07). Names are case-sensitive and matched exactly, spaces included.
Not inherited from superclasses.
Effect only through slots. A declared but unreferenced style has no effect.
Within one style, a side-specific border line or colour (borderTop, borderTopColor, …) wins over the all-sides attribute (border, borderColor) on that side.

The attributes, grouped by area. Every attribute other than name defaults to “unset”.

Attribute	Type	Unset value	Allowed values	Effect
`name`	`String`	none, mandatory	non-blank	Name used by slots.
`align`	`Align`	`INHERIT`	see B.1	Horizontal alignment.
`verticalAlign`	`VerticalAlign`	`INHERIT`	see B.2	Vertical alignment.
`wrapText`	`Toggle`	`INHERIT`	`TRUE`, `FALSE`	Long text wraps on several lines.
`shrinkToFit`	`Toggle`	`INHERIT`	`TRUE`, `FALSE`	The font shrinks so the text fits the cell width.
`rotation`	`int`	`UNSET`	-90 to 90, or 255	Text rotation in degrees; 255 means vertical stacked text.
`indent`	`int`	`UNSET`	0 to 250	Indentation level.
`border`	`Border`	`INHERIT`	see B.3	Border line of all four sides.
`borderColor`	`String`	`""`	colour	Border colour of all four sides.
`borderTop`, `borderBottom`, `borderLeft`, `borderRight`	`Border`	`INHERIT`	see B.3	Border line of one side; wins over `border` in the same style.
`borderTopColor`, `borderBottomColor`, `borderLeftColor`, `borderRightColor`	`String`	`""`	colour	Border colour of one side; wins over `borderColor` in the same style.
`fillColor`	`String`	`""`	colour	Foreground fill colour, the background colour of the cell.
`fillBackgroundColor`	`String`	`""`	colour	Second colour, used only by patterned fills.
`fillPattern`	`Fill`	`INHERIT`	see B.4	Fill pattern.
`fontName`	`String`	`""`	a font name, for example `Arial`	Font family.
`fontSize`	`int`	`UNSET`	1 to 409	Font size in points.
`bold`	`Toggle`	`INHERIT`	`TRUE`, `FALSE`	Bold font.
`italic`	`Toggle`	`INHERIT`	`TRUE`, `FALSE`	Italic font.
`strikeout`	`Toggle`	`INHERIT`	`TRUE`, `FALSE`	Struck-out text.
`underline`	`Underline`	`INHERIT`	see B.5	Underline.
`fontColor`	`String`	`""`	colour	Font colour.
`script`	`Script`	`INHERIT`	see B.6	Superscript or subscript.
`dataFormat`	`String`	`""`	Excel format code	Data format of the cells the style applies to.
`locked`	`Toggle`	`INHERIT`	`TRUE`, `FALSE`	Locked cell; effective only on protected sheets.
`hidden`	`Toggle`	`INHERIT`	`TRUE`, `FALSE`	Hidden formula; effective only on protected sheets.
`quotePrefix`	`Toggle`	`INHERIT`	`TRUE`, `FALSE`	Excel quote prefix, which marks the value as text.

Validation of @ExcelStyle:

Rule	Checked on
V-16	`name` blank. The style is then ignored, and the error element is `@ExcelStyle(#n)`, `n` being the 1-based position of the declaration on the class.
V-07	the same `name` declared twice on the same class.
V-13	`borderColor`, the four side colours, `fillColor`, `fillBackgroundColor`, `fontColor`.
V-14	`rotation`, `indent`, `fontSize`.

Notes on specific attributes:

Fill. When the effective style has a fillColor and no fillPattern, the fill is solid (SOLID_FOREGROUND). A plain background needs fillColor only. fillBackgroundColor matters only with a patterned fill. Setting fillPattern = Fill.NO_FILL at a higher level removes a fill set at a lower level.
Removing inherited values. Toggle.FALSE, Border.NONE, Underline.NONE, Script.NONE and Fill.NO_FILL explicitly remove what a lower level set, while INHERIT keeps it.
Protection. locked and hidden take effect only when the sheet is protected, and sheetsmith does not protect sheets: they matter only if the reader protects the sheet in Excel.
dataFormat. On data cells, @ExcelColumn.format wins over it. When no level sets a format, the application default for the kind of value applies.

@ExcelStyle(name = "header", bold = Toggle.TRUE, fillColor = "#1F4E79", fontColor = "#FFFFFF",
        align = Align.CENTER, verticalAlign = VerticalAlign.CENTER, wrapText = Toggle.TRUE)
@ExcelStyle(name = "zebra", fillColor = "#EEF3F8")
@ExcelStyle(name = "money", align = Align.RIGHT, dataFormat = "#,##0.00")
@ExcelStyle(name = "boxed", border = Border.THIN, borderColor = "#BFBFBF", borderBottom = Border.MEDIUM)
@ExcelStyle(name = "note", italic = Toggle.TRUE, fontColor = "GREY_50_PERCENT", fontSize = 9)
@ExcelStyle(name = "vertical", rotation = 90, align = Align.CENTER)
@ExcelStyle(name = "hatched", fillPattern = Fill.THIN_FORWARD_DIAG, fillColor = "#C00000",
        fillBackgroundColor = "#FFFFFF")
@ExcelStyle(name = "as-text", quotePrefix = Toggle.TRUE)

In boxed, the bottom side is MEDIUM and the other three are THIN, all with the colour #BFBFBF.

`@ExcelStyles`

Container of repeated @ExcelStyle annotations. The compiler uses it automatically when @ExcelStyle is repeated on a class. It has one attribute, value, of type ExcelStyle[]. Writing it explicitly is allowed but never necessary:

// equivalent forms
@ExcelStyle(name = "a", bold = Toggle.TRUE)
@ExcelStyle(name = "b", italic = Toggle.TRUE)

@ExcelStyles({@ExcelStyle(name = "a", bold = Toggle.TRUE), @ExcelStyle(name = "b", italic = Toggle.TRUE)})

`@ExcelStyleSheet`

Marks a style sheet: a class that holds named styles shared by several sheet classes. It has no attributes.

A style sheet carries this annotation and @ExcelStyle declarations. Its fields, methods and other annotations play no role. A final class with a private constructor is the usual form.
Sheet classes reference it in @ExcelSheet.styleSheets and can then use its styles by name.
Only classes carrying this annotation can be referenced (V-09).
Style names must be unique within the style sheet (V-07). Errors on a style of a style sheet name the style sheet class, not the sheet class.
The style sheets referenced by one sheet class must not declare the same name (V-08).
A style declared on the sheet class wins over a style with the same name from a style sheet, and replaces it entirely.

@ExcelStyleSheet
@ExcelStyle(name = "header", bold = Toggle.TRUE, fillColor = "#1F4E79", fontColor = "#FFFFFF")
@ExcelStyle(name = "zebra", fillColor = "#EEF3F8")
public final class CorporateStyles {
    private CorporateStyles() {
    }
}

`@HeaderStyles`

Header slots, usable only as the value of @ExcelSheet.header. Every attribute is the name of a named style; empty means no style.

Attribute	Default	Cascade level	Applies to
`base`	`""`	2	every header cell
`lastColumn`	`""`	4, before `firstColumn`	the header cell of the last column
`firstColumn`	`""`	4, after `lastColumn`	the header cell of the first column

Rules:

With one column, its header cell is both first and last, and firstColumn wins over lastColumn.
The frame sits below firstColumn, lastColumn and the column headerStyle.
The column headerStyle is the most specific level of the header.
Header slots never apply to data cells.

Validation: V-06 for a name that does not exist (element @ExcelSheet, slot header.base, header.firstColumn or header.lastColumn).

@ExcelSheet(header = @HeaderStyles(base = "header", firstColumn = "header-left", lastColumn = "header-right"))

`@BodyStyles`

Body slots at table level, usable only as the value of @ExcelSheet.body.

Attribute	Default	Cascade level	Applies to
`base`	`""`	2	every data cell
`odd`	`""`	3	data cells of rows 1, 3, 5, …
`even`	`""`	3	data cells of rows 2, 4, 6, …
`lastColumn`	`""`	5, before `firstColumn`	data cells of the last column
`firstColumn`	`""`	5, after `lastColumn`	data cells of the first column
`lastRow`	`""`	6, before `firstRow`	data cells of the last data row
`firstRow`	`""`	6, after `lastRow`	data cells of the first data row

Rules:

Data rows are numbered from 1, so the first data row is odd.
The row wins over the column (level 6 after level 5).
The first wins over the last, for rows and for columns.
The frame sits below the row and column slots.
Column slots (@ColumnStyles) are more specific than every body slot.
Body slots never apply to the header or the title.

Validation: V-06 (element @ExcelSheet, slot body.base, body.odd, and so on).

@ExcelSheet(body = @BodyStyles(base = "cell", odd = "zebra", firstColumn = "key", lastRow = "total"))

`@ColumnStyles`

Body slots of one column, usable only as the value of @ExcelColumn.styles. Applied after every table level, in this order: base, odd or even, lastRow, then firstRow. Only the column format comes after them.

Attribute	Default	Applies to
`base`	`""`	every data cell of the column
`odd`	`""`	the cells of the column in odd data rows
`even`	`""`	the cells of the column in even data rows
`lastRow`	`""`	the cell of the column in the last data row
`firstRow`	`""`	the cell of the column in the first data row; wins over `lastRow` with one data row

Column slots have no first and last column attributes, because the column is a single column. They never apply to the header cell of the column, which is styled by @ExcelColumn.headerStyle.

Validation: V-06 (element: the field name, slot styles.base, styles.odd, and so on).

@ExcelColumn(header = "Amount", order = 40, styles = @ColumnStyles(base = "money", lastRow = "money-total"))
BigDecimal amount;