CellStyleCollection Class

Namespace:
GemBox.Spreadsheet
Assembly:
GemBox.Spreadsheet.dll

Represents a collection of workbook (master) Styles.

public sealed class CellStyleCollection : IEnumerable<Style>, IEnumerable
Public NotInheritable Class CellStyleCollection
    Implements IEnumerable(Of Style), IEnumerable
Inheritance:
System.Object
CellStyleCollection
Implements
System.Collections.Generic.IEnumerable<Style>
System.Collections.IEnumerable
Remarks

Conceptually, cell formatting is divided into following groups:

  • Number - indicates how to format and render the numeric value of a cell. Associated property is NumberFormat.
  • Alignment - formatting information pertaining to text alignment in cells. Associated properties are HorizontalAlignment, VerticalAlignment, Indent, Rotation, IsTextVertical, WrapText and ShrinkToFit.
  • Font - defines the properties for the used font. Associated property is Font.
  • Border - expresses a single set of cell border formats (left, right, top, bottom and diagonal). Associated property is Borders.
  • Fill - specifies fill formatting (pattern or gradient). Associated property is FillPattern.
  • Protection - contains protection properties associated with the cell. Associated properties are Locked and FormulaHidden.

Additional CellStyle properties not associated with any formatting group are:

  • Name - name of the referenced Style.
  • QuotePrefix - true to store numeric value of a cell as text; otherwise, false.
  • IsDefault - true if Name Style is default (Normal) and there are no additional modifications of cell formatting; otherwise, false.

ExcelFile contains a set of Styles which can be referenced by multiple cells.

ExcelFile must always contain at least one Style which cannot be removed and is, by default, referenced by all cells. This default style is Normal.

Style can either be built-in or user-defined. Built-in style is accessible from Styles via BuiltInCellStyleName enumeration.

Cell formatting group (Number, Alignment, Font, Border, Fill or Protection) (and its associated properties) is resolved from Name Style, unless cell formatting group or its associated property is modified.

Cell formatting is available for one or more cells through Style property which is available on ExcelCell and CellRange types. Cell formatting specified on ExcelColumn and ExcelRow types through Style property is simply propagated to cell formatting of its Cells.

note

For performance reasons, cell formatting on CellRange is resolved based just on its top-left cell formatting, except borders which are resolved based on corner cells depending on border side.

Setting cell formatting property on CellRange is propagated to each cell in a range.

To set Style to one or more cells, simply assign it to Style property.

tip

Preferable way to modify formatting property of multiple cells is to get CellRange to which all those cells belong, and use Style property of that range to make the modification.

If modifying multiple formatting properties of a CellRange, without preserving unmodified formatting properties, preferable way is to create new instance of CellStyle, make modifications on it, and assign it to Style property of that range.

GemBox.Spreadsheet internally takes care not to allocate unnecessary cells when formatting a range of cells (for example, when formatting Cells) and to cache formatting information of equally formatted cells, at the appropriate time, to reduce memory footprint.

Properties

Count

Gets the number of Styles contained in the collection.

public int Count { get; }
Public ReadOnly Property Count As Integer
Property Value
System.Int32

Item[BuiltInCellStyleName]

Gets the Style that corresponds to given BuiltInCellStyleName.

If CellStyleCollection doesn't contain correspondent style, then new style will be added and returned.

public Style this[BuiltInCellStyleName styleName] { get; }
Public ReadOnly Property Item(styleName As BuiltInCellStyleName) As Style
Parameters
styleName
BuiltInCellStyleName
Property Value
Style

Style that corresponds to given BuiltInCellStyleName.

Item[String]

Gets the Style that corresponds to given name.

If CellStyleCollection doesn't contain correspondent style, then new style will be added and returned.

public Style this[string styleName] { get; }
Public ReadOnly Property Item(styleName As String) As Style
Parameters
styleName
System.String

The name of the Style.

Property Value
Style

Style that corresponds to given name.

Normal

Gets the 'Normal' style.

public Style Normal { get; }
Public ReadOnly Property Normal As Style
Property Value
Style

The 'Normal' style.

Remarks

The 'Normal' style always exists in a workbook and it cannot be removed.

The 'Normal' style stores default cell formatting properties for an entire workbook, because all cells will reference the 'Normal' style by default.

Methods

Add(String)

Adds an empty Style instance to the CellStyleCollection.

public Style Add(string name)
Public Function Add(name As String) As Style
Parameters
name
System.String

The name of new Style instance.

Returns
Style

New Style instance that is added to this collection.

Exceptions
System.ArgumentException

Parameter name cannot be null or empty.

System.InvalidOperationException

Style with name name is already contained in the workbook.

Contains(String)

Determines whether the CellStyleCollection contains a Style instance with specific name.

public bool Contains(string styleName)
Public Function Contains(styleName As String) As Boolean
Parameters
styleName
System.String

Name of the Style to locate in the CellStyleCollection.

Returns
System.Boolean

true if Style instance with specific name is found in the CellStyleCollection; otherwise, false.

GetEnumerator()

Returns an enumerator that iterates through the CellStyleCollection.

public IEnumerator<Style> GetEnumerator()
Public Function GetEnumerator As IEnumerator(Of Style)
Returns
System.Collections.Generic.IEnumerator<Style>

A System.Collections.Generic.IEnumerator<T> that can be used to iterate through the CellStyleCollection.

Remove(BuiltInCellStyleName)

Removes built-in style with the specified name from the workbook.

public bool Remove(BuiltInCellStyleName name)
Public Function Remove(name As BuiltInCellStyleName) As Boolean
Parameters
name
BuiltInCellStyleName

The name of the built-in style which should be removed from the workbook.

Returns
System.Boolean

true if style is successfully removed; otherwise, false. This method also returns false if style was not found in the workbook.

Exceptions
System.InvalidOperationException

'Normal' style cannot be removed from the workbook.

Remove(String)

Removes style with the specified name from the workbook.

public bool Remove(string name)
Public Function Remove(name As String) As Boolean
Parameters
name
System.String

The name of the style which should be removed from the workbook.

Returns
System.Boolean

true if style is successfully removed; otherwise, false. This method also returns false if style was not found in the workbook.

Exceptions
System.InvalidOperationException

'Normal' style cannot be removed from the workbook.

Implements

System.Collections.Generic.IEnumerable<T>
System.Collections.IEnumerable

See Also